diff --git a/README.md b/README.md index a8b97bd0..ad14b0db 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # emissary-ingress.dev -The [emissary-ingress.dev][] website, built using [Hugo][] and hosted on [Netlify][]. +The [emissary-ingress.dev](https://emissary-ingress.dev) website, built using [Hugo][] and hosted on [Netlify][]. ## Local build diff --git a/content/en/docs/2.5/about/_index.md b/content/en/docs/2.5/about/_index.md new file mode 100644 index 00000000..0ba607e7 --- /dev/null +++ b/content/en/docs/2.5/about/_index.md @@ -0,0 +1,4 @@ +--- +title: "About" +weight: 10 +--- diff --git a/content/en/docs/2.5/about/aes-emissary-eol.md b/content/en/docs/2.5/about/aes-emissary-eol.md deleted file mode 100644 index 59dfbeed..00000000 --- a/content/en/docs/2.5/about/aes-emissary-eol.md +++ /dev/null @@ -1,56 +0,0 @@ -# Ambassador Edge Stack and Emissary-ingress 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/content/en/docs/2.5/about/alternatives.md b/content/en/docs/2.5/about/alternatives.md index bafec087..b3bc2e7d 100644 --- a/content/en/docs/2.5/about/alternatives.md +++ b/content/en/docs/2.5/about/alternatives.md @@ -1,6 +1,8 @@ -# $productName$ vs. other software +--- +title: "Alternatives" +--- -Alternatives to $productName$ fall into three basic categories: +Alternatives to Emissary fall into three basic categories: * Hosted API gateways, such as the [Amazon API gateway](https://aws.amazon.com/api-gateway/). * Traditional API gateways, such as [Kong](https://konghq.org/). @@ -12,8 +14,8 @@ Both hosted API gateways and traditional API gateways are: * Not Kubernetes-native. They're typically configured using REST APIs, making it challenging to adopt cloud-native patterns such as GitOps and declarative configuration. * [Designed for API management, rather than designed for microservices](../../topics/concepts/microservices-api-gateways). -A Layer 7 proxy can be used as an API gateway, but typically requires additional bespoke development to support microservices use cases. In fact, many API gateways package the additional features needed for an API gateway on top of an L7 proxy. $productName$ uses Envoy, while Kong uses NGINX. If you're interested in deploying Envoy directly, we've written an [introductory tutorial](https://www.datawire.io/guide/traffic/getting-started-lyft-envoy-microservices-resilience/). +A Layer 7 proxy can be used as an API gateway, but typically requires additional bespoke development to support microservices use cases. In fact, many API gateways package the additional features needed for an API gateway on top of an L7 proxy. Emissary uses Envoy, while Kong uses NGINX. If you're interested in deploying Envoy directly, we've written an [introductory tutorial](https://www.datawire.io/guide/traffic/getting-started-lyft-envoy-microservices-resilience/). ## Istio -[Istio](https://istio.io) is an open-source service mesh, built on Envoy. A service mesh is designed to manage East/West traffic (traffic between servers and your data center), while an API gateway manages North/South traffic (in and out of your data center). Documentation on how to deploy $productName$ with Istio is [here](../../howtos/istio). In general, we've found that North/South traffic is quite different from East/West traffic (i.e., you don't control the client in the North/South use case). +[Istio](https://istio.io) is an open-source service mesh, built on Envoy. A service mesh is designed to manage East/West traffic (traffic between servers and your data center), while an API gateway manages North/South traffic (in and out of your data center). Documentation on how to deploy Emissary with Istio is [here](../../howtos/istio). In general, we've found that North/South traffic is quite different from East/West traffic (i.e., you don't control the client in the North/South use case). diff --git a/content/en/docs/2.5/about/changes-2.x.md b/content/en/docs/2.5/about/changes-2.x.md index 389cc89b..bb7312a8 100644 --- a/content/en/docs/2.5/about/changes-2.x.md +++ b/content/en/docs/2.5/about/changes-2.x.md @@ -1,28 +1,27 @@ -import Alert from '@material-ui/lab/Alert'; - -Major Changes in $productName$ 2.X -================================== +--- +title: Major Changes in Emissary 2.X +--- -The 2.X family introduces a number of changes to allow $productName$ +The 2.X family introduces a number of changes to allow Emissary 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 +While Emissary 2 is functionally compatible with Emissary 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. +Emissary 1.X and Emissary $version$. For details, read on. ## 1. Configuration API Version `getambassador.io/v3alpha1` -$productName$ 2.0 introduced API version `getambassador.io/v3alpha1` to allow +Emissary 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 +Emissary 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. - $productName$ 2.X supports only API versions getambassador.io/v2 + Emissary 2.X supports only API versions getambassador.io/v2 and getambassador.io/v3alpha1. If you are using any resources with older API versions, you will need to upgrade them. @@ -47,15 +46,15 @@ either a string or a list of strings is not allowed. Several such elements appea ## 2. `Listener`s, `Host`s, and `Mapping`s -$productName$ 2.0 introduced the new **mandatory** `Listener` CRD, and made some changes +Emissary 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. +The new [`Listener` CRD](../../topics/running/listener) defines where and how Emissary 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 +**Note that `Listener`s are never created by Emissary, and must be defined by the user.** If you do not +define any `Listener`s, Emissary 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 @@ -82,7 +81,7 @@ spec: 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$. +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 Emissary. 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. @@ -93,11 +92,11 @@ Note also that there is no limit on how many `Listener`s may be created, and as ### 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 +In Emissary 1.X, Emissary would make sure that a wildcard `Host`, with a `hostname` of `"*"`, was always present. +Emissary 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 +Of particular note is that Emissary **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: @@ -114,7 +113,7 @@ Adding a `Host` with a `hostname` of `"*"` will allow the second query to work. 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: +However, as of Emissary 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. @@ -145,7 +144,7 @@ Each `Host` can specify its `requestPolicy.insecure.action` independently of any ### `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. +As of Emissary 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: @@ -168,7 +167,7 @@ spec: 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). +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 Emissary Communications](../../howtos/configure-communications). Learn more about Host.
@@ -197,15 +196,15 @@ for compatibility with Kubernetes 1.22. ### 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). In $productName$ +By default, Emissary 2.X will configure Envoy using the +[V3 Envoy API](https://www.envoyproxy.io/docs/envoy/latest/api-v3/api). In Emissary 2.X, you may switch back to Envoy V2 by setting the `AMBASSADOR_ENVOY_API_VERSION` -environment variable to "V2"; in $productName$ 3.X, support for the Envoy V2 API (and +environment variable to "V2"; in Emissary 3.X, support for the Envoy V2 API (and the `AMBASSADOR_ENVOY_API_VERSION` environment variable) will be removed. ### 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. +In Emissary 1.X, the environment variable `AMBASSADOR_FAST_RECONFIGURE` could be used to enable a higher performance implementation of the code Emissary uses to validate and generate Envoy configuration. In Emissary 2.X, this higher-performance mode is always enabled. ### Changes to the `ambassador` `Module`, and the `tls` `Module` @@ -213,7 +212,7 @@ It is no longer possible to configure TLS using the `tls` element of the `ambass 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). +Configuration for the `PROXY` protocol is part of the `Listener` resource in Emissary 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. @@ -223,16 +222,16 @@ Configuration for the `PROXY` protocol is part of the `Listener` resource in $pr ### `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). +`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 Emissary 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. +Service Preview is no longer supported as of Emissary 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. +The Edge Policy Console has been removed as of Emissary 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. +The `Project` CRD has been removed as of Emissary 2.X, in favor of Argo. diff --git a/content/en/docs/3.4/about/aes-emissary-eol.md b/content/en/docs/2.5/about/emissary-eol.md similarity index 98% rename from content/en/docs/3.4/about/aes-emissary-eol.md rename to content/en/docs/2.5/about/emissary-eol.md index 6afc3142..8a40b4e1 100644 --- a/content/en/docs/3.4/about/aes-emissary-eol.md +++ b/content/en/docs/2.5/about/emissary-eol.md @@ -1,4 +1,6 @@ -# $productName$ End of Life Policy +--- +title: Emissary 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. diff --git a/content/en/docs/2.5/about/faq.md b/content/en/docs/2.5/about/faq.md index 513c75c5..67796d55 100644 --- a/content/en/docs/2.5/about/faq.md +++ b/content/en/docs/2.5/about/faq.md @@ -1,56 +1,58 @@ -# Frequently Asked Questions +--- +title: Frequently Asked Questions +--- ## General -### Why $productName$? +### Why Emissary? Kubernetes shifts application architecture for microservices, as well as the -development workflow for a full-cycle development. $productName$ is designed for +development workflow for a full-cycle development. Emissary 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. * 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/). +We've written about [the history of Emissary](https://blog.getambassador.io/building-ambassador-an-open-source-api-gateway-on-kubernetes-and-envoy-ed01ed520844), [Why Emissary 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$? +### What's the difference between Emissary and Ambassador Edge Stack? -$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. +Emissary is a CNCF Incubating project and provides the open-source core of Ambassador Edge Stack. Originally we called Emissary 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 Ambassador Edge Stack 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? +### How is Ambassador Edge Stack 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. +The core Emissary 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 Ambassador Edge Stack (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? +### Can I use the add-on features for Ambassador Edge Stack for free? -Yes! The core functionality of the $AESproductName$ is free and has no limits whatsoever. If you wish to use one of our additional, proprietary features such as Single Sign-On, you can get a free community license for up to 5 requests per second by registering your connected $AESproductName$ installation in [Ambassador Cloud](https://app.getambassador.io/cloud/). Please contact [sales](/contact-us/) if you need more than 5 RPS. +Yes! The core functionality of the Ambassador Edge Stack is free and has no limits whatsoever. If you wish to use one of our additional, proprietary features such as Single Sign-On, you can get a free community license for up to 5 requests per second by registering your connected Ambassador Edge Stack installation in [Ambassador Cloud](https://app.getambassador.io/cloud/). Please contact [sales](/contact-us/) if you need more than 5 RPS. For more details on core unlimited features and premium features, see the [editions page](/editions). -### How does $productName$ use Envoy Proxy? +### How does Emissary 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. +Emissary 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? +### Is Emissary production ready? [//]: # (+FIX+ Check for OSS) -Yes. Thousands of organizations, large and small, run $productName$ in production. +Yes. Thousands of organizations, large and small, run Emissary in production. Public users include Chick-Fil-A, ADP, Microsoft, NVidia, and AppDirect, among others. -### What is the performance of $productName$? +### What is the performance of Emissary? -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. +There are many dimensions to performance. We published a benchmark of [Emissary 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$? +### What's the difference between a service mesh (such as Istio) and Emissary? [//]: # (+FIX+ Check for OSS) 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, +("east-west"). Emissary focuses on traffic into your cluster ("north-south"). +While both a service mesh and Emissary can route L7 traffic, the reality is that +these use cases are quite different. Many users will integrate Emissary with a +service mesh. Production customers of Emissary have integrated with Consul, Istio, and Linkerd2. ## Common Configurations @@ -61,7 +63,7 @@ See the [Protecting the Diagnostics Interface](../../howtos/protecting-diag-acce ## Troubleshooting -### How do I get help for $productName$? +### How do I get help for Emissary? 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 @@ -70,10 +72,10 @@ 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. +This error means that Emissary 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 +Emissary 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 +Emissary. In general, verifying each network hop between your client and backend service is critical to finding the source of the problem. diff --git a/content/en/docs/2.5/about/features-and-benefits.md b/content/en/docs/2.5/about/features-and-benefits.md index a25d7752..c418cd36 100644 --- a/content/en/docs/2.5/about/features-and-benefits.md +++ b/content/en/docs/2.5/about/features-and-benefits.md @@ -1,43 +1,45 @@ -# Features and benefits +--- +title: 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). +In cloud-native organizations, developers frequently take on responsibility for the full development lifecycle of a service, from development to QA to operations. Emissary 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. +As such, the Emissary 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. +Emissary 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 [//]: # (+FIX+ Forge is no more) -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$. +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. Emissary 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 Emissary. ## Kubernetes-native architecture [//]: # (+FIX+ we've come to realize that it's better to scale vertically) -$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/). +Emissary relies entirely on Kubernetes for reliability, availability, and scalability. For example, Emissary persists all state in Kubernetes, instead of requiring a separate database. Scaling the Emissary 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. +Emissary 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. +Emissary fully supports gRPC and HTTP/2 routing, thanks to Envoy's extensive capabilities in this area. See [gRPC and Emissary](../../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. +Emissary integrates with the [Istio](https://istio.io) service mesh as the edge proxy. In this configuration, Emissary routes external traffic to the internal Istio service mesh. See [Istio and Emissary](../../howtos/istio) for details. ## Authentication -$productName$ supports authenticating incoming requests using a custom authentication service. When configured, the $productName$ will check with your external authentication service prior to routing an incoming request. For more information, see the [authentication guide](../../topics/running/services/auth-service). +Emissary supports authenticating incoming requests using a custom authentication service. When configured, the Emissary will check with your external authentication service prior to routing an incoming request. For more information, see the [authentication guide](../../topics/running/services/auth-service). ## 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/). +Emissary supports rate limiting incoming requests. When configured, the Emissary 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). +Emissary includes a diagnostics service so that you can quickly debug issues associated with configuring the Emissary. For more information, see [running Emissary in Production](../../topics/running). diff --git a/content/en/docs/2.5/about/known-issues.md b/content/en/docs/2.5/about/known-issues.md index 6b89c65a..74cbc459 100644 --- a/content/en/docs/2.5/about/known-issues.md +++ b/content/en/docs/2.5/about/known-issues.md @@ -1,9 +1,8 @@ -import Alert from '@material-ui/lab/Alert'; - -Known Issues in $productName$ -============================= +--- +title: Known Issues +--- ## 2.2.1 - TLS certificates using elliptic curves were incorrectly flagged as invalid. This issue is - corrected in $productName$ 2.2.2. + corrected in Emissary 2.2.2. diff --git a/content/en/docs/2.5/about/support.md b/content/en/docs/2.5/about/support.md index 11927f95..85d9df15 100644 --- a/content/en/docs/2.5/about/support.md +++ b/content/en/docs/2.5/about/support.md @@ -1,22 +1,24 @@ -# Need help? +--- +title: Support +--- -If you need help deploying $productName$ at your organization, there are several different options available to you. +If you need help deploying Emissary at your organization, there are several different options available to you. ## Support tiers -### $productName$ community support +### Emissary community support -When running $OSSproductName$, or $AESproductName$ with free community licenses, [join our Slack channel](http://a8r.io/slack) to talk with other users in the community and get your questions answered. +When running Emissary, or Ambassador Edge Stack with free community licenses, [join our Slack channel](http://a8r.io/slack) to talk with other users in the community and get your questions answered. -If you can’t find an answer there, [contact us](/contact-us) to learn more about the support options available with $AESproductName$ Enterprise. +If you can’t find an answer there, [contact us](/contact-us) to learn more about the support options available with Ambassador Edge Stack Enterprise. -### $AESproductName$ Enterprise +### Ambassador Edge Stack Enterprise -With $AESproductName$ Enterprise, you have access to deployment and production support. To learn more, [contact sales](/contact-us). +With Ambassador Edge Stack Enterprise, you have access to deployment and production support. To learn more, [contact sales](/contact-us). -**Deployment and Update Support**: $AESproductName$ can accelerate your migration to Kubernetes, or your upgrade between versions of $AESproductName$. Deployment support helps you with the $AESproductName$ and Kubernetes migration, before you move to production. +**Deployment and Update Support**: Ambassador Edge Stack can accelerate your migration to Kubernetes, or your upgrade between versions of Ambassador Edge Stack. Deployment support helps you with the Ambassador Edge Stack and Kubernetes migration, before you move to production. -**Production Support**: We offer two types of production support contracts for users deploying the $AESproductName$ in production. We offer both business hour (8am - 5pm EST, M-F) and 24x7 Sev 1 support for the $AESproductName$. 24x7 Sev 1 support includes custom hotfix support for production outages if necessary. +**Production Support**: We offer two types of production support contracts for users deploying the Ambassador Edge Stack in production. We offer both business hour (8am - 5pm EST, M-F) and 24x7 Sev 1 support for the Ambassador Edge Stack. 24x7 Sev 1 support includes custom hotfix support for production outages if necessary. ## File a Github Issue diff --git a/content/en/docs/2.5/about/why-ambassador.md b/content/en/docs/2.5/about/why-ambassador.md index 0d343983..d1b0d929 100644 --- a/content/en/docs/2.5/about/why-ambassador.md +++ b/content/en/docs/2.5/about/why-ambassador.md @@ -1,10 +1,12 @@ -# Why $productName$? +--- +title: Why Emissary? +--- -$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)). +Emissary 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, Emissary is made to support multiple, independent teams that need to rapidly publish, monitor, and update services for end-users. A true edge stack, Emissary 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? +## How Does Emissary work? -$productName$ is an open-source, Kubernetes-native [microservices API gateway](../../topics/concepts/microservices-api-gateways) built on 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)). +Emissary is an open-source, Kubernetes-native [microservices API gateway](../../topics/concepts/microservices-api-gateways) built on the [Envoy Proxy](https://www.envoyproxy.io). Emissary is built from the ground up to support multiple, independent teams that need to rapidly publish, monitor, and update services for end-users. Emissary 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 @@ -16,15 +18,15 @@ Traditional cloud applications were built using a monolithic approach. These app ### Heterogeneous services -$productName$ is commonly used to route traffic to a wide variety of services. It supports: +Emissary 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$. +* Can route raw TCP for services that use protocols not directly supported by Emissary. ### 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$: +Service updates result in a constantly changing application. The dynamic nature of cloud-native applications introduces new challenges around configuration updates, release, and testing. Emissary: * 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. @@ -32,23 +34,23 @@ Service updates result in a constantly changing application. The dynamic nature ### 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: +Independent teams can create their own workflows for developing and releasing functionality that are optimized for their specific service(s). With Emissary, 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. +* Independently configure different aspects of Emissary, eliminating the need to request configuration changes through a centralized operations team. -## $productName$ is engineered for Kubernetes +## Emissary is engineered for Kubernetes -$productName$ takes full advantage of Kubernetes and Envoy Proxy. +Emissary 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. +* All of the state required for Emissary is stored directly in Kubernetes, eliminating the need for an additional database. +* The Emissary 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). +[Deploy Emissary 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) +* [Why did we start building Emissary?](https://blog.getambassador.io/building-ambassador-an-open-source-api-gateway-on-kubernetes-and-envoy-ed01ed520844) +* [Emissary Architecture overview](../../topics/concepts/architecture) diff --git a/content/en/docs/2.5/community.md b/content/en/docs/2.5/community.md index 759e4f0e..a2e08eb0 100644 --- a/content/en/docs/2.5/community.md +++ b/content/en/docs/2.5/community.md @@ -1,4 +1,7 @@ -# Community +--- +title: Community +weight: 50 +--- ## Contributor's guide Please review our [contributor's guide](https://github.com/emissary-ingress/emissary/blob/master/DEVELOPING.md) diff --git a/content/en/docs/2.5/doc-links.yml b/content/en/docs/2.5/doc-links.yml deleted file mode 100644 index 2fef59dc..00000000 --- a/content/en/docs/2.5/doc-links.yml +++ /dev/null @@ -1,228 +0,0 @@ - - title: Quick start - link: /tutorials/getting-started - - title: Install $productName$ - 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: Core concepts - link: /topics/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: How do I... - items: - - title: Route to my services - items: - - title: Configuring $productName$ Communications - link: /howtos/configure-communications - - title: Get traffic from the edge - link: /howtos/route - - title: Other protocols - items: - - title: TCP connections - link: /topics/using/tcpmappings - - title: gRPC connections - link: /howtos/grpc - - title: WebSocket connections - link: /howtos/websockets - - title: Protect my services - items: - - title: Authentication - items: - - title: Basic authentication with $productName$ - link: /howtos/basic-auth - - title: Rate limiting - items: - - title: Basic rate limiting with $productName$ - link: /howtos/rate-limiting-tutorial - - title: Monitor my services - 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: Monitoring with Prometheus and Grafana - link: /howtos/prometheus - - title: Statistics - link: /topics/running/statistics - items: - - title: Envoy statistics with StatsD - link: /topics/running/statistics/envoy-statsd - - title: The metrics endpoint - link: /topics/running/statistics/8877-metrics - - title: Set up integrations - items: - - title: Knative Serverless Framework - link: /howtos/knative - - title: ExternalDNS integration - link: /howtos/external-dns - - title: Service meshes - items: - - 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 - items: - - title: TLS - link: /topics/running/tls/ - items: - - 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: The Listener resource - link: /topics/running/listener - - title: The Module resource - link: /topics/running/ambassador - - title: Deploying $productName$ - items: - - title: Deployment architecture - link: /topics/running/ambassador-deployment - - title: $productName$ environment variables and ports - link: /topics/running/environment - - 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: Edge policy management - items: - - title: Gateway API - link: /topics/using/gateway-api - - title: Ingress and load balancing - items: - - title: The Mapping resource - items: - - title: Mapping basics - link: /topics/using/intro-mappings - - title: Advanced Mapping configuration - link: /topics/using/mappings - - 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: Headers - link: /topics/using/headers/headers - items: - - 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: 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: 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: 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: Rate limiting - items: - - title: Basic rate limiting - link: /topics/using/rate-limits/ - - title: TLS - items: - - 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: End of Life Policy - link: /about/aes-emissary-eol - - title: Changes in $productName$ 2.X - link: /about/changes-2.x - - title: Known issues - link: /about/known-issues - - title: FAQs - link: /about/faq - - title: Community - link: /community - - title: Troubleshooting - link: /topics/running/debugging - - title: Release Notes - link: /release-notes - - title: Licenses - link: licenses - - title: EOL Policy - link: /about/aes-emissary-eol diff --git a/content/en/docs/2.5/howtos/_index.md b/content/en/docs/2.5/howtos/_index.md new file mode 100644 index 00000000..b4fc2da6 --- /dev/null +++ b/content/en/docs/2.5/howtos/_index.md @@ -0,0 +1,28 @@ +--- +title: "How-to guides" +weight: 20 +--- + +These guides are designed to help users quickly accomplish common tasks. The guides assume a certain level of understanding of Emissary. Many of these guides are contributed by third parties; we welcome contributions via Pull Request at https://github.com/emissary-ingress/emissary. + +* Integrating with Service Mesh. Emissary natively integrates with many service meshes. + * [HashiCorp Consul](consul) + * [Istio](istio) + * [Linkerd](linkerd2) +* Distributed tracing. Emissary natively supports a number of distributed tracing systems to enable developers to visualize request flow in microservice and service-oriented architectures. + * [Datadog](tracing-datadog) + * [Zipkin](tracing-zipkin) +* Monitoring. Emissary integrates with a number of different monitoring/metrics providers. + * [Prometheus](prometheus) +* [Developing Custom Filters](filter-dev-guide) +* Frameworks and Protocols. Emissary supports a wide range of protocols and cloud-native frameworks. + * [gRPC](grpc) + * [Knative Serverless Framework](knative) + * [WebSockets](websockets) +* Security. Emissary supports a number of strategies for securing Kubernetes services. + * [Protecting the Diagnostics Interface](protecting-diag-access) + * [HTTPS and TLS termination](tls-termination) + * [Certificate Manager](cert-manager) can be used to automatically obtain and renew TLS certificates; Ambassador Edge Stack natively integrates this functionality. + * [Client Certificate Validation](client-cert-validation) + * [Basic Authentication](basic-auth) is a tutorial on how to use the external authentication API to code your own authentication service. + * [Basic Rate Limiting](rate-limiting-tutorial) diff --git a/content/en/docs/2.5/howtos/basic-auth.md b/content/en/docs/2.5/howtos/basic-auth.md index 70ce27ce..c59cad2f 100644 --- a/content/en/docs/2.5/howtos/basic-auth.md +++ b/content/en/docs/2.5/howtos/basic-auth.md @@ -1,28 +1,22 @@ -import Alert from '@material-ui/lab/Alert'; - -# Basic authentication (for $productName$) - -[//]: # (+FIX+ link to "authentication and authorization" concept) - - - This guide applies to $OSSproductName$, use of this guide with $AESproductName$ is not supported. $AESproductName$ does authentication using the Filter resource instead of the AuthService resource as described below. - +--- +title: Basic Authentication +--- -$productName$ can authenticate incoming requests before routing them to a backing -service. In this tutorial, we'll configure $productName$ to use an external third +Emissary can authenticate incoming requests before routing them to a backing +service. In this tutorial, we'll configure Emissary to use an external third party authentication service. We're assuming also that you are running the quote application in your cluster as described in the -[$productName$ tutorial](../../tutorials/quickstart-demo/). +[Emissary tutorial](../../tutorials/quickstart-demo/). ## Before you get started -This tutorial assumes you have already followed the $productName$ [Installation](../../topics/install/) guide. If you haven't done that already, you should do so now. +This tutorial assumes you have already followed the Emissary [Installation](../../topics/install/) guide. If you haven't done that already, you should do so now. -Once complete, you'll have a Kubernetes cluster running $productName$. Let's walk through adding authentication to this setup. +Once complete, you'll have a Kubernetes cluster running Emissary. Let's walk through adding authentication to this setup. ## 1. Deploy the authentication service -$productName$ delegates the actual authentication logic to a third party authentication service. We've written a [simple authentication service](https://github.com/datawire/ambassador-auth-service) that: +Emissary delegates the actual authentication logic to a third party authentication service. We've written a [simple authentication service](https://github.com/datawire/ambassador-auth-service) that: - listens for requests on port 3000; - expects all URLs to begin with `/extauth/`; @@ -30,7 +24,7 @@ $productName$ delegates the actual authentication logic to a third party authent - accepts only user `username`, password `password`; and - makes sure that the `x-qotm-session` header is present, generating a new one if needed. -$productName$ routes _all_ requests through the authentication service: it relies on the auth service to distinguish between requests that need authentication and those that do not. If $productName$ cannot contact the auth service, it will return a 503 for the request; as such, **it is very important to have the auth service running before configuring $productName$ to use it.** +Emissary routes _all_ requests through the authentication service: it relies on the auth service to distinguish between requests that need authentication and those that do not. If Emissary cannot contact the auth service, it will return a 503 for the request; as such, **it is very important to have the auth service running before configuring Emissary to use it.** Here's the YAML we'll start with: @@ -78,7 +72,7 @@ spec: memory: 100Mi ``` -Note that the cluster does not yet contain any $productName$ AuthService definition. This is intentional: we want the service running before we tell $productName$ about it. +Note that the cluster does not yet contain any Emissary AuthService definition. This is intentional: we want the service running before we tell Emissary about it. The YAML above is published at getambassador.io, so if you like, you can just do @@ -97,9 +91,9 @@ example-auth-6c5855b98d-24clp 1/1 Running 0 4m ``` Note that the `READY` field says `1/1` which means the pod is up and running. -## 2. Configure $productName$ authentication +## 2. Configure Emissary authentication -Once the auth service is running, we need to tell $productName$ about it. The easiest way to do that is point it to the `example-auth` service with the following: +Once the auth service is running, we need to tell Emissary about it. The easiest way to do that is point it to the `example-auth` service with the following: ```yaml --- @@ -116,7 +110,7 @@ spec: - "x-qotm-session" ``` -This configuration tells $productName$ about the auth service, notably that it needs the `/extauth` prefix, and that it's OK for it to pass back the `x-qotm-session` header. Note that `path_prefix` and `allowed_*_headers` are optional. +This configuration tells Emissary about the auth service, notably that it needs the `/extauth` prefix, and that it's OK for it to pass back the `x-qotm-session` header. Note that `path_prefix` and `allowed_*_headers` are optional. If the auth service uses a framework like [Gorilla Toolkit](http://www.gorillatoolkit.org) which enforces strict slashes as HTTP path separators, it is possible to end up with an infinite redirect where the auth service's framework redirects any request with non-conformant slashing. This would arise if the above example had `path_prefix: "/extauth/"`, the auth service would see a request for `/extauth//backend/get-quote/` which would then be redirected to `/extauth/backend/get-quote/` rather than actually be handled by the authentication handler. For this reason, remember that the full path of the incoming request including the leading slash, will be appended to `path_prefix` regardless of non-conformant slashing. @@ -128,7 +122,7 @@ kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/demo/dem or, again, apply it from a local file if you prefer. -Note that the cluster does not yet contain any $productName$ AuthService definition. +Note that the cluster does not yet contain any Emissary AuthService definition. ## 3. Test authentication diff --git a/content/en/docs/2.5/howtos/cert-manager.md b/content/en/docs/2.5/howtos/cert-manager.md index 975dd3ff..55f82717 100644 --- a/content/en/docs/2.5/howtos/cert-manager.md +++ b/content/en/docs/2.5/howtos/cert-manager.md @@ -1,11 +1,11 @@ -# Using cert-manager +--- +title: Using cert-manager +--- -[//]: # (+FIX+ link to "TLS and certificates" concept) - -$AESproductName$ has simple and easy built-in support for automatically [using ACME] with the +Ambassador Edge Stack has simple and easy built-in support for automatically [using ACME] with the `http-01` challenge to create and renew TLS certificates. However, this support is not available -in $OSSproductName$, and it is limited to the ACME `http-01` challenge type. If you're running -$OSSproductName$, or if you require more flexible certificate management (such as using ACME's +in Emissary, and it is limited to the ACME `http-01` challenge type. If you're running +Emissary, or if you require more flexible certificate management (such as using ACME's `dns-01` challenge, or using a non-ACME certificate source), external certificate management tools are also supported. @@ -13,7 +13,7 @@ tools are also supported. One such tool is Jetstack's [cert-manager](https://github.com/jetstack/cert-manager), which is a general-purpose tool for managing certificates in Kubernetes. Cert-manager will automatically create and renew TLS certificates and store -them as Kubernetes secrets for easy use in a cluster. $productName$ will automatically watch for secret +them as Kubernetes secrets for easy use in a cluster. Emissary will automatically watch for secret changes and reload certificates upon renewal. > **Note:** This document assumes cert-manager v0.15 or greater. This document has been updated to use CRD standards diff --git a/content/en/docs/2.5/howtos/client-cert-validation.md b/content/en/docs/2.5/howtos/client-cert-validation.md index 10fe639d..7a2ec247 100644 --- a/content/en/docs/2.5/howtos/client-cert-validation.md +++ b/content/en/docs/2.5/howtos/client-cert-validation.md @@ -1,21 +1,21 @@ -# Client certificate validation - -[//]: # (+FIX+ link to "TLS and client certs" concept) +--- +title: Client certificate validation +--- Sometimes, for additional security or authentication purposes, you will want the server to validate who the client is before establishing an encrypted connection. -To support this, $productName$ can be configured to use a provided CA certificate +To support this, Emissary can be configured to use a provided CA certificate to validate certificates sent from your clients. This allows for client-side -mTLS where both $productName$ and the client provide and validate each other's +mTLS where both Emissary and the client provide and validate each other's certificates. ## Prerequisites - [openssl](https://www.openssl.org/source/) For creating client certificates - [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [$productName$](../../tutorials/getting-started) +- [Emissary](../../tutorials/getting-started) - [cURL](https://curl.haxx.se/download.html) @@ -30,7 +30,7 @@ certificates. ``` Enter a passcode for PEM files and fill in the certificate information. - Since this certificate will only be shared between a client and $productName$, + Since this certificate will only be shared between a client and Emissary, the Common Name must be set to something. Everything else can be left blank. **Note:** If using MacOS, @@ -55,7 +55,7 @@ certificates. kubectl create secret generic client-cacert --from-file=tls.crt=cert.pem ``` -3. Configure $productName$ to use this certificate for client certificate validation. +3. Configure Emissary to use this certificate for client certificate validation. First create a `Host` to manage your domain: @@ -84,14 +84,14 @@ certificates. - host.example.com secret: host.example.com ca_secret: client-cacert - cert_required: false # Optional: Configures $productName$ to reject the request if the client does not provide a certificate. Default: false + cert_required: false # Optional: Configures Emissary to reject the request if the client does not provide a certificate. Default: false ``` - **Note**: Client certificate validation requires $productName$ be configured to terminate TLS + **Note**: Client certificate validation requires Emissary be configured to terminate TLS - $productName$ is now be configured to validate certificates that the client provides. + Emissary is now be configured to validate certificates that the client provides. -4. Test that $productName$ is validating the client certificates with `curl` +4. Test that Emissary is validating the client certificates with `curl` **Linux**: ``` @@ -104,7 +104,7 @@ certificates. ``` Looking through the verbose output, you can see we are sending a client - certificate and $productName$ is validating it. + certificate and Emissary is validating it. If you need further proof, simply create a new set of certificates and - try sending the curl with those. You will see $productName$ deny the request. + try sending the curl with those. You will see Emissary deny the request. diff --git a/content/en/docs/2.5/howtos/configure-communications.md b/content/en/docs/2.5/howtos/configure-communications.md index 1ac09d2c..eb6462f1 100644 --- a/content/en/docs/2.5/howtos/configure-communications.md +++ b/content/en/docs/2.5/howtos/configure-communications.md @@ -1,25 +1,24 @@ -import Alert from '@material-ui/lab/Alert'; - -Configuring $productName$ Communications -======================================== +--- +title: Configuring Emissary Communications +--- -For $productName$ to do its job of managing network communications for your services, it first needs to know how its own communications should be set up. This is handled by a combination of resources: the `Listener`, the `Host`, and the `TLSContext`. +For Emissary to do its job of managing network communications for your services, it first needs to know how its own communications should be set up. This is handled by a combination of resources: the `Listener`, the `Host`, and the `TLSContext`. -- `Listener`: defines where, and how, $productName$ should listen for requests from the network. -- `Host`: defines which hostnames $productName$ should care about, and how to handle different kinds of requests for those hosts. `Host`s can be associated with one or more `Listener`s. -- `TLSContext`: defines whether, and how, $productName$ will manage TLS certificates and options. `TLSContext`s can be associated with one or more `Host`s. +- `Listener`: defines where, and how, Emissary should listen for requests from the network. +- `Host`: defines which hostnames Emissary should care about, and how to handle different kinds of requests for those hosts. `Host`s can be associated with one or more `Listener`s. +- `TLSContext`: defines whether, and how, Emissary will manage TLS certificates and options. `TLSContext`s can be associated with one or more `Host`s. -Once the basic communications setup is in place, $productName$ `Mapping`s and `TCPMapping`s can be associated with `Host`s to actually do routing. +Once the basic communications setup is in place, Emissary `Mapping`s and `TCPMapping`s can be associated with `Host`s to actually do routing. Remember that Listener and Host resources are  - required for a functioning $productName$ installation that can route traffic!
+ required for a functioning Emissary installation that can route traffic!
Learn more about Listener.
Learn more about Host. - Remember than $productName$ does not make sure that a wildcard Host exists! If the + Remember than Emissary does not make sure that a wildcard Host exists! If the wildcard behavior is needed, a Host with a hostname of "*" must be defined by the user. @@ -38,7 +37,7 @@ 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 +having trouble with TLS, always [check the logs] of your Emissary Pods and look for certificate errors. [TLS]: ../../topics/running/tls @@ -51,7 +50,7 @@ Examples / Cookbook ### Basic HTTP and HTTPS A useful configuration is to support either HTTP or HTTPS, in this case on either port 8080 or port 8443. This -tends to make it as easy as possible to communicate with the services behind the $productName$ instance. It uses +tends to make it as easy as possible to communicate with the services behind the Emissary instance. It uses two `Listener`s and at least one `Host`. @@ -172,13 +171,13 @@ spec: Learn more about Host -### TLS using ACME ($AESproductName$ only) +### TLS using ACME (Ambassador Edge Stack only) This scenario uses ACME to get certificates for `foo.example.com` and `bar.example.com`. HTTPS traffic to either host is routed; HTTP traffic to `foo.example.com` will be redirected to HTTPS, but HTTP traffic to `bar.example.com` will be rejected outright. -Since this example uses ACME, **it is only supported in $AESproductName$**. +Since this example uses ACME, **it is only supported in Ambassador Edge Stack**. For demonstration purposes, we show this example listening for HTTPS on port 9999, using `X-Forwarded-Proto`. @@ -240,7 +239,7 @@ This scenario uses TLS without ACME. Each of our two `Host`s uses a distinct TLS traffic to either`foo.example.com` or `bar.example.com` is routed, but this time `foo.example.com` will redirect HTTP requests, while `bar.example.com` will route them. -Since this example does not use ACME, it is supported in $productName$ as well as $AESproductName$. +Since this example does not use ACME, it is supported in Emissary as well as Ambassador Edge Stack. For demonstration purposes, we show this example listening for HTTPS on port 4848, using `X-Forwarded-Proto`. @@ -381,10 +380,10 @@ spec: Learn more about Host -### ACME With a TLSContext ($AESproductName$ Only) +### ACME With a TLSContext (Ambassador Edge Stack Only) -In $AESproductName$, you can use a `TLSContext` with ACME as well. This example is the same as "TLS using ACME", -but we use a `TLSContext` to set `ALPN` information. Again, ACME is only supported in $AESproductName$. +In Ambassador Edge Stack, you can use a `TLSContext` with ACME as well. This example is the same as "TLS using ACME", +but we use a `TLSContext` to set `ALPN` information. Again, ACME is only supported in Ambassador Edge Stack. ```yaml --- @@ -420,7 +419,7 @@ spec: ### Using an L7 Load Balancer to Terminate TLS -In this scenario, a layer 7 load balancer ahead of $productName$ will terminate TLS, so $productName$ will always see HTTP with a known good `X-Forwarded-Protocol`. We'll use that to route HTTPS and redirect HTTP. +In this scenario, a layer 7 load balancer ahead of Emissary will terminate TLS, so Emissary will always see HTTP with a known good `X-Forwarded-Protocol`. We'll use that to route HTTPS and redirect HTTP. ```yaml --- @@ -450,7 +449,7 @@ spec: - We set `l7Depth` to 1 to indicate that there's a single trusted L7 load balancer ahead of us. - We specifically set this Listener to HTTP-only, but we stick with port 8443 just because we expect people setting up TLS at all to expect to use port 8443. (There's nothing special about the port number, pick whatever you like.) -- Our `Host` does not specify a `tlsSecret`, so $productName$ will not try to terminate TLS. +- Our `Host` does not specify a `tlsSecret`, so Emissary will not try to terminate TLS. - Since the `Listener` still pays attention to `X-Forwarded-Proto`, both secure and insecure requests are possible, and we use the `Host` to route HTTPS and redirect HTTP. @@ -462,12 +461,12 @@ spec: ### Using a Split L4 Load Balancer to Terminate TLS -Here, we assume that $productName$ is behind a load balancer setup that handles TLS at layer 4: +Here, we assume that Emissary is behind a load balancer setup that handles TLS at layer 4: -- Incoming cleartext traffic is forwarded to $productName$ on port 8080. -- Incoming TLS traffic is terminated at the load balancer, then forwarded to $productName$ _as cleartext_ on port 8443. +- Incoming cleartext traffic is forwarded to Emissary on port 8080. +- Incoming TLS traffic is terminated at the load balancer, then forwarded to Emissary _as cleartext_ on port 8443. - This might involve multiple L4 load balancers, but the actual number doesn't matter. -- The actual port numbers we use don't matter either, as long as $productName$ and the load balancer(s) agree on which port is for which traffic. +- The actual port numbers we use don't matter either, as long as Emissary and the load balancer(s) agree on which port is for which traffic. We're going to route HTTPS for both `foo.example.com` and `bar.example.com`, redirect HTTP for `foo.example.com`, and reject HTTP for `bar.example.com`. diff --git a/content/en/docs/2.5/howtos/consul.md b/content/en/docs/2.5/howtos/consul.md index a8c7404e..77cc6247 100644 --- a/content/en/docs/2.5/howtos/consul.md +++ b/content/en/docs/2.5/howtos/consul.md @@ -1,7 +1,6 @@ - -import Alert from '@material-ui/lab/Alert'; - -# Consul integration +--- +title: Consul integration +---

Contents

@@ -9,7 +8,7 @@ import Alert from '@material-ui/lab/Alert'; - [Consul integration](#consul-integration) - [Architecture overview](#architecture-overview) - [Installing Consul](#installing-consul) - - [Installing $productName$](#installing-consul) + - [Installing Emissary](#installing-consul) - [Using Consul for service discovery](#using-consul-for-service-discovery) - [Using Consul for authorization and encryption](#using-consul-for-authorization-and-encryption) - [Environment variables](#environment-variables) @@ -18,32 +17,32 @@ import Alert from '@material-ui/lab/Alert';
[Consul](https://www.consul.io) is a widely used service mesh. -$productName$ natively supports service discovery and unauthenticated +Emissary natively supports service discovery and unauthenticated communication to services in Consul. Additionally, the *Ambassador -Consul Connector* enables $productName$ to encrypt and authenticate +Consul Connector* enables Emissary to encrypt and authenticate its communication via mTLS with services in Consul that make use of [Consul's *Connect* feature](https://www.consul.io/docs/connect). ## Architecture overview -Using Consul with $productName$ is particularly useful when deploying -$productName$ in hybrid cloud environments where you deploy +Using Consul with Emissary is particularly useful when deploying +Emissary in hybrid cloud environments where you deploy applications on VMs and Kubernetes. In this environment, Consul -enables $productName$ to securely route over TLS to any application +enables Emissary to securely route over TLS to any application regardless of where it is deployed. In this architecture, Consul serves as the source of truth for your entire data center, tracking available endpoints, service configuration, and secrets for TLS encryption. New applications and services automatically register themselves with Consul using the -Consul agent or API. When you send a request through $productName$, -$productName$ sends the request to an endpoint based on the data in +Consul agent or API. When you send a request through Emissary, +Emissary sends the request to an endpoint based on the data in Consul. ![ambassador-consul](../../images/consul-ambassador.png) This guide first instructs you on registering a service with Consul -and using $productName$ to dynamically route requests to that service +and using Emissary to dynamically route requests to that service based on Consul's service discovery data, and subsequently instructs you on using using the Ambassador Consul Connector to use Consul for authorizing and encrypting requests. @@ -121,24 +120,24 @@ and skip to the next section. helm install -f consul-values.yaml hashicorp hashicorp/consul ``` -## Installing $productName$ +## Installing Emissary -If you have not already installed $productName$ in to your cluster, +If you have not already installed Emissary in to your cluster, then go to the [quick start guide](../../tutorials/getting-started) before continuing any further in this guide. ## Using Consul for service discovery -This section of the guide instructs you on configuring $productName$ +This section of the guide instructs you on configuring Emissary to look for services registered to Consul, registering a demo -application with Consul, and configuring $productName$ to route to +application with Consul, and configuring Emissary to route to this application using endpoint data from Consul. In this tutorial, you deploy the application in Kubernetes. However, this application can be deployed anywhere in your data center, such as on a VM. -1. Configure $productName$ to look for services registered to Consul +1. Configure Emissary to look for services registered to Consul by creating the `ConsulResolver`. Use `kubectl` to apply the following manifest: @@ -172,10 +171,10 @@ on a VM. - This tells $productName$ that Consul is a service discovery endpoint. + This tells Emissary that Consul is a service discovery endpoint. You must set the resolver to your `ConsulResolver` on a - per-`Mapping` basis, otherwise for that `Mapping` $productName$ + per-`Mapping` basis, otherwise for that `Mapping` Emissary uses the default resolver. That is, in order for a `Mapping` to make use of a service registered in Consul, you need to add `resolver: consul-dc1` to that `Mapping`. @@ -296,7 +295,7 @@ on a VM. -4. Configure $productName$ to make use of this `quote-consul` service. +4. Configure Emissary to make use of this `quote-consul` service. Use `kubectl` to apply the following manifest: ```shell @@ -322,12 +321,12 @@ on a VM. `Deployment`. - `resolver` must be set to the `ConsulResolver` that you created in the previous step. - - `load_balancer` must be set to configure $productName$ to route + - `load_balancer` must be set to configure Emissary to route directly to the Quote application endpoints that are retrieved from Consul. 5. Send a request to the `/quote-consul/` API endpoint in order to - validate that $productName$ is now making use of that service: + validate that Emissary is now making use of that service: ```console $ AMBASSADOR_IP=$(kubectl --namespace $productNamespace$ get services/$productDeploymentName$ -o "go-template={{range .status.loadBalancer.ingress}}{{or .ip .hostname}}{{end}}") @@ -352,14 +351,14 @@ Consul. In this part of the guide, you'll install a different version of the demo application that now uses Consul's *Connect* feature to authorize its incoming connections using mTLS, and install *Ambassador Consul -Connector* to enable $productName$ to authenticate to such services. +Connector* to enable Emissary to authenticate to such services. The following steps assume you've already set up Consul for service discovery, as detailed above. 1. The Ambassador Consul Connector retrieves the TLS certificate issued by the Consul CA and stores it in a Kubernetes `Secret` for - $productName$ to use. Deploy the Ambassador Consul Connector with + Emissary to use. Deploy the Ambassador Consul Connector with `kubectl`: ```shell @@ -371,7 +370,7 @@ discovery, as detailed above. - RBAC resources. - The Ambassador Consul Connector service. - A `TLSContext` named `ambassador-consul` to load the - `ambassador-consul-connect` `Secret` into $productName$. + `ambassador-consul-connect` `Secret` into Emissary. 2. Deploy a new version of the demo application, and configure it to inject the Consul Connect sidecar by setting @@ -487,7 +486,7 @@ discovery, as detailed above. After you have verified that you see the `quote-connect` service in your web browser, you may kill the port-forward. -5. Create a `Mapping` to configure $productName$ route to the +5. Create a `Mapping` to configure Emissary route to the `quote-connect` service in Consul. Use `kubectl` to apply the following manifest: @@ -515,11 +514,11 @@ discovery, as detailed above. You can view this with `kubectl get svc -A` it should follow the format of `{service name}-sidecar-proxy`. - `resolver` must be set to the `ConsulResolver` created when - configuring $productName$. + configuring Emissary. - `tls` must be set to the TLSContext storing the Consul mTLS certificates, which is `ambassador-consul` in the standard `ambassador-consul-connector.yaml`. - - `load_balancer` must be set to configure $productName$ to route + - `load_balancer` must be set to configure Emissary to route directly to the application endpoints that are retrieved from Consul. @@ -527,7 +526,7 @@ discovery, as detailed above. the `quote-connect` service in Consul. 6. Send a request to the `/quote-connect/` API endpoint in order to - validate that $productName$ is now using mTLS to encrypt and + validate that Emissary is now using mTLS to encrypt and authenticate communication with that service: ```console @@ -554,7 +553,7 @@ environment variables. The defaults are best for most use-cases. | Environment Variable | Description | Default | |------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------| -| `_AMBASSADOR_ID` | Set 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`) | `""` | +| `_AMBASSADOR_ID` | Set 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 Emissary `Deployment`) | `""` | | `_CONSUL_HOST` | Set the IP or DNS name of the target Consul HTTP API server | `127.0.0.1` | | `_CONSUL_PORT` | Set the port number of the target Consul HTTP API server | `8500` | | `_AMBASSADOR_TLS_SECRET_NAME` | Set the name of the Kubernetes `v1.Secret` created by this program that contains the Consul-generated TLS certificate. | `$AMBASSADOR_ID-consul-connect` | @@ -562,6 +561,6 @@ environment variables. The defaults are best for most use-cases. ## More information -For more about $productName$'s integration with Consul, read the +For more about Emissary's integration with Consul, read the [service discovery configuration](../../topics/running/resolvers) documentation. diff --git a/content/en/docs/2.5/howtos/dist-tracing.md b/content/en/docs/2.5/howtos/dist-tracing.md index ec5b160f..5d48ef27 100644 --- a/content/en/docs/2.5/howtos/dist-tracing.md +++ b/content/en/docs/2.5/howtos/dist-tracing.md @@ -1,4 +1,6 @@ -# Explore distributed tracing and Kubernetes monitoring +--- +title: Distributed Tracing +--- The Kubernetes monitoring and distributed tracing landscape is hard to grasp. Although this conceptual approach to [observability is nothing new](https://blog.getambassador.io/distributed-tracing-with-java-microdonuts-kubernetes-and-the-ambassador-api-gateway-ace15b62a89e) — companies like New Relic revolutionized single-application performance monitoring (APM) over a decade ago — it took a few years and the [Dapper publication](https://research.google/pubs/pub36356/) for this idea to migrate to distributed applications. The importance of this technology is only increasing, as more and more of us are building [“deep systems”](https://lightstep.com/deep-systems/). diff --git a/content/en/docs/2.5/howtos/external-dns.md b/content/en/docs/2.5/howtos/external-dns.md index f0f51dbb..2a771dd9 100644 --- a/content/en/docs/2.5/howtos/external-dns.md +++ b/content/en/docs/2.5/howtos/external-dns.md @@ -1,6 +1,6 @@ -import Alert from '@material-ui/lab/Alert'; - -# ExternalDNS with $productName$ +--- +title: ExternalDNS +--- [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. @@ -14,9 +14,9 @@ Start by checking the [ExternalDNS repo's deployment instructions](https://githu ### Installation -Configuration for a `ServiceAccount`, `ClusterRole`, and `ClusterRoleBinding` are necessary for the ExternalDNS deployment to support compatability with $productName$ and allow ExternalDNS to get hostnames from $productName$'s `Hosts`. +Configuration for a `ServiceAccount`, `ClusterRole`, and `ClusterRoleBinding` are necessary for the ExternalDNS deployment to support compatability with Emissary and allow ExternalDNS to get hostnames from Emissary'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 above for annotations and arguments for your DNS Provider. +The following configuration is an example configuring Emissary - ExternalDNS integration with [AWS Route53](https://aws.amazon.com/route53/) as the DNS provider. Refer to the ExternalDNS documentation above for annotations and arguments for your DNS Provider. 1. Create a YAML file named `externaldns-config.yaml`, and copy the following configuration into it. @@ -97,9 +97,9 @@ The following configuration is an example configuring $productName$ - ExternalDN Configure or remove arguments to fit your needs. Additional arguments required for your DNS provider can be found by checking the [ExternalDNS repo's deployment instructions](https://github.com/kubernetes-sigs/external-dns#deploying-to-a-cluster). - * `--source=ambassador-host` - required across all DNS providers to tell ExternalDNS to look for hostnames in the $productName$ `Host` configurations. + * `--source=ambassador-host` - required across all DNS providers to tell ExternalDNS to look for hostnames in the Emissary `Host` configurations. -3. Apply the above config with the following command to deploy ExternalDNS to your cluster and configure support for $productName$ +3. Apply the above config with the following command to deploy ExternalDNS to your cluster and configure support for Emissary ```shell kubectl apply -f externaldns-ambassador.yaml @@ -111,7 +111,7 @@ The following configuration is an example configuring $productName$ - ExternalDN ## Usage -After applying the above configuration, ExternalDNS is ready to use. Configure a `Host` with the following annotation to allow ExternalDNS to get the IP address of your $productName$'s LoadBalancer and register it with your DNS provider. +After applying the above configuration, ExternalDNS is ready to use. Configure a `Host` with the following annotation to allow ExternalDNS to get the IP address of your Emissary's LoadBalancer and register it with your DNS provider. ```yaml apiVersion: getambassador.io/v3alpha1 @@ -127,4 +127,4 @@ spec: ``` -Victory! ExternalDNS is now running and configured to report $productName$'s IP and hostname with your DNS provider. +Victory! ExternalDNS is now running and configured to report Emissary's IP and hostname with your DNS provider. diff --git a/content/en/docs/2.5/howtos/filter-dev-guide.md b/content/en/docs/2.5/howtos/filter-dev-guide.md index eefe8b6b..d0413fd6 100644 --- a/content/en/docs/2.5/howtos/filter-dev-guide.md +++ b/content/en/docs/2.5/howtos/filter-dev-guide.md @@ -1,18 +1,20 @@ -# Developing custom filters for routing +--- +title: Developing custom filters for routing +--- -Sometimes you may want $AESproductName$ to manipulate an incoming request. Some example use cases: +Sometimes you may want Ambassador Edge Stack to manipulate an incoming request. Some example use cases: * Inspect an incoming request, and add a custom header that can then be used for routing * Add custom Authorization headers * Validate an incoming request fits an OpenAPI specification before passing the request to a target service -$AESproductName$ supports these use cases by allowing you to execute custom logic in `Filters`. Filters are written in Golang, and managed by $AESproductName$. If you want to write a filter in a language other than Golang, $AESproductName$ also has an HTTP/gRPC interface for Filters called `External`. +Ambassador Edge Stack supports these use cases by allowing you to execute custom logic in `Filters`. Filters are written in Golang, and managed by Ambassador Edge Stack. If you want to write a filter in a language other than Golang, Ambassador Edge Stack also has an HTTP/gRPC interface for Filters called `External`. ## Prerequisites -`Plugin` `Filter`s are built as [Go plugins](https://golang.org/pkg/plugin/) and loaded directly into the $AESproductName$ container so they can run in-process with the rest of $AESproductName$. +`Plugin` `Filter`s are built as [Go plugins](https://golang.org/pkg/plugin/) and loaded directly into the Ambassador Edge Stack container so they can run in-process with the rest of Ambassador Edge Stack. -To build a `Plugin` `Filter` into the $AESproductName$ container you will need +To build a `Plugin` `Filter` into the Ambassador Edge Stack container you will need - Linux or MacOS host (Windows Subsystem for Linux is ok) - [Docker](https://docs.docker.com/install/) - [rsync](https://rsync.samba.org/) @@ -36,10 +38,10 @@ We've created an example filter that you can customize for your particular use c 4. Push the image to your Docker registry: `docker push $DOCKER_REGISTRY/amb-sidecar-plugin:VERSION`. -5. Configure $AESproductName$ to use the plugin by creating a `Filter` +5. Configure Ambassador Edge Stack to use the plugin by creating a `Filter` and `FilterPolicy` CRD, as per the [filter reference](/docs/edge-stack/latest/topics/using/filters/). -6. Update the standard $AESproductName$ manifest to use your Docker +6. Update the standard Ambassador Edge Stack manifest to use your Docker image instead of the standard sidecar. ```patch @@ -55,14 +57,14 @@ We've created an example filter that you can customize for your particular use c ## Rapid development of a custom filter -During development, you may want to sidestep the deployment process for a faster development loop. The `aes-plugin-runner` helps you rapidly develop $AESproductName$ filters locally. +During development, you may want to sidestep the deployment process for a faster development loop. The `aes-plugin-runner` helps you rapidly develop Ambassador Edge Stack filters locally. To install the runner, download the latest version: Mac 64-bit | Linux 64-bit -Note that the plugin runner must match the version of $AESproductName$ that you are running. Place the binary somewhere in your `$PATH`. +Note that the plugin runner must match the version of Ambassador Edge Stack that you are running. Place the binary somewhere in your `$PATH`. Information about open-source code used in `aes-plugin-runner` can be found by running `aes-plugin-runner --version`. diff --git a/content/en/docs/2.5/howtos/grpc.md b/content/en/docs/2.5/howtos/grpc.md index 3967ddf7..ffdc0872 100644 --- a/content/en/docs/2.5/howtos/grpc.md +++ b/content/en/docs/2.5/howtos/grpc.md @@ -1,12 +1,14 @@ -# gRPC Connections +--- +title: gRPC +--- -$productName$ makes it easy to access your services from outside your application. This includes gRPC services, although a little bit of additional configuration is required: by default, Envoy connects to upstream services using HTTP/1.x and then upgrades to HTTP/2 whenever possible. However, gRPC is built on HTTP/2 and most gRPC servers do not speak HTTP/1.x at all. $productName$ must tell its underlying Envoy that your gRPC service only wants to speak to that HTTP/2, using the `grpc` attribute of a `Mapping`. +Emissary makes it easy to access your services from outside your application. This includes gRPC services, although a little bit of additional configuration is required: by default, Envoy connects to upstream services using HTTP/1.x and then upgrades to HTTP/2 whenever possible. However, gRPC is built on HTTP/2 and most gRPC servers do not speak HTTP/1.x at all. Emissary must tell its underlying Envoy that your gRPC service only wants to speak to that HTTP/2, using the `grpc` attribute of a `Mapping`. -## Writing a gRPC service for $productName$ +## Writing a gRPC service for Emissary There are many examples and walkthroughs on how to write gRPC applications so that is not what this article will aim to accomplish. If you do not yet have a service written you can find examples of gRPC services in all supported languages here: [gRPC Quickstart](https://grpc.io/docs/quickstart/) -This document will use the [gRPC python helloworld example](https://github.com/grpc/grpc/tree/master/examples/python/helloworld) to demonstrate how to configure a gRPC service with $productName$. +This document will use the [gRPC python helloworld example](https://github.com/grpc/grpc/tree/master/examples/python/helloworld) to demonstrate how to configure a gRPC service with Emissary. Follow the example up through [Run a gRPC application](https://grpc.io/docs/languages/python/quickstart/#run-a-grpc-application) to get started. @@ -61,7 +63,7 @@ $ docker push /grpc_example ### Mapping gRPC services -$productName$ `Mapping`s are based on URL prefixes; for gRPC, the URL prefix is the full-service name, including the package path (`package.service`). These are defined in the `.proto` definition file. In the example [proto definition file](https://github.com/grpc/grpc/blob/master/examples/protos/helloworld.proto) we see: +Emissary `Mapping`s are based on URL prefixes; for gRPC, the URL prefix is the full-service name, including the package path (`package.service`). These are defined in the `.proto` definition file. In the example [proto definition file](https://github.com/grpc/grpc/blob/master/examples/protos/helloworld.proto) we see: ``` package helloworld; @@ -155,7 +157,7 @@ spec: restartPolicy: Always ``` -The Host is declared here because we are using gRPC without TLS. Since $productName$ terminates TLS by default, in the Host we add a `requestPolicy` which allows insecure connections. After adding the $productName$ mapping to the service, the rest of the Kubernetes deployment YAML file is pretty straightforward. We need to identify the container image to use, expose the `containerPort` to listen on the same port the Docker container is listening on, and map the service port (80) to the container port (50051). +The Host is declared here because we are using gRPC without TLS. Since Emissary terminates TLS by default, in the Host we add a `requestPolicy` which allows insecure connections. After adding the Emissary mapping to the service, the rest of the Kubernetes deployment YAML file is pretty straightforward. We need to identify the container image to use, expose the `containerPort` to listen on the same port the Docker container is listening on, and map the service port (80) to the container port (50051). > For more information on insecure routing, please refer to the [`Host` documentation](../../topics/running/host-crd#secure-and-insecure-requests). @@ -168,7 +170,7 @@ $ kubectl apply -f grpc_example.yaml ### Testing the Deployment -Make sure to test your Kubernetes deployment before making more advanced changes (like adding TLS). To test any service with $productName$, we will need the hostname of the running $productName$ service which you can get with: +Make sure to test your Kubernetes deployment before making more advanced changes (like adding TLS). To test any service with Emissary, we will need the hostname of the running Emissary service which you can get with: ``` $ kubectl get service ambassador -o wide @@ -200,11 +202,11 @@ Greeter client received: Hello, you! ### gRPC and TLS -There is some extra configuration required to connect to a gRPC service through $productName$ over an encrypted channel. Currently, the gRPC call is being sent over cleartext to $productName$ which proxies it to the gRPC application. +There is some extra configuration required to connect to a gRPC service through Emissary over an encrypted channel. Currently, the gRPC call is being sent over cleartext to Emissary which proxies it to the gRPC application. ![](../images/grpc-tls.png) -If you want to add TLS encryption to your gRPC calls, first you need to tell $productName$ to add [ALPN protocols](../../topics/running/tls) which are required by HTTP/2 to do TLS. +If you want to add TLS encryption to your gRPC calls, first you need to tell Emissary to add [ALPN protocols](../../topics/running/tls) which are required by HTTP/2 to do TLS. For example: @@ -221,7 +223,7 @@ spec: alpn_protocols: h2 ``` -Next, you need to change the client code slightly and tell it to open a secure RPC channel with $productName$. +Next, you need to change the client code slightly and tell it to open a secure RPC channel with Emissary. ```diff - with grpc.insecure_channel(‘$AMBASSADORHOST:$PORT’) as channel: @@ -231,9 +233,9 @@ Next, you need to change the client code slightly and tell it to open a secure R print("Greeter client received: " + response.message) ``` -`grpc.ssl_channel_credentials(root_certificates=None, private_key=None, certificate_chain=None)`returns the root certificate that will be used to validate the certificate and public key sent by $productName$. The default values of `None` tells the gRPC runtime to grab the root certificate from the default location packaged with gRPC and ignore the private key and certificate chain fields. Generally, passing no arguments to the method that requests credentials gives the same behavior. Refer to the languages [API Reference](https://grpc.io/docs/) if this is not the case. +`grpc.ssl_channel_credentials(root_certificates=None, private_key=None, certificate_chain=None)`returns the root certificate that will be used to validate the certificate and public key sent by Emissary. The default values of `None` tells the gRPC runtime to grab the root certificate from the default location packaged with gRPC and ignore the private key and certificate chain fields. Generally, passing no arguments to the method that requests credentials gives the same behavior. Refer to the languages [API Reference](https://grpc.io/docs/) if this is not the case. -$productName$ is now terminating TLS from the gRPC client and proxying the call to the application over cleartext. +Emissary is now terminating TLS from the gRPC client and proxying the call to the application over cleartext. ![](../images/gRPC-TLS-Ambassador.png) @@ -243,7 +245,7 @@ If you want to configure authentication in another language, [gRPC provides exam Some gRPC clients automatically include the port in the Host header. This is a problem when using TLS because the certificate will match `myurl.com` but the Host header will be `myurl.com:443`, resulting in the error `rpc error: code = Unimplemented desc =`. If you run into this issue, there are two ways to solve it depending on your use case, both using the Module resource. -The first is to set the `strip_matching_host_port` [property](../../topics/running/ambassador#strip-matching-host-port) to `true`. However, this only works if the port in the header matches the port that Envoy listens on (8443 by default). In the default installation of $productName$, the public port is 443, which then maps internally to 8443, so this only works for custom installations where the public service port matches the port in the Listener resource. +The first is to set the `strip_matching_host_port` [property](../../topics/running/ambassador#strip-matching-host-port) to `true`. However, this only works if the port in the header matches the port that Envoy listens on (8443 by default). In the default installation of Emissary, the public port is 443, which then maps internally to 8443, so this only works for custom installations where the public service port matches the port in the Listener resource. The second solution is to use the following [Lua script](../../topics/running/ambassador#lua-scripts), which always strips the port: @@ -272,7 +274,7 @@ spec: ![](../images/gRPC-TLS-Originate.png) -$productName$ can originate TLS with your gRPC service so the entire RPC channel is encrypted. To configure this, first get some TLS certificates and configure the server to open a secure channel with them. Using self-signed certs this can be done with OpenSSL and adding a couple of lines to the server code. +Emissary can originate TLS with your gRPC service so the entire RPC channel is encrypted. To configure this, first get some TLS certificates and configure the server to open a secure channel with them. Using self-signed certs this can be done with OpenSSL and adding a couple of lines to the server code. ```diff def serve(): @@ -298,7 +300,7 @@ Rebuild your docker container **making sure the certificates are included** and print("Greeter client received: " + response.message) ``` -Once deployed we will need to tell $productName$ to originate TLS to the application. +Once deployed we will need to tell Emissary to originate TLS to the application. ```yaml --- @@ -342,7 +344,7 @@ spec: secret: ambassador-cert ``` -We need to tell $productName$ to route to the `service:` over https and have the service listen on `443`. We also need to tell $productName$ to use ALPN protocols when originating TLS with the application, the same way we did with TLS termination. This is done by setting `alpn_protocols: ["h2"]` in a `TLSContext` telling the service to use that tls-context in the mapping by setting `tls: upstream`. +We need to tell Emissary to route to the `service:` over https and have the service listen on `443`. We also need to tell Emissary to use ALPN protocols when originating TLS with the application, the same way we did with TLS termination. This is done by setting `alpn_protocols: ["h2"]` in a `TLSContext` telling the service to use that tls-context in the mapping by setting `tls: upstream`. Refer to the [TLS document](../../topics/running/tls/origination#advanced-configuration-using-a-tlscontext) for more information on TLS origination. @@ -359,9 +361,9 @@ headers: ### Ingress controllers -Some [Kubernetes ingress controllers](https://kubernetes.io/docs/concepts/services-networking/ingress/) do not support HTTP/2 fully. As a result, if you are running $productName$ with an ingress controller in front, you may find that gRPC requests fail even with correct $productName$ configuration. +Some [Kubernetes ingress controllers](https://kubernetes.io/docs/concepts/services-networking/ingress/) do not support HTTP/2 fully. As a result, if you are running Emissary with an ingress controller in front, you may find that gRPC requests fail even with correct Emissary configuration. -A simple way around this is to use $productName$ with a `LoadBalancer` service, rather than an Ingress controller. You can also consider using [$productName$ as your Ingress Controller](../../topics/running/ingress-controller). +A simple way around this is to use Emissary with a `LoadBalancer` service, rather than an Ingress controller. You can also consider using [Emissary as your Ingress Controller](../../topics/running/ingress-controller). ### Mappings with hosts @@ -381,7 +383,7 @@ spec: host: api.example.com ``` -Some gRPC client libraries produce requests where the `host` or `:authority` header includes the port number. For example, a request to the above service might include `host: api.example.com:443` instead of just `host: api.example.com`. To avoid having $productName$ return a 404 (not found) response to these requests due to the mismatched host, you may want to set `strip_matching_host_port` in the [Ambassador module](../../topics/running/ambassador#strip-matching-host-port). +Some gRPC client libraries produce requests where the `host` or `:authority` header includes the port number. For example, a request to the above service might include `host: api.example.com:443` instead of just `host: api.example.com`. To avoid having Emissary return a 404 (not found) response to these requests due to the mismatched host, you may want to set `strip_matching_host_port` in the [Ambassador module](../../topics/running/ambassador#strip-matching-host-port). Alternately, you may find it cleaner to make sure your gRPC client does not include the port in the `host` header. Here is an example using gRPC/Go. @@ -400,4 +402,4 @@ conn, err := grpc.Dial(hostname+":"+port, opts...) ## gRPC-Web -$productName$ also supports the [gRPC-Web](../../topics/running/ambassador#grpc) protocol for browser-based gRPC applications. +Emissary also supports the [gRPC-Web](../../topics/running/ambassador#grpc) protocol for browser-based gRPC applications. diff --git a/content/en/docs/2.5/howtos/index.md b/content/en/docs/2.5/howtos/index.md deleted file mode 100644 index f16cdd46..00000000 --- a/content/en/docs/2.5/howtos/index.md +++ /dev/null @@ -1,25 +0,0 @@ -# "How-to" guides - -These guides are designed to help users quickly accomplish common tasks. The guides assume a certain level of understanding of $productName$. Many of these guides are contributed by third parties; we welcome contributions via Pull Request at https://github.com/emissary-ingress/emissary. - -* Integrating with Service Mesh. $productName$ natively integrates with many service meshes. - * [HashiCorp Consul](consul) - * [Istio](istio) - * [Linkerd](linkerd2) -* Distributed tracing. $productName$ natively supports a number of distributed tracing systems to enable developers to visualize request flow in microservice and service-oriented architectures. - * [Datadog](tracing-datadog) - * [Zipkin](tracing-zipkin) -* Monitoring. $productName$ integrates with a number of different monitoring/metrics providers. - * [Prometheus](prometheus) -* [Developing Custom Filters](filter-dev-guide) -* Frameworks and Protocols. $productName$ supports a wide range of protocols and cloud-native frameworks. - * [gRPC](grpc) - * [Knative Serverless Framework](knative) - * [WebSockets](websockets) -* Security. $productName$ supports a number of strategies for securing Kubernetes services. - * [Protecting the Diagnostics Interface](protecting-diag-access) - * [HTTPS and TLS termination](tls-termination) - * [Certificate Manager](cert-manager) can be used to automatically obtain and renew TLS certificates; $AESproductName$ natively integrates this functionality. - * [Client Certificate Validation](client-cert-validation) - * [Basic Authentication](basic-auth) is a tutorial on how to use the external authentication API to code your own authentication service. - * [Basic Rate Limiting](rate-limiting-tutorial) diff --git a/content/en/docs/2.5/howtos/istio.md b/content/en/docs/2.5/howtos/istio.md index 6fa74fcf..153a20e6 100644 --- a/content/en/docs/2.5/howtos/istio.md +++ b/content/en/docs/2.5/howtos/istio.md @@ -1,19 +1,19 @@ -import Alert from '@material-ui/lab/Alert'; +--- +title: Istio +--- -# Istio integration +Emissary and Istio: Edge Proxy and Service Mesh together in one. Emissary is deployed at the edge of your network and routes incoming traffic to your internal services (aka "north-south" traffic). [Istio](https://istio.io/) is a service mesh for microservices, and is designed to add application-level Layer (L7) observability, routing, and resilience to service-to-service traffic (aka "east-west" traffic). Both Istio and Emissary are built using [Envoy](https://www.envoyproxy.io). -$productName$ and Istio: Edge Proxy and Service Mesh together in one. $productName$ is deployed at the edge of your network and routes incoming traffic to your internal services (aka "north-south" traffic). [Istio](https://istio.io/) is a service mesh for microservices, and is designed to add application-level Layer (L7) observability, routing, and resilience to service-to-service traffic (aka "east-west" traffic). Both Istio and $productName$ are built using [Envoy](https://www.envoyproxy.io). - -$productName$ and Istio can be deployed together on Kubernetes. In this configuration, $productName$ manages +Emissary and Istio can be deployed together on Kubernetes. In this configuration, Emissary manages traditional edge functions such as authentication, TLS termination, and edge routing. Istio mediates communication -from $productName$ to services, and communication between services. +from Emissary to services, and communication between services. -This allows the operator to have the best of both worlds: a high performance, modern edge service ($productName$) combined with a state-of-the-art service mesh (Istio). While Istio has introduced a [Gateway](https://istio.io/latest/docs/tasks/traffic-management/ingress/ingress-control/#configuring-ingress-using-an-istio-gateway) abstraction, $productName$ still has a much broader feature set for edge routing than Istio. For more on this topic, see our blog post on [API Gateway vs Service Mesh](https://blog.getambassador.io/api-gateway-vs-service-mesh-104c01fa4784). +This allows the operator to have the best of both worlds: a high performance, modern edge service (Emissary) combined with a state-of-the-art service mesh (Istio). While Istio has introduced a [Gateway](https://istio.io/latest/docs/tasks/traffic-management/ingress/ingress-control/#configuring-ingress-using-an-istio-gateway) abstraction, Emissary still has a much broader feature set for edge routing than Istio. For more on this topic, see our blog post on [API Gateway vs Service Mesh](https://blog.getambassador.io/api-gateway-vs-service-mesh-104c01fa4784). -This guide explains how to take advantage of both $productName$ and Istio to have complete control and observability over how requests are made in your cluster: +This guide explains how to take advantage of both Emissary and Istio to have complete control and observability over how requests are made in your cluster: - [Install Istio](#install-istio) and configure auto-injection -- [Install $productName$ with Istio integration](#install-edge) +- [Install Emissary with Istio integration](#install-edge) - [Configure an mTLS `TLSContext`](#configure-an-mtls-tlscontext) - [Route to services using mTLS](#route-to-services-using-mtls) @@ -32,12 +32,12 @@ To follow this guide, you need: ## Install Istio Start by [installing Istio](https://istio.io/docs/setup/getting-started/). Any supported installation method for -Istio will work for use with $productName$. +Istio will work for use with Emissary. ### Configure Istio Auto-Injection Istio functions by supplying a sidecar container running Envoy with every service in the mesh (including -$productName$). The sidecar is what enforces Istio policies for traffic to and from the service, notably +Emissary). The sidecar is what enforces Istio policies for traffic to and from the service, notably including mTLS encryption and certificate handling. As such, it is very important that the sidecar be correctly supplied for every service in the mesh! @@ -56,16 +56,16 @@ kubectl label namespace $namespace istio-injection=enabled --overwrite sidecar. -## Install $productName$ with Istio Integration +## Install Emissary with Istio Integration -Properly integrating $productName$ with Istio provides support for: +Properly integrating Emissary with Istio provides support for: * [Mutual TLS (mTLS)](../../topics/running/tls/mtls/), with certificates managed by Istio, to allow end-to-end encryption for east-west traffic; * Automatic generation of Prometheus metrics for services; and * Istio distributed tracing for end-to-end observability. -The simplest way to enable everything is to install $productName$ using [Helm](https://helm.sh), though +The simplest way to enable everything is to install Emissary using [Helm](https://helm.sh), though you can use manual installation with YAML if you wish. ### Installation with Helm (Recommended) @@ -73,28 +73,28 @@ you can use manual installation with YAML if you wish. To install with Helm, write the following YAML to a file called `istio-integration.yaml`: ```yaml -# Listeners are required in $productName$ 2.0. +# Listeners are required in Emissary 2.0. # This will create the two default Listeners for HTTP on port 8080 and HTTPS on port 8443. createDefaultListeners: true -# These are annotations that will be added to the $productName$ pods. +# These are annotations that will be added to the Emissary pods. podAnnotations: # These first two annotations tell Istio not to try to do port management for the - # $productName$ pod itself. Though these annotations are placed on the $productName$ + # Emissary pod itself. Though these annotations are placed on the Emissary # pods, they are interpreted by Istio. traffic.sidecar.istio.io/includeInboundPorts: "" # do not intercept any inbound ports traffic.sidecar.istio.io/includeOutboundIPRanges: "" # do not intercept any outbound traffic # We use proxy.istio.io/config to tell the Istio proxy to write newly-generated mTLS certificates # into /etc/istio-certs, which will be mounted below. Though this annotation is placed on the - # $productName$ pods, it is interpreted by Istio. + # Emissary pods, it is interpreted by Istio. proxy.istio.io/config: | proxyMetadata: OUTPUT_CERTS: /etc/istio-certs # We use sidecar.istio.io/userVolumeMount to tell the Istio sidecars to mount the istio-certs # volume at /etc/istio-certs, allowing the sidecars to see the generated certificates. Though - # this annotation is placed on the $productName$ pods, it is interpreted by Istio. + # this annotation is placed on the Emissary pods, it is interpreted by Istio. sidecar.istio.io/userVolumeMount: '[{"name": "istio-certs", "mountPath": "/etc/istio-certs"}]' # We define a single storage volume called "istio-certs". It starts out empty, and Istio @@ -105,16 +105,16 @@ volumes: medium: Memory name: istio-certs -# We also tell $productName$ to mount the "istio-certs" volume at /etc/istio-certs in the -# $productName$ pod. This gives $productName$ access to the mTLS certificates, too. +# We also tell Emissary to mount the "istio-certs" volume at /etc/istio-certs in the +# Emissary pod. This gives Emissary access to the mTLS certificates, too. volumeMounts: - name: istio-certs mountPath: /etc/istio-certs/ readOnly: true -# Finally, we need to set some environment variables for $productName$. +# Finally, we need to set some environment variables for Emissary. env: - # AMBASSADOR_ISTIO_SECRET_DIR tells $productName$ to look for Istio mTLS certs, and to + # AMBASSADOR_ISTIO_SECRET_DIR tells Emissary to look for Istio mTLS certs, and to # make them available as a secret named "istio-certs". AMBASSADOR_ISTIO_SECRET_DIR: "/etc/istio-certs" @@ -123,7 +123,7 @@ env: AMBASSADOR_ENVOY_BASE_ID: "1" ``` -To install $productName$ with Helm, use these values to configure Istio integration: +To install Emissary with Helm, use these values to configure Istio integration: 1. Create the `$productNamespace$` Namespace: @@ -144,7 +144,7 @@ To install $productName$ with Helm, use these values to configure Istio integrat helm repo update ``` -4. Use Helm to install $productName$ in $productNamespace$: +4. Use Helm to install Emissary in $productNamespace$: ```bash helm install $productHelmName$ --namespace $productNamespace$ -f istio-integration.yaml datawire/$productHelmName$ && \ @@ -156,31 +156,31 @@ To install $productName$ with Helm, use these values to configure Istio integrat To install using YAML files, you need to manually incorporate the contents of the `istio-integration.yaml` file shown above into your deployment YAML: -* `pod-annotations` should be configured as Kubernetes `annotations` on the $productName$ Pods; +* `pod-annotations` should be configured as Kubernetes `annotations` on the Emissary Pods; * `volumes`, `volumeMounts`, and `env` contents should be included in the $productDeploymentName$ Deployment; and * you must also label the $productNamespace$ Namespace for auto-injection as described above. ### Configuring an Existing Installation -If you have already installed $productName$ and want to enable Istio: +If you have already installed Emissary and want to enable Istio: 1. Install Istio. 2. Label the $productNamespace$ namespace for Istio auto-injection, as above. -2. Edit the $productName$ Deployments to contain the `annotations`, `volumes`, `volumeMounts`, and `env` elements +2. Edit the Emissary Deployments to contain the `annotations`, `volumes`, `volumeMounts`, and `env` elements shown above. * If you installed with Helm, you can use `helm upgrade` with `-f istio-integration.yaml` to modify the installation for you. -3. Restart the $productName$ pods. +3. Restart the Emissary pods. ## Configure an mTLS `TLSContext` -After configuring $productName$ for Istio integration, the Istio mTLS certificates are available within -$productName$: +After configuring Emissary for Istio integration, the Istio mTLS certificates are available within +Emissary: -- Both the `istio-proxy` sidecar and $productName$ mount the `istio-certs` volume at `/etc/istio-certs`. +- Both the `istio-proxy` sidecar and Emissary mount the `istio-certs` volume at `/etc/istio-certs`. - The `istio-proxy` sidecar saves the mTLS certificates into `/etc/istio-certs` (per the `OUTPUT_CERTS` environment variable). -- $productName$ reads the mTLS certificates from `/etc/istio-certs` (per the `AMBASSADOR_ISTIO_SECRET_DIR` +- Emissary reads the mTLS certificates from `/etc/istio-certs` (per the `AMBASSADOR_ISTIO_SECRET_DIR` environment variable) and creates a Secret named `istio-certs`. @@ -221,7 +221,7 @@ This `Mapping` will use mTLS when communicating with its upstream service. ## Route to Services Using mTLS -After integrating $productName$ with Istio, $productName$'s feature-rich routing capabilities and Istio's mTLS +After integrating Emissary with Istio, Emissary's feature-rich routing capabilities and Istio's mTLS and observability are all available for all incoming traffic. To take full advantage of both, you need to: - configure upstream services with the Istio sidecar; @@ -242,7 +242,7 @@ as discussed above. ### Configure `Mapping`s to Use mTLS -Traffic routing in $productName$ is configured with the [`Mapping`](../../topics/using/intro-mappings) resource. +Traffic routing in Emissary is configured with the [`Mapping`](../../topics/using/intro-mappings) resource. This is a powerful configuration object that lets you configure different routing rules for different services. To configure a `Mapping` to use mTLS, you need to use the `tls` element of the `Mapping` to tell it to originate @@ -301,9 +301,9 @@ The behavior of your service will not seem to change, even though mTLS is active } ``` -This request first went to $productName$, which routed it over an mTLS connection to the quote service in the +This request first went to Emissary, 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. +being from Emissary, exported various metrics, and finally forwarded it on to the actual quote service. ### Configure Service Ports @@ -401,7 +401,7 @@ The Istio sidecar also supports [distributed tracing](https://istio.io/docs/task by default. To take advantage of this support, you need to: 1. Install a tracing provider, for example [Zipkin](../tracing-zipkin) into your cluster. -2. Add a [`TracingService`](../../topics/running/services/tracing-service) to tell $productName$ to send tracing +2. Add a [`TracingService`](../../topics/running/services/tracing-service) to tell Emissary to send tracing to your tracing provider, for example: ```yaml @@ -420,7 +420,7 @@ by default. To take advantage of this support, you need to: - ":path" ``` -After adding a `TracingService`, restart $productName$ for the configuration to take effect. Istio propagates +After adding a `TracingService`, restart Emissary for the configuration to take effect. Istio propagates the tracing headers automatically, allowing for end-to-end observability within the cluster. ## FAQ @@ -429,9 +429,9 @@ the tracing headers automatically, allowing for end-to-end observability within By default, Istio mTLS certificates are valid for 90 days, but get rotated every day. -$productName$ updates the mTLS certificates as they are rotated, so you don't need to worry about certificate expiration. +Emissary updates the mTLS certificates as they are rotated, so you don't need to worry about certificate expiration. -To test that $productName$ is properly rotating certificates, shorten the TTL of the Istio certificates by +To test that Emissary is properly rotating certificates, shorten the TTL of the Istio certificates by setting the following environment variables in the `istiod` container in the `istio-system` Namespace: ```yaml diff --git a/content/en/docs/2.5/howtos/knative.md b/content/en/docs/2.5/howtos/knative.md index f995eaaa..21b8a5f8 100644 --- a/content/en/docs/2.5/howtos/knative.md +++ b/content/en/docs/2.5/howtos/knative.md @@ -1,4 +1,6 @@ -# Knative Serverless Framework +--- +title: Knative +--- [Knative](https://knative.dev/) is a popular Kubernetes-based platform for managing serverless workloads with two main components: diff --git a/content/en/docs/2.5/howtos/linkerd2.md b/content/en/docs/2.5/howtos/linkerd2.md index 09352941..aab60d39 100644 --- a/content/en/docs/2.5/howtos/linkerd2.md +++ b/content/en/docs/2.5/howtos/linkerd2.md @@ -1,21 +1,21 @@ --- -description: "A guide to using Linkerd 2 Auto-Inject to mesh a service and using $productName$ to dynamically route requests to that service." +title: Linkerd 2 +description: "A guide to using Linkerd 2 Auto-Inject to mesh a service and using Emissary to dynamically route requests to that service." --- -# Linkerd 2 integration -[Linkerd 2](https://www.linkerd.io) is a zero-config and ultra-lightweight service mesh. $productName$ natively supports Linkerd 2 for service discovery, end-to-end TLS (including mTLS between services), and (with Linkerd 2.8) multicluster operation. +[Linkerd 2](https://www.linkerd.io) is a zero-config and ultra-lightweight service mesh. Emissary natively supports Linkerd 2 for service discovery, end-to-end TLS (including mTLS between services), and (with Linkerd 2.8) multicluster operation. ## Architecture Linkerd 2 is designed for simplicity, security, and performance. In the cluster, it runs a control plane in its own namespace and then injects sidecar proxy containers in every Pod that should be meshed. -$productName$ itself also needs to be interwoven or "meshed" with Linkerd 2, and then configured to add special Linkerd headers to requests that tell Linkerd 2 where to forward them. This ie because mTLS between services is automatically handled by the control plane and the proxies. Istio and Consul allow $productName$ to initiate mTLS connections to upstream services by grabbing a certificate from a Kubernetes Secret. However, Linkerd 2 does not work this way, so $productName$ must rely on Linkerd 2 for mTLS connections to upstream services. This means we want Linkerd 2 to inject its sidecar into $productName$'s pods, but not Istio and Consul. +Emissary itself also needs to be interwoven or "meshed" with Linkerd 2, and then configured to add special Linkerd headers to requests that tell Linkerd 2 where to forward them. This ie because mTLS between services is automatically handled by the control plane and the proxies. Istio and Consul allow Emissary to initiate mTLS connections to upstream services by grabbing a certificate from a Kubernetes Secret. However, Linkerd 2 does not work this way, so Emissary must rely on Linkerd 2 for mTLS connections to upstream services. This means we want Linkerd 2 to inject its sidecar into Emissary's pods, but not Istio and Consul. -Through that setup, $productName$ terminates external TLS as the gateway and traffic is then immediately wrapped into mTLS by Linkerd 2 again. Thus we have a full end-to-end TLS encryption chain. +Through that setup, Emissary terminates external TLS as the gateway and traffic is then immediately wrapped into mTLS by Linkerd 2 again. Thus we have a full end-to-end TLS encryption chain. ## Getting started -In this guide, you will use Linkerd 2 Auto-Inject to mesh a service and use $productName$ to dynamically route requests to that service based on Linkerd 2's service discovery data. If you already have $productName$ installed, you will just need to install Linkerd 2 and deploy your service. +In this guide, you will use Linkerd 2 Auto-Inject to mesh a service and use Emissary to dynamically route requests to that service based on Linkerd 2's service discovery data. If you already have Emissary installed, you will just need to install Linkerd 2 and deploy your service. Setting up Linkerd 2 requires to install three components. The first is the CLI on your local machine, the second is the actual Linkerd 2 control plane in your Kubernetes Cluster. Finally, you have to inject your services' Pods with Linkerd Sidecars to mesh them. @@ -53,9 +53,9 @@ Setting up Linkerd 2 requires to install three components. The first is the CLI Note that this simple command automatically enables mTLS by default and registers the AutoInject Webhook with your Kubernetes API Server. You now have a production-ready Linkerd 2 setup rolled out into your cluster! -3. Deploy $productName$. This howto assumes you have already followed the $productName$ [Getting Started](../../tutorials/getting-started) guide. If you haven't done that already, you should do that now. +3. Deploy Emissary. This howto assumes you have already followed the Emissary [Getting Started](../../tutorials/getting-started) guide. If you haven't done that already, you should do that now. -4. Configure $productName$ to add it to the Linkerd 2 service mesh. +4. Configure Emissary to add it to the Linkerd 2 service mesh. ``` kubectl -n emissary get deploy emissary-ingress -o yaml | \ @@ -64,11 +64,11 @@ Setting up Linkerd 2 requires to install three components. The first is the CLI kubectl apply -f - ``` - This will tell $productName$ to add additional headers to each request forwarded to Linkerd 2 with information about where to route this request to. This is a general setting. You can also set `add_linkerd_headers` per [Mapping](../../topics/using/mappings). + This will tell Emissary to add additional headers to each request forwarded to Linkerd 2 with information about where to route this request to. This is a general setting. You can also set `add_linkerd_headers` per [Mapping](../../topics/using/mappings). ## Routing to Linkerd 2 services -You'll now register a demo application with Linkerd 2, and show how $productName$ can route to this application using endpoint data from Linkerd 2. +You'll now register a demo application with Linkerd 2, and show how Emissary can route to this application using endpoint data from Linkerd 2. 1. Enable [AutoInjection](https://linkerd.io/2/features/proxy-injection/) on the Namespace you are about to deploy to: ```yaml @@ -178,7 +178,7 @@ You'll now register a demo application with Linkerd 2, and show how $productName ``` kubectl apply -f qotm-mapping.yaml ``` - to apply this configuration to your Kubernetes cluster. Note that in the above config there is nothing special to make it work with Linkerd 2. The general config for $productName$ already adds Linkerd Headers when forwarding requests to the service mesh. + to apply this configuration to your Kubernetes cluster. Note that in the above config there is nothing special to make it work with Linkerd 2. The general config for Emissary already adds Linkerd Headers when forwarding requests to the service mesh. 1. Send a request to the `qotm-Linkerd2` API. @@ -188,19 +188,19 @@ You'll now register a demo application with Linkerd 2, and show how $productName {"hostname":"qotm-749c675c6c-hq58f","ok":true,"quote":"The last sentence you read is often sensible nonsense.","time":"2019-03-29T22:21:42.197663","version":"1.7"} ``` -Congratulations! You're successfully routing traffic to the QOTM application, the location of which is registered in Linkerd 2. The traffic to $productName$ is not TLS secured, but from $productName$ to the QOTM an automatic mTLS connection is being used. +Congratulations! You're successfully routing traffic to the QOTM application, the location of which is registered in Linkerd 2. The traffic to Emissary is not TLS secured, but from Emissary to the QOTM an automatic mTLS connection is being used. -If you now [configure TLS termination](../../topics/running/tls) in $productName$, you have an end-to-end secured connection. +If you now [configure TLS termination](../../topics/running/tls) in Emissary, you have an end-to-end secured connection. ## Multicluster operation -Linkerd 2.8 can support [multicluster operation](https://linkerd.io/2/features/multicluster/), where the Linkerd mesh transparently bridges from one cluster to another, allowing seamless access between the two. This works using the Linkerd "[service mirror controller](https://linkerd.io/2020/02/25/multicluster-kubernetes-with-service-mirroring/#step-1-service-discovery)" to discover services in the target cluster, and expose (mirror) them in the source cluster. Requests to mirrored services in the source cluster are transparently proxied via $productName$ in the target cluster to the appropriate target service, using Linkerd's [automatic mTLS](https://linkerd.io/2/features/automatic-mtls/) to protect the requests in flight between clusters. By configuring Linkerd to use the existing $productName$ as the ingress gateway between clusters, you eliminate the need to deploy and manage an additional ingress gateway. +Linkerd 2.8 can support [multicluster operation](https://linkerd.io/2/features/multicluster/), where the Linkerd mesh transparently bridges from one cluster to another, allowing seamless access between the two. This works using the Linkerd "[service mirror controller](https://linkerd.io/2020/02/25/multicluster-kubernetes-with-service-mirroring/#step-1-service-discovery)" to discover services in the target cluster, and expose (mirror) them in the source cluster. Requests to mirrored services in the source cluster are transparently proxied via Emissary in the target cluster to the appropriate target service, using Linkerd's [automatic mTLS](https://linkerd.io/2/features/automatic-mtls/) to protect the requests in flight between clusters. By configuring Linkerd to use the existing Emissary as the ingress gateway between clusters, you eliminate the need to deploy and manage an additional ingress gateway. ### Initial multicluster setup -1. Install $productName$ and the [Linkerd multicluster control plane](https://linkerd.io/2/tasks/installing-multicluster/). Make sure you've also linked the clusters. +1. Install Emissary and the [Linkerd multicluster control plane](https://linkerd.io/2/tasks/installing-multicluster/). Make sure you've also linked the clusters. -2. Inject $productName$ deployment with Linkerd (even if you have AutoInject enabled): +2. Inject Emissary deployment with Linkerd (even if you have AutoInject enabled): ``` kubectl -n emissary get deploy emissary-ingress -o yaml | \ @@ -210,19 +210,19 @@ Linkerd 2.8 can support [multicluster operation](https://linkerd.io/2/features/m kubectl apply -f - ``` - (It's important to require identity on the gateway port so that automatic mTLS works, but it's also important to let $productName$ handle its own ports. AutoInject can't handle this on its own.) + (It's important to require identity on the gateway port so that automatic mTLS works, but it's also important to let Emissary handle its own ports. AutoInject can't handle this on its own.) -3. Configure $productName$ as normal for your application. +3. Configure Emissary as normal for your application. -At this point, your $productName$ installation should work fine with multicluster Linkerd as a source cluster: you can configure Linkerd to bridge to a target cluster, and all should be well. +At this point, your Emissary installation should work fine with multicluster Linkerd as a source cluster: you can configure Linkerd to bridge to a target cluster, and all should be well. ### Using the cluster as a target cluster -Allowing the $productName$ installation to serve as a target cluster requires explicitly giving permission for Linkerd to mirror services from the cluster, and explicitly telling Linkerd to use $productName$ as the target gateway. +Allowing the Emissary installation to serve as a target cluster requires explicitly giving permission for Linkerd to mirror services from the cluster, and explicitly telling Linkerd to use Emissary as the target gateway. -1. Configure the target cluster $productName$ to allow insecure routing. +1. Configure the target cluster Emissary to allow insecure routing. - When $productName$ is running in a Linkerd mesh, Linkerd provides transport security, so connections coming in from the Linkerd in the source cluster will always be HTTP when they reach $productName$. Therefore, the `Host` CRDs corresponding to services that you'll be accessing from the source cluster *must* be configured to `Route` insecure requests. More information on this topic is available in the [`Host` documentation](../../topics/running/host-crd); an example might be + When Emissary is running in a Linkerd mesh, Linkerd provides transport security, so connections coming in from the Linkerd in the source cluster will always be HTTP when they reach Emissary. Therefore, the `Host` CRDs corresponding to services that you'll be accessing from the source cluster *must* be configured to `Route` insecure requests. More information on this topic is available in the [`Host` documentation](../../topics/running/host-crd); an example might be ```yaml apiVersion: getambassador.io/v3alpha1 @@ -238,7 +238,7 @@ Allowing the $productName$ installation to serve as a target cluster requires ex action: Route ``` -2. Configure the target cluster $productName$ to support Linkerd health checks. +2. Configure the target cluster Emissary to support Linkerd health checks. Multicluster Linkerd does its own health checks beyond what Kubernetes does, so a `Mapping` is needed to allow Linkerd's health checks to succeed: @@ -256,13 +256,13 @@ Allowing the $productName$ installation to serve as a target cluster requires ex bypass_auth: true ``` - When configuring $productName$, Kubernetes is usually configured to run health checks directly against port 8877 -- however, that port is not meant to be exposed outside the cluster. The `Mapping` permits accessing the health check endpoint without directly exposing the port. + When configuring Emissary, Kubernetes is usually configured to run health checks directly against port 8877 -- however, that port is not meant to be exposed outside the cluster. The `Mapping` permits accessing the health check endpoint without directly exposing the port. (The actual prefix in the `Mapping` is not terribly important, but it needs to match the metadata supplied to the service mirror controller, below.) -3. Configure the target cluster $productName$ for the service mirror controller. +3. Configure the target cluster Emissary for the service mirror controller. - This requires changes to the $productName$'s `deployment` and `service`. **For all of these commands, you will need to make sure your Kubernetes context is set to talk to the target cluster.** + This requires changes to the Emissary's `deployment` and `service`. **For all of these commands, you will need to make sure your Kubernetes context is set to talk to the target cluster.** In the `deployment`, you need the `config.linkerd.io/enable-gateway` `annotation`: @@ -279,7 +279,7 @@ Allowing the $productName$ installation to serve as a target cluster requires ex In the `service`, you need to provide appropriate named `port` definitions: - `mc-gateway` needs to be defined as `port` 4143 - - `mc-probe` needs to be defined as `port` 80, `targetPort` 8080 (or wherever $productName$ is listening) + - `mc-probe` needs to be defined as `port` 80, `targetPort` 8080 (or wherever Emissary is listening) ``` kubectl -n emissary patch svc emissary-ingress --type='json' -p='[ @@ -303,7 +303,7 @@ Allowing the $productName$ installation to serve as a target cluster requires ex (Here, the value of `mirror.linkerd.io/probe-path` must match the `prefix` using for the probe `Mapping` above.) -4. Configure individual exported services. Adding the following annotations to a service will tell the service to use $productName$ as the gateway: +4. Configure individual exported services. Adding the following annotations to a service will tell the service to use Emissary as the gateway: ``` kubectl -n $namespace patch svc $service -p=' @@ -314,7 +314,7 @@ Allowing the $productName$ installation to serve as a target cluster requires ex ' ``` - This annotation will tell Linkerd that the given service can be reached via the $productName$ in the `emissary` namespace. + This annotation will tell Linkerd that the given service can be reached via the Emissary in the `emissary` namespace. 5. Verify that all is well from the source cluster. @@ -326,7 +326,7 @@ Allowing the $productName$ installation to serve as a target cluster requires ex linkerd check --multicluster ``` - Next, make sure that the $productName$ gateway shows up when listing active gateways: + Next, make sure that the Emissary gateway shows up when listing active gateways: ``` linkerd multicluster gateways @@ -336,4 +336,4 @@ Allowing the $productName$ installation to serve as a target cluster requires ex ## More information -For more about $productName$'s integration with Linkerd 2, read the [service discovery configuration](../../topics/running/resolvers) documentation. For further reading about Linkerd 2 multi-cluster, see the [install documentation](https://linkerd.io/2/tasks/installing-multicluster/) and [introduction](https://linkerd.io/2/features/multicluster/). +For more about Emissary's integration with Linkerd 2, read the [service discovery configuration](../../topics/running/resolvers) documentation. For further reading about Linkerd 2 multi-cluster, see the [install documentation](https://linkerd.io/2/tasks/installing-multicluster/) and [introduction](https://linkerd.io/2/features/multicluster/). diff --git a/content/en/docs/2.5/howtos/prometheus.md b/content/en/docs/2.5/howtos/prometheus.md index e3468bc4..e64aa0cb 100644 --- a/content/en/docs/2.5/howtos/prometheus.md +++ b/content/en/docs/2.5/howtos/prometheus.md @@ -1,4 +1,6 @@ -# Monitoring with Prometheus and Grafana +--- +title: Monitoring with Prometheus and Grafana +--- Prometheus is an open-source monitoring and alerting system. When used along with Grafana, you can create a dynamic dashboard for monitoring @@ -7,28 +9,28 @@ ingress into our Kubernetes cluster. ## Deployment This guide will focus on deploying Prometheus and Grafana alongside -$productName$ in Kubernetes using the [Prometheus +Emissary in Kubernetes using the [Prometheus Operator](https://github.com/coreos/prometheus-operator). **Note:** Both Prometheus and Grafana can be deployed as standalone applications outside of Kubernetes. This process is well-documented within the website and docs within their respective projects. -### $productName$ +### Emissary -$productName$ makes it easy to output Envoy-generated +Emissary makes it easy to output Envoy-generated statistics to Prometheus. For the remainder of this guide, it is -assumed that you have installed and configured $productName$ +assumed that you have installed and configured Emissary into your Kubernetes cluster, and that it is possible for you to -modify the global configuration of the $productName$ +modify the global configuration of the Emissary deployment. -Starting with $productName$ `0.71.0`, Prometheus can scrape stats/metrics +Starting with Emissary `0.71.0`, Prometheus can scrape stats/metrics directly from Envoy's `/metrics` endpoint, removing the need to -[configure $productName$ to output stats to +[configure Emissary to output stats to StatsD](#statsd-exporter-output-statistics-to-productname). -The `/metrics` endpoint can be accessed internally via the $productName$ admin port (default 8877): +The `/metrics` endpoint can be accessed internally via the Emissary admin port (default 8877): ``` http(s)://ambassador:8877/metrics @@ -49,17 +51,17 @@ spec: service: localhost:8877 ``` -**Note**: Since `/metrics` in an endpoint on $productName$ +**Note**: Since `/metrics` in an endpoint on Emissary itself, the `service` field can just reference the admin port on localhost. ### Using the `cluster_tag` setting -The metrics that Prometheus scrapes from $productName$ are keyed using +The metrics that Prometheus scrapes from Emissary are keyed using the name of the Envoy [`cluster`](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/cluster_manager) that is handling traffic for a given `Mapping`. The name of a given -`cluster` is generated by $productName$ and, as such, is not necessarily +`cluster` is generated by Emissary and, as such, is not necessarily terribly readable. You can set the `cluster_tag` attribute within a @@ -78,6 +80,7 @@ standard YAML files. Alternatively, you can install it with follow the instructions in the README, or simply create the resources published in the YAML with `kubectl`. + ``` kubectl create -f https://raw.githubusercontent.com/coreos/prometheus-operator/master/bundle.yaml ``` @@ -147,13 +150,13 @@ standard YAML files. Alternatively, you can install it with Finally, we need to tell Prometheus where to scrape metrics from. The Prometheus Operator easily manages this using a `ServiceMonitor` CRD. To tell Prometheus to scrape metrics from - $productName$'s `/metrics` endpoint, copy the following + Emissary's `/metrics` endpoint, copy the following YAML to a file called `ambassador-monitor.yaml`, and apply it with `kubectl`. - If you are running an $productName$ version higher than 0.71.0 and + If you are running an Emissary version higher than 0.71.0 and want to scrape metrics directly from the `/metrics` endpoint of - $productName$ running in the `ambassador` namespace: + Emissary running in the `ambassador` namespace: ```yaml --- @@ -174,7 +177,7 @@ standard YAML files. Alternatively, you can install it with - port: ambassador-admin ``` -Prometheus is now configured to gather metrics from $productName$. +Prometheus is now configured to gather metrics from Emissary. ### Prometheus Operator with Helm @@ -188,7 +191,7 @@ will install Prometheus and configure it to monitor your Kubernetes cluster. This section will focus on setting up Prometheus to scrape stats from -$productName$. Configuration of the Helm Chart and analysis of +Emissary. Configuration of the Helm Chart and analysis of stats from other cluster components is outside of the scope of this documentation. @@ -204,9 +207,9 @@ documentation. that is looking for `ServiceMonitor`s with `label: release=prometheus`. - If you are running an $productName$ version higher than 0.71.0 and + If you are running an Emissary version higher than 0.71.0 and want to scrape metrics directly from the `/metrics` endpoint of - $productName$ running in the `default` namespace: + Emissary running in the `default` namespace: ```yaml --- @@ -250,7 +253,7 @@ documentation. - port: prometheus-metrics ``` -Prometheus is now configured to gather metrics from $productName$. +Prometheus is now configured to gather metrics from Emissary. #### Prometheus Operator CRDs @@ -284,12 +287,12 @@ section in the dashboard for each use case. a Grafana dashboard is created by default. You can use this dashboard or set `grafana.enabled: false` and follow the instructions below. -To deploy Grafana behind $productName$: replace -`{{AMBASSADOR_IP}}` with the IP address or DNS name of your $productName$ service, copy the YAML below, and apply it with `kubectl`: +To deploy Grafana behind Emissary: replace +`{{AMBASSADOR_IP}}` with the IP address or DNS name of your Emissary service, copy the YAML below, and apply it with `kubectl`: **Note:** If you forgot how to get the value of your `AMBASSADOR_IP` or have not set-up DNS, you can get the IP by using the `kubectl get services -n ambassador` -command, and select the External-IP of your $productName$ LoadBalancer service. +command, and select the External-IP of your Emissary LoadBalancer service. ```yaml --- @@ -369,7 +372,7 @@ spec: ``` Now, create a service and `Mapping` to expose Grafana behind -$productName$: +Emissary: **Note:** Don't forget to replace `{{GRAFANA_NAMESPACE}}` with the namespace you deployed Grafana to. In our example we used the default namespace, @@ -390,7 +393,7 @@ spec: Now, access Grafana by going to `{AMBASSADOR_IP}/grafana/` and logging in with `username: admin` : `password: admin`. -Before you can import the $productName$ dashboard. You need to add a data source. +Before you can import the Emissary dashboard. You need to add a data source. From the Grafana home page, select `Create your first data source`. Now, select 'Prometheus'. In the URL section, type in `http://prometheus.default:9090`. We deployed prometheus to the default namespace in our example, but if you @@ -404,12 +407,12 @@ From here, select the Prometheus data source we created from the `Prometheus` dr down menu, and select import to finish adding the dashboard. In the dashboard we just added, you should now be able to view graphs in the -`$productName$ Metrics Endpoint` tab. +`Emissary Metrics Endpoint` tab. ## Viewing stats/metrics -Above, you have created an environment where $productName$ is handling +Above, you have created an environment where Emissary is handling ingress traffic, Prometheus is scraping and collecting statistics from Envoy, and Grafana is displaying these statistics in a dashboard. @@ -431,7 +434,7 @@ kubectl port-forward service/prometheus 9090 and going to `http://localhost:9090/` from a web browser In the UI, click the dropdown and see all of the stats Prometheus is -able to scrape from $productName$. +able to scrape from Emissary. The Prometheus data model is, at its core, time-series based. Therefore, it makes it easy to represent rates, averages, @@ -443,9 +446,9 @@ full reference on how to work with this data model. ## Additional install options -### StatsD Exporter: Output statistics to $productName$ +### StatsD Exporter: Output statistics to Emissary -If running a pre-`0.71.0` version of $productName$, you will need to +If running a pre-`0.71.0` version of Emissary, you will need to configure Envoy to output stats to a separate collector before being scraped by Prometheus. You will use the [Prometheus StatsD Exporter](https://github.com/prometheus/statsd_exporter) to do this. @@ -456,10 +459,10 @@ Exporter](https://github.com/prometheus/statsd_exporter) to do this. kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/monitoring/statsd-sink.yaml ``` -2. Configure $productName$ to output statistics to `statsd` +2. Configure Emissary to output statistics to `statsd` - In the $productName$ deployment, add the `STATSD_ENABLED` - and `STATSD_HOST` environment variables to tell $productName$ where to output stats. + In the Emissary deployment, add the `STATSD_ENABLED` + and `STATSD_HOST` environment variables to tell Emissary where to output stats. ```yaml ... @@ -475,7 +478,7 @@ Exporter](https://github.com/prometheus/statsd_exporter) to do this. ... ``` -$productName$ is now configured to output statistics to the +Emissary is now configured to output statistics to the Prometheus StatsD exporter. #### ServiceMonitor diff --git a/content/en/docs/2.5/howtos/protecting-diag-access.md b/content/en/docs/2.5/howtos/protecting-diag-access.md index edbb34ae..ec601db2 100644 --- a/content/en/docs/2.5/howtos/protecting-diag-access.md +++ b/content/en/docs/2.5/howtos/protecting-diag-access.md @@ -1,11 +1,13 @@ -# Protecting Access to the Diagnostics Interface +--- +title: Protecting Access to the Diagnostics Interface +--- -Out of the box, $productName$ enables `Mapping`s to provide access to the diagnostics +Out of the box, Emissary enables `Mapping`s to provide access to the diagnostics interfaces that can help you debug your installation. In a production environment, though, public access to these endpoints is not an ideal situation. To solve this, we will be using the Ambassador `Module` to remove the default mappings, after which we'll create a new, host-based `mapping` to expose the diagnostics interface more securely. The -Ambassador `Module` applies system-wide configuration settings for $productName$ to follow. +Ambassador `Module` applies system-wide configuration settings for Emissary to follow. ```yaml apiVersion: getambassador.io/v3alpha1 diff --git a/content/en/docs/2.5/howtos/rate-limiting-tutorial.md b/content/en/docs/2.5/howtos/rate-limiting-tutorial.md index 5f4142fd..a15757e5 100644 --- a/content/en/docs/2.5/howtos/rate-limiting-tutorial.md +++ b/content/en/docs/2.5/howtos/rate-limiting-tutorial.md @@ -1,21 +1,21 @@ -import Alert from '@material-ui/lab/Alert'; - -# Basic rate limiting +--- +title: Basic Rate Limiting +--- -This guide applies to $OSSproductName$. It will not work correctly -on $AESproductName$. +This guide applies to Emissary. It will not work correctly +on Ambassador Edge Stack. -$productName$ can validate incoming requests before routing them to a backing service. In this tutorial, we'll configure $productName$ to use a simple third party rate limit service. (If you don't want to implement your own rate limiting service, $AESproductName$ integrates a [powerful, flexible rate limiting service](/docs/edge-stack/latest/topics/using/rate-limits/rate-limits/).) +Emissary can validate incoming requests before routing them to a backing service. In this tutorial, we'll configure Emissary to use a simple third party rate limit service. (If you don't want to implement your own rate limiting service, Ambassador Edge Stack integrates a [powerful, flexible rate limiting service](/docs/edge-stack/latest/topics/using/rate-limits/rate-limits/).) ## Before you get started -This tutorial assumes you have already followed the $productName$ [Installation](../../topics/install/) and [Quickstart Tutorial](../../tutorials/quickstart-demo) guides. If you haven't done that already, you should do so now. +This tutorial assumes you have already followed the Emissary [Installation](../../topics/install/) and [Quickstart Tutorial](../../tutorials/quickstart-demo) guides. If you haven't done that already, you should do so now. -Once completed, you'll have a Kubernetes cluster running $productName$ and the Quote service. Let's walk through adding rate limiting to this setup. +Once completed, you'll have a Kubernetes cluster running Emissary and the Quote service. Let's walk through adding rate limiting to this setup. ## 1. Deploy the rate limit service -$productName$ delegates the actual rate limit logic to a third party service. We've written a [simple rate limit service](https://github.com/emissary-ingress/emissary/tree/v2.1.0/docker/test-ratelimit) that: +Emissary delegates the actual rate limit logic to a third party service. We've written a [simple rate limit service](https://github.com/emissary-ingress/emissary/tree/v2.1.0/docker/test-ratelimit) that: - listens for requests on port 5000; - handles gRPC `shouldRateLimit` requests; @@ -75,17 +75,17 @@ spec: memory: 100Mi ``` -This configuration tells $productName$ about the rate limit service, notably that it is serving requests at `example-rate-limit:5000`. $productName$ will see the `RateLimitService` and reconfigure itself within a few +This configuration tells Emissary about the rate limit service, notably that it is serving requests at `example-rate-limit:5000`. Emissary will see the `RateLimitService` and reconfigure itself within a few seconds, allowing incoming requests to be rate-limited. Note that you can configure the `RateLimitService` to use a specific label `domain`. If `domain` is not specified (which is the situation here), the default is `ambassador`. -If $productName$ cannot contact the rate limit service, it will allow the request to be processed as if there were no rate limit service configuration. +If Emissary cannot contact the rate limit service, it will allow the request to be processed as if there were no rate limit service configuration. -## 2. Configure $productName$ Mappings +## 2. Configure Emissary Mappings -$productName$ only validates requests on `Mapping`s which set labels to use for rate limiting, +Emissary only validates requests on `Mapping`s which set labels to use for rate limiting, so you'll need to apply `labels` to your `Mapping`s to enable rate limiting. For more information on the labelling process, see the [Rate Limits configuration documentation](../../topics/using/rate-limits/). @@ -95,7 +95,7 @@ on the labelling process, see the [Rate Limits configuration documentation](../. apiVersion! -If $productName$ cannot contact the rate limit service, it will allow the request to be processed as if there were no rate limit service configuration. +If Emissary cannot contact the rate limit service, it will allow the request to be processed as if there were no rate limit service configuration. Replace the label that is applied to the `service-backend` with: @@ -130,7 +130,7 @@ spec: header_name: "x-ambassador-test-allow" ``` - + Note that the `key` could be anything you like, but our example rate limiting service expects it to match the name of the header. Also note that since our `RateLimitService` expects to use labels in the diff --git a/content/en/docs/2.5/howtos/route.md b/content/en/docs/2.5/howtos/route.md index b2d9dc0f..7fd0b04b 100644 --- a/content/en/docs/2.5/howtos/route.md +++ b/content/en/docs/2.5/howtos/route.md @@ -1,9 +1,8 @@ --- -description: "$productName$ uses the Mapping resource to map a resource, like a URL prefix, to a Kubernetes service or web service." +title: Mapping resource +description: "Emissary uses the Mapping resource to map a resource, like a URL prefix, to a Kubernetes service or web service." --- -import Alert from '@material-ui/lab/Alert'; - # Get traffic from the edge
@@ -19,13 +18,13 @@ import Alert from '@material-ui/lab/Alert';
-The core $productName$ resource used to manage cluster ingress is the `Mapping` resource. +The core Emissary resource used to manage cluster ingress is the `Mapping` resource. **A `Mapping` resource routes a URL path (or prefix) to a service (either a Kubernetes service or other web service).** Remember that Listener and Host resources are  - required for a functioning $productName$ installation that can route traffic!
+ required for a functioning Emissary installation that can route traffic!
Learn more about Listener.
Learn more about Host. @@ -49,8 +48,8 @@ spec: | Name | Type | Description | | :--- | :--- | :--- | | `metadata.name` | String | Identifies the Mapping. | -| `spec.prefix` | String | The URL prefix identifying your resource. [See below](#resources) on how $productName$ handles resources. | -| `spec.service` | String | The service handling the resource. If a Kubernetes service, it must include the namespace (in the format `service.namespace`) if the service is in a different namespace than $productName$. [See below](#services) on service name formatting.| +| `spec.prefix` | String | The URL prefix identifying your resource. [See below](#resources) on how Emissary handles resources. | +| `spec.service` | String | The service handling the resource. If a Kubernetes service, it must include the namespace (in the format `service.namespace`) if the service is in a different namespace than Emissary. [See below](#services) on service name formatting.| Here's another example using a web service that maps requests to `/httpbin/` to `http://httpbin.org` (again, **this is not a complete example on its own; see below**): @@ -72,7 +71,7 @@ spec: For demonstration purposes, here's a possible way of combining a `Listener`, a `Host`, and both `Mapping`s above that is complete and functional: - it will accept HTTP or HTTPS on port 8443; -- $productName$ is terminating TLS; +- Emissary is terminating TLS; - HTTPS to `foo.example.com` will be routed as above; - HTTP to `foo.example.com` will be redirected to HTTPS; - HTTP or HTTPS to other hostnames will be rejected; and @@ -149,7 +148,7 @@ Note the addition of `label`s and `selector`s to explicitly specify which resour ## Applying a Mapping resource -A Mapping resource can be managed using the same workflow as any other Kubernetes resources (like a Service or Deployment). For example, if the above Mapping is saved into a file called `httpbin-mapping.yaml`, the following command will apply the configuration directly to $productName$: +A Mapping resource can be managed using the same workflow as any other Kubernetes resources (like a Service or Deployment). For example, if the above Mapping is saved into a file called `httpbin-mapping.yaml`, the following command will apply the configuration directly to Emissary: ``` kubectl apply -f httpbin-mapping.yaml @@ -159,13 +158,13 @@ kubectl apply -f httpbin-mapping.yaml ## Resources -To $productName$, a resource is a group of one or more URLs that all share a common prefix in the URL path. For example, these URLs all share the `/resource1/` path prefix, so `/resource1/` can be considered a single resource: +To Emissary, a resource is a group of one or more URLs that all share a common prefix in the URL path. For example, these URLs all share the `/resource1/` path prefix, so `/resource1/` can be considered a single resource: * `https://ambassador.example.com/resource1/foo` * `https://ambassador.example.com/resource1/bar` * `https://ambassador.example.com/resource1/baz/zing` -On the other hand, these URLs share only the prefix `/` -- you _could_ tell $productName$ to treat them as a single resource, but it's probably not terribly useful. +On the other hand, these URLs share only the prefix `/` -- you _could_ tell Emissary to treat them as a single resource, but it's probably not terribly useful. * `https://ambassador.example.com/resource1/foo` * `https://ambassador.example.com/resource2/bar` @@ -173,7 +172,7 @@ On the other hand, these URLs share only the prefix `/` -- you _could_ tell $pro Note that the length of the prefix doesn't matter; a prefix like `/v1/this/is/my/very/long/resource/name/` is valid. -Also note that $productName$ does not actually require the prefix to start and end with `/` -- however, in practice, it's a good idea. Specifying a prefix of `/man` would match all of the following, which probably is not what was intended: +Also note that Emissary does not actually require the prefix to start and end with `/` -- however, in practice, it's a good idea. Specifying a prefix of `/man` would match all of the following, which probably is not what was intended: * `https://ambassador.example.com/man/foo` * `https://ambassador.example.com/mankind` @@ -181,11 +180,11 @@ Also note that $productName$ does not actually require the prefix to start and e ## Services -$productName$ routes traffic to a service. A service is defined as `[scheme://]service[.namespace][:port]`. Everything except for the service is optional. +Emissary routes traffic to a service. A service is defined as `[scheme://]service[.namespace][:port]`. Everything except for the service is optional. - `scheme` can be either `http` or `https`; if not present, the default is `http`. - `service` is the name of a service (typically the service name in Kubernetes or Consul); it is not allowed to contain the `.` character. -- `namespace` is the namespace in which the service is running. Starting with $productName$ 1.0.0, if not supplied, it defaults to the namespace in which the Mapping resource is defined. The default behavior can be configured using the [Module resource](../../topics/running/ambassador). When using a Consul resolver, `namespace` is not allowed. +- `namespace` is the namespace in which the service is running. Starting with Emissary 1.0.0, if not supplied, it defaults to the namespace in which the Mapping resource is defined. The default behavior can be configured using the [Module resource](../../topics/running/ambassador). When using a Consul resolver, `namespace` is not allowed. - `port` is the port to which a request should be sent. If not specified, it defaults to `80` when the scheme is `http` or `443` when the scheme is `https`. Note that the [resolver](../../topics/running/resolvers) may return a port in which case the `port` setting is ignored. While using service.namespace.svc.cluster.local may work for Kubernetes resolvers, the preferred syntax is service.namespace. @@ -220,19 +219,19 @@ spec: ## Best Practices -$productName$'s configuration is assembled from multiple YAML blocks which are managed by independent application teams. This implies that certain best practices should be followed. +Emissary's configuration is assembled from multiple YAML blocks which are managed by independent application teams. This implies that certain best practices should be followed. -#### $productName$'s configuration should be under version control. +#### Emissary's configuration should be under version control. -While you can always read back the $productName$'s configuration from Kubernetes or its diagnostic service, the $productName$ will not do versioning for you. +While you can always read back the Emissary's configuration from Kubernetes or its diagnostic service, the Emissary will not do versioning for you. -#### $productName$ tries to not start with a broken configuration, but it's not perfect. +#### Emissary tries to not start with a broken configuration, but it's not perfect. -Gross errors will result in the $productName$ refusing to start, in which case `kubectl logs` will be helpful. However, it's always possible to map a resource to the wrong service, or use the wrong `rewrite` rules. $productName$ can't detect that on its own, although its [diagnostic service](../../topics/running/diagnostics/) can help you figure it out. +Gross errors will result in the Emissary refusing to start, in which case `kubectl logs` will be helpful. However, it's always possible to map a resource to the wrong service, or use the wrong `rewrite` rules. Emissary can't detect that on its own, although its [diagnostic service](../../topics/running/diagnostics/) can help you figure it out. #### Be careful of mapping collisions. -If two different developers try to map `/myservice/` to something, this can lead to unexpected behavior. $productName$'s [canary deployment](../../topics/using/canary/) logic means that it's more likely that traffic will be split between them than that it will throw an error -- again, the diagnostic service can help you here. +If two different developers try to map `/myservice/` to something, this can lead to unexpected behavior. Emissary's [canary deployment](../../topics/using/canary/) logic means that it's more likely that traffic will be split between them than that it will throw an error -- again, the diagnostic service can help you here. #### Unless specified, mapping attributes cannot be applied to any other resource type. diff --git a/content/en/docs/2.5/howtos/tls-termination.md b/content/en/docs/2.5/howtos/tls-termination.md index d634c76b..10b4d612 100644 --- a/content/en/docs/2.5/howtos/tls-termination.md +++ b/content/en/docs/2.5/howtos/tls-termination.md @@ -1,19 +1,21 @@ -# TLS termination and enabling HTTPS +--- +title: TLS Termination and Enabling HTTPS +--- TLS encryption is one of the basic requirements of having a secure system. -$AESproductName$ [automatically enables TLS termination/HTTPs +Ambassador Edge Stack [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$ +While this automatic certificate management in Ambassador Edge Stack helps +simply TLS configuration in your cluster, the Open-Source Emissary 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$. +certificate to Ambassador Edge Stack. ## Prerequisites @@ -24,9 +26,9 @@ This guide requires you have the following installed: [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/) - [openssl](https://www.openssl.org/source/) -## Install $productName$ +## Install Emissary -[Install $productName$ in Kubernetes](../../topics/install). +[Install Emissary 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 @@ -50,7 +52,7 @@ spec: 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 +create a certificate and private key pair that Emissary can use for TLS termination. - Create a private key and certificate. @@ -72,7 +74,7 @@ termination. ## Store the certificate and key in a Kubernetes Secret -$productName$ dynamically loads TLS certificates by reading them from +Emissary 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. @@ -80,14 +82,14 @@ 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 +## Tell Emissary 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 +named `tls-cert`, we need to tell Emissary to use this certificate +for terminating TLS on a domain. A `Host` is used to tell Emissary which certificate to use for TLS termination on a domain. -Create the following `Host` to have $productName$ use the `Secret` we created +Create the following `Host` to have Emissary use the `Secret` we created above for terminating TLS on all domains. ```yaml @@ -107,7 +109,7 @@ spec: hostname: wildcard-host ``` -**Note:** If running multiple instances of $productName$ in one cluster remember to include the `ambassador_id` property in the `spec`, e.g.: +**Note:** If running multiple instances of Emissary in one cluster remember to include the `ambassador_id` property in the `spec`, e.g.: ```yaml --- @@ -126,14 +128,14 @@ 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 +Emissary 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 +First, make sure the Emissary service is listening on `443` and forwarding to port `8443`. Verify this with `kubectl`: ``` @@ -156,9 +158,9 @@ spec: ``` If the output to the `kubectl` command is not similar to the example above, -edit the $productName$ service to add the `https` port. +edit the Emissary service to add the `https` port. -After verifying $productName$ is listening on port 443, send a request +After verifying Emissary is listening on port 443, send a request to your backend service with curl: ``` @@ -176,20 +178,20 @@ 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. +This guide walked you through how to enable basic TLS termination in Emissary 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. +While a self-signed certificate is a simple and quick way to get Emissary 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$ +information on how to [use `cert-manager` with Emissary ](../cert-manager). ### Enable advanced TLS options -$productName$ exposes configuration for many more advanced options +Emissary 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/content/en/docs/2.5/howtos/tracing-datadog.md b/content/en/docs/2.5/howtos/tracing-datadog.md index d627e29f..842bc6a0 100644 --- a/content/en/docs/2.5/howtos/tracing-datadog.md +++ b/content/en/docs/2.5/howtos/tracing-datadog.md @@ -1,12 +1,14 @@ -# Distributed Tracing with Datadog +--- +title: 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. +In this tutorial, we'll configure Emissary 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. +This tutorial assumes you have already followed Emissary [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. +After completing the Getting Started guide you will have a Kubernetes cluster running Emissary and the Quote service. Let's walk through adding tracing to this setup. ## 1. Configure the DataDog agent @@ -16,7 +18,7 @@ You will need to configure the DataDog agent so that it uses a host-port and acc 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: +When using JSON logging with Envoy, Emissary will automatically append the `dd.trace_id` and `dd.span_id` properties to all logs so that correlation works: ```yaml --- @@ -31,7 +33,7 @@ spec: ## 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. +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 Emissary containers environment. ```yaml --- @@ -48,7 +50,7 @@ spec: ## 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. +Use `curl` to generate a few requests to an existing Emissary 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 diff --git a/content/en/docs/2.5/howtos/tracing-zipkin.md b/content/en/docs/2.5/howtos/tracing-zipkin.md index 37ddc902..874a2fb3 100644 --- a/content/en/docs/2.5/howtos/tracing-zipkin.md +++ b/content/en/docs/2.5/howtos/tracing-zipkin.md @@ -1,20 +1,20 @@ -import Alert from '@material-ui/lab/Alert'; - -# Distributed tracing with Zipkin +--- +title: Distributed tracing with Zipkin +--- -In this tutorial, we'll configure $productName$ to initiate a trace on some sample requests, and use Zipkin to visualize them. +In this tutorial, we'll configure Emissary to initiate a trace on some sample requests, and use Zipkin 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. +This tutorial assumes you have already followed Emissary [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. +After completing the Getting Started guide you will have a Kubernetes cluster running Emissary and the Quote service. Let's walk through adding tracing to this setup. ## 1. Deploy Zipkin -In this tutorial, you will use a simple deployment of the open-source [Zipkin](https://github.com/openzipkin/zipkin/wiki) distributed tracing system to store and visualize $productName$-generated traces. The trace data will be stored in memory within the Zipkin container, and you will be able to explore the traces via the Zipkin web UI. +In this tutorial, you will use a simple deployment of the open-source [Zipkin](https://github.com/openzipkin/zipkin/wiki) distributed tracing system to store and visualize Emissary-generated traces. The trace data will be stored in memory within the Zipkin container, and you will be able to explore the traces via the Zipkin web UI. -First, add the following YAML to a file named `zipkin.yaml`. This configuration will create a Zipkin Deployment that uses the [openzipkin/zipkin](https://hub.docker.com/r/openzipkin/zipkin/) container image and also an associated Service. We will also include a `TracingService` that configures $productName$ to use the Zipkin service (running on the default port of 9411) to provide tracing support. +First, add the following YAML to a file named `zipkin.yaml`. This configuration will create a Zipkin Deployment that uses the [openzipkin/zipkin](https://hub.docker.com/r/openzipkin/zipkin/) container image and also an associated Service. We will also include a `TracingService` that configures Emissary to use the Zipkin service (running on the default port of 9411) to provide tracing support. ```yaml --- @@ -70,18 +70,18 @@ Next, deploy this configuration into your cluster: $ kubectl apply -f zipkin.yaml ``` -As a final step we want to restart $productName$ as this is necessary to add the tracing header. This command will restart all the Pods (assuming $productName$ is installed in the ambassador namespace): +As a final step we want to restart Emissary as this is necessary to add the tracing header. This command will restart all the Pods (assuming Emissary is installed in the ambassador namespace): ``` $ kubectl -n ambassador rollout restart deploy ``` - Restarting $productName$ is required after deploying a Tracing Service for changes to take effect. + Restarting Emissary is required after deploying a Tracing Service for changes to take effect. ## 2. 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. +Use `curl` to generate a few requests to an existing Emissary `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/backend/ diff --git a/content/en/docs/2.5/howtos/websockets.md b/content/en/docs/2.5/howtos/websockets.md index 25cac7da..95925b23 100644 --- a/content/en/docs/2.5/howtos/websockets.md +++ b/content/en/docs/2.5/howtos/websockets.md @@ -1,6 +1,8 @@ -# WebSocket connections +--- +title: WebSockets +--- -$productName$ makes it easy to access your services from outside your +Emissary makes it easy to access your services from outside your application, and this includes services that use WebSockets. Only a small amount of additional configuration is required, which is as simple as telling the Mapping to allow "upgrading" from the HTTP protocol to diff --git a/content/en/docs/2.5/release-notes/edge-stack-1.13.4.png b/content/en/docs/2.5/release-notes/edge-stack-1.13.4.png deleted file mode 100644 index 954ac1a9..00000000 Binary files a/content/en/docs/2.5/release-notes/edge-stack-1.13.4.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/edge-stack-1.13.7-json-logging.png b/content/en/docs/2.5/release-notes/edge-stack-1.13.7-json-logging.png deleted file mode 100644 index 4a47cbdf..00000000 Binary files a/content/en/docs/2.5/release-notes/edge-stack-1.13.7-json-logging.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/edge-stack-1.13.7-memory.png b/content/en/docs/2.5/release-notes/edge-stack-1.13.7-memory.png deleted file mode 100644 index 9c415ba3..00000000 Binary files a/content/en/docs/2.5/release-notes/edge-stack-1.13.7-memory.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/edge-stack-1.13.7-tcpmapping-consul.png b/content/en/docs/2.5/release-notes/edge-stack-1.13.7-tcpmapping-consul.png deleted file mode 100644 index c455a47f..00000000 Binary files a/content/en/docs/2.5/release-notes/edge-stack-1.13.7-tcpmapping-consul.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/edge-stack-1.13.8-cloud-bugfix.png b/content/en/docs/2.5/release-notes/edge-stack-1.13.8-cloud-bugfix.png deleted file mode 100644 index 6beaf653..00000000 Binary files a/content/en/docs/2.5/release-notes/edge-stack-1.13.8-cloud-bugfix.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/edge-stack-2.0.0-host_crd.png b/content/en/docs/2.5/release-notes/edge-stack-2.0.0-host_crd.png deleted file mode 100644 index c77ef528..00000000 Binary files a/content/en/docs/2.5/release-notes/edge-stack-2.0.0-host_crd.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/edge-stack-2.0.0-ingressstatus.png b/content/en/docs/2.5/release-notes/edge-stack-2.0.0-ingressstatus.png deleted file mode 100644 index 6856d308..00000000 Binary files a/content/en/docs/2.5/release-notes/edge-stack-2.0.0-ingressstatus.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/edge-stack-2.0.0-insecure_action_hosts.png b/content/en/docs/2.5/release-notes/edge-stack-2.0.0-insecure_action_hosts.png deleted file mode 100644 index 79c20bad..00000000 Binary files a/content/en/docs/2.5/release-notes/edge-stack-2.0.0-insecure_action_hosts.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/edge-stack-2.0.0-listener.png b/content/en/docs/2.5/release-notes/edge-stack-2.0.0-listener.png deleted file mode 100644 index ea45a02b..00000000 Binary files a/content/en/docs/2.5/release-notes/edge-stack-2.0.0-listener.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/edge-stack-2.0.0-prune_routes.png b/content/en/docs/2.5/release-notes/edge-stack-2.0.0-prune_routes.png deleted file mode 100644 index bc43229f..00000000 Binary files a/content/en/docs/2.5/release-notes/edge-stack-2.0.0-prune_routes.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/edge-stack-2.0.0-tlscontext.png b/content/en/docs/2.5/release-notes/edge-stack-2.0.0-tlscontext.png deleted file mode 100644 index 68dbad80..00000000 Binary files a/content/en/docs/2.5/release-notes/edge-stack-2.0.0-tlscontext.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/edge-stack-2.0.0-v3alpha1.png b/content/en/docs/2.5/release-notes/edge-stack-2.0.0-v3alpha1.png deleted file mode 100644 index c0ac3596..00000000 Binary files a/content/en/docs/2.5/release-notes/edge-stack-2.0.0-v3alpha1.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/emissary-1.13.10-cors-origin.png b/content/en/docs/2.5/release-notes/emissary-1.13.10-cors-origin.png deleted file mode 100644 index b7538e5f..00000000 Binary files a/content/en/docs/2.5/release-notes/emissary-1.13.10-cors-origin.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/emissary-ga.png b/content/en/docs/2.5/release-notes/emissary-ga.png deleted file mode 100644 index 062f043a..00000000 Binary files a/content/en/docs/2.5/release-notes/emissary-ga.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/tada.png b/content/en/docs/2.5/release-notes/tada.png deleted file mode 100644 index c8832e8e..00000000 Binary files a/content/en/docs/2.5/release-notes/tada.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/v2.0.4-k8s-1.22.png b/content/en/docs/2.5/release-notes/v2.0.4-k8s-1.22.png deleted file mode 100644 index ed9b0415..00000000 Binary files a/content/en/docs/2.5/release-notes/v2.0.4-k8s-1.22.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/v2.0.4-l7depth.png b/content/en/docs/2.5/release-notes/v2.0.4-l7depth.png deleted file mode 100644 index 9314324c..00000000 Binary files a/content/en/docs/2.5/release-notes/v2.0.4-l7depth.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/v2.0.4-mapping-dns-type.png b/content/en/docs/2.5/release-notes/v2.0.4-mapping-dns-type.png deleted file mode 100644 index 7770c77d..00000000 Binary files a/content/en/docs/2.5/release-notes/v2.0.4-mapping-dns-type.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/v2.0.4-v3alpha1.png b/content/en/docs/2.5/release-notes/v2.0.4-v3alpha1.png deleted file mode 100644 index 9c50b8fb..00000000 Binary files a/content/en/docs/2.5/release-notes/v2.0.4-v3alpha1.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/v2.0.4-version.png b/content/en/docs/2.5/release-notes/v2.0.4-version.png deleted file mode 100644 index 9481b7db..00000000 Binary files a/content/en/docs/2.5/release-notes/v2.0.4-version.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/v2.0.5-auth-circuit-breaker.png b/content/en/docs/2.5/release-notes/v2.0.5-auth-circuit-breaker.png deleted file mode 100644 index cac8cf7b..00000000 Binary files a/content/en/docs/2.5/release-notes/v2.0.5-auth-circuit-breaker.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/v2.0.5-mappingselector.png b/content/en/docs/2.5/release-notes/v2.0.5-mappingselector.png deleted file mode 100644 index 31942ede..00000000 Binary files a/content/en/docs/2.5/release-notes/v2.0.5-mappingselector.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/v2.1.0-canary.png b/content/en/docs/2.5/release-notes/v2.1.0-canary.png deleted file mode 100644 index 39d3bbbf..00000000 Binary files a/content/en/docs/2.5/release-notes/v2.1.0-canary.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/v2.1.0-gzip-enabled.png b/content/en/docs/2.5/release-notes/v2.1.0-gzip-enabled.png deleted file mode 100644 index 061fcbc9..00000000 Binary files a/content/en/docs/2.5/release-notes/v2.1.0-gzip-enabled.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/v2.1.0-smoother-migration.png b/content/en/docs/2.5/release-notes/v2.1.0-smoother-migration.png deleted file mode 100644 index ebd77497..00000000 Binary files a/content/en/docs/2.5/release-notes/v2.1.0-smoother-migration.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/v2.1.2-annotations.png b/content/en/docs/2.5/release-notes/v2.1.2-annotations.png deleted file mode 100644 index b5498c3c..00000000 Binary files a/content/en/docs/2.5/release-notes/v2.1.2-annotations.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/v2.1.2-host-mapping-matching.png b/content/en/docs/2.5/release-notes/v2.1.2-host-mapping-matching.png deleted file mode 100644 index 1cfba5ed..00000000 Binary files a/content/en/docs/2.5/release-notes/v2.1.2-host-mapping-matching.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/v2.1.2-mapping-cors.png b/content/en/docs/2.5/release-notes/v2.1.2-mapping-cors.png deleted file mode 100644 index f76ea01c..00000000 Binary files a/content/en/docs/2.5/release-notes/v2.1.2-mapping-cors.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/v2.1.2-mapping-less-weighted.png b/content/en/docs/2.5/release-notes/v2.1.2-mapping-less-weighted.png deleted file mode 100644 index 7e299062..00000000 Binary files a/content/en/docs/2.5/release-notes/v2.1.2-mapping-less-weighted.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/v2.1.2-mapping-no-rewrite.png b/content/en/docs/2.5/release-notes/v2.1.2-mapping-no-rewrite.png deleted file mode 100644 index 5d3d5a29..00000000 Binary files a/content/en/docs/2.5/release-notes/v2.1.2-mapping-no-rewrite.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/v2.2.0-cloud.png b/content/en/docs/2.5/release-notes/v2.2.0-cloud.png deleted file mode 100644 index 5923fcb4..00000000 Binary files a/content/en/docs/2.5/release-notes/v2.2.0-cloud.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/v2.2.0-percent-escape.png b/content/en/docs/2.5/release-notes/v2.2.0-percent-escape.png deleted file mode 100644 index df4d81b9..00000000 Binary files a/content/en/docs/2.5/release-notes/v2.2.0-percent-escape.png and /dev/null differ diff --git a/content/en/docs/2.5/release-notes/v2.2.0-tls-cert-validation.png b/content/en/docs/2.5/release-notes/v2.2.0-tls-cert-validation.png deleted file mode 100644 index f8635b5a..00000000 Binary files a/content/en/docs/2.5/release-notes/v2.2.0-tls-cert-validation.png and /dev/null differ diff --git a/content/en/docs/2.5/releaseNotes.yml b/content/en/docs/2.5/releaseNotes.yml deleted file mode 100644 index a0d0c3ca..00000000 --- a/content/en/docs/2.5/releaseNotes.yml +++ /dev/null @@ -1,1143 +0,0 @@ -# -*- fill-column: 100 -*- - -# This file should be placed in the folder for the version of the -# product that's meant to be documented. A `/release-notes` page will -# be automatically generated and populated at build time. -# -# Note that an entry needs to be added to the `doc-links.yml` file in -# order to surface the release notes in the table of contents. -# -# The YAML in this file should contain: -# -# changelog: An (optional) URL to the CHANGELOG for the product. -# items: An array of releases with the following attributes: -# - version: The (optional) version number of the release, if applicable. -# - date: The date of the release in the format YYYY-MM-DD. -# - notes: An array of noteworthy changes included in the release, each having the following attributes: -# - type: The type of change, one of `bugfix`, `feature`, `security` or `change`. -# - title: A short title of the noteworthy change. -# - body: >- -# Two or three sentences describing the change and why it -# is noteworthy. This is HTML, not plain text or -# markdown. It is handy to use YAML's ">-" feature to -# allow line-wrapping. -# - image: >- -# The URL of an image that visually represents the -# noteworthy change. This path is relative to the -# `release-notes` directory; if this file is -# `FOO/releaseNotes.yml`, then the image paths are -# relative to `FOO/release-notes/`. -# - docs: The path to the documentation page where additional information can be found. -# - href: A path from the root to a resource on the getambassador website, takes precedence over a docs link. - -changelog: https://github.com/emissary-ingress/emissary/blob/$branch$/CHANGELOG.md -items: - - 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: 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 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: Properly populate alt_state_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: 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/content/en/docs/2.5/topics/_index.md b/content/en/docs/2.5/topics/_index.md new file mode 100644 index 00000000..4beca302 --- /dev/null +++ b/content/en/docs/2.5/topics/_index.md @@ -0,0 +1,4 @@ +--- +title: "Topics" +weight: 30 +--- diff --git a/content/en/docs/2.5/topics/concepts/index.md b/content/en/docs/2.5/topics/concepts/_index.md similarity index 81% rename from content/en/docs/2.5/topics/concepts/index.md rename to content/en/docs/2.5/topics/concepts/_index.md index 2d02a027..df88d005 100644 --- a/content/en/docs/2.5/topics/concepts/index.md +++ b/content/en/docs/2.5/topics/concepts/_index.md @@ -1,4 +1,7 @@ -# Core concepts +--- +title: "Core Concepts" +description: "This section of the documentation introduces core concepts of Kubernetes and Emissary" +--- 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. diff --git a/content/en/docs/2.5/topics/concepts/architecture.md b/content/en/docs/2.5/topics/concepts/architecture.md index 4ef23b74..c4c9c12c 100644 --- a/content/en/docs/2.5/topics/concepts/architecture.md +++ b/content/en/docs/2.5/topics/concepts/architecture.md @@ -1,27 +1,30 @@ -# The $productName$ architecture +--- +title: "Architecture" +description: "This section of the documentation provides an overview of the Emissary architecture" +--- -## $productName$ is a control plane +## Emissary 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). +Emissary 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, Emissary 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). ![Architecture](../../../images/ambassador-arch.png) ## 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. +2. When the manifest is applied to the cluster, the Kubernetes API notifies Emissary of the change. +3. Emissary 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. +Emissary relies on Kubernetes for scaling, high availability, and persistence. All Emissary configuration is stored directly in Kubernetes; there is no database. Emissary is packaged as a single container that contains both the control plane and an Envoy Proxy instance. By default, Emissary 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. +By design, Emissary is an entirely stateless architecture. Each individual Emissary instance operates independently of other instances. These Emissary instances rely on Kubernetes to coordinate the configuration between the different Emissary instances. This enables Emissary 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$. +Emissary closely tracks Envoy Proxy releases. A stable branch of Envoy Proxy is maintained that enables the team to cherry-pick specific fixes into Emissary. diff --git a/content/en/docs/2.5/topics/concepts/gitops-continuous-delivery.md b/content/en/docs/2.5/topics/concepts/gitops-continuous-delivery.md index 336a1c66..c8878695 100644 --- a/content/en/docs/2.5/topics/concepts/gitops-continuous-delivery.md +++ b/content/en/docs/2.5/topics/concepts/gitops-continuous-delivery.md @@ -1,14 +1,19 @@ +--- +title: "Operating Model" +description: "This section of the documentation provides an overview of the operating model of Emissary" +--- + # 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. +Emissary configuration is built on the concept of _policies_. A policy is a statement of intent and codified in a declarative configuration file. Emissary 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. +Because many different teams may need to write policies, Emissary supports a decentralized configuration model. Individual policies are written in different files. Emissary aggregates all policies into one master policy configuration for the edge. ## Continuous delivery and GitOps @@ -39,28 +44,28 @@ Contrast this a **traditional, manual workflow:** The self-service, continuous delivery model is critical for ensuring that edge operations can scale. -## Continuous delivery, GitOps, and $productName$ +## Continuous delivery, GitOps, and Emissary -Adopting a continuous delivery workflow with $productName$ via GitOps provides several advantages: +Adopting a continuous delivery workflow with Emissary 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. +2. **Auditability**: Understanding the specific configuration of Emissary 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 + whether the component is Kubernetes, Emissary, 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: +In a typical Emissary GitOps workflow: -* Each service has its own $productName$ policy. This policy consists of one or more $productName$ custom resource definitions, specified in YAML. +* Each service has its own Emissary policy. This policy consists of one or more Emissary 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. +* The [AppDirect engineering team](https://blog.getambassador.io/fireside-chat-with-alex-gervais-accelerating-appdirect-developer-workflow-with-ambassador-7586597b1c34) writes Emissary 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/content/en/docs/2.5/topics/concepts/kubernetes-network-architecture.md b/content/en/docs/2.5/topics/concepts/kubernetes-network-architecture.md index 6650aa60..f50fbbb7 100644 --- a/content/en/docs/2.5/topics/concepts/kubernetes-network-architecture.md +++ b/content/en/docs/2.5/topics/concepts/kubernetes-network-architecture.md @@ -1,4 +1,7 @@ -# Kubernetes Network architecture +--- +title: "Kubernetes Network Architecture" +description: "This section of the documentation provides an overview of the Kubernetes network architecture" +--- ## Kubernetes has its own isolated network @@ -34,7 +37,7 @@ The most popular approach to configuring edge proxies is with the Kubernetes ing The ingress resource is a Kubernetes standard. As such, it is a lowest common denominator resource. In practice, users find that the ingress resource is insufficient in scope to address the requirements for edge routing. Semantics such as TLS termination, redirecting to TLS, timeouts, rate limiting, and authentication are all beyond the scope of the ingress resource. -$productName$ can function as an ingress controller (i.e., it reads ingress resources), although it also includes many other capabilities that are beyond the scope of the ingress specification. Most $productName$ users find that the various additional capabilities of $productName$ are essential, and end up using $productName$'s extensions to the ingress resource, instead of using ingress resources themselves. +Emissary can function as an ingress controller (i.e., it reads ingress resources), although it also includes many other capabilities that are beyond the scope of the ingress specification. Most Emissary users find that the various additional capabilities of Emissary are essential, and end up using Emissary's extensions to the ingress resource, instead of using ingress resources themselves. ### Kubernetes services and Pods @@ -44,7 +47,7 @@ When traffic is routed to the pods via a Kubernetes service, Kubernetes uses a b Traffic can also be routed directly to pods, bypassing the Kubernetes service. Since pods are much more ephemeral than Kubernetes services, this approach requires an edge proxy that is optimized for this use case. In particular, the edge proxy needs to support real-time discovery of pods, and be able to dynamically update pod locations without downtime. -$productName$ supports routing both to Kubernetes services and directly to pods. +Emissary supports routing both to Kubernetes services and directly to pods. ## Further reading diff --git a/content/en/docs/2.5/topics/concepts/microservices-api-gateways.md b/content/en/docs/2.5/topics/concepts/microservices-api-gateways.md index ba95b8fc..923d0491 100644 --- a/content/en/docs/2.5/topics/concepts/microservices-api-gateways.md +++ b/content/en/docs/2.5/topics/concepts/microservices-api-gateways.md @@ -1,4 +1,7 @@ -# Microservices API gateways +--- +title: "Microservices & API gateways" +description: "This section of the documentation provides an overview of microserverse and API Gateways" +--- A microservices API gateway is an API gateway designed to accelerate the development workflow of independent services teams. A microservices API gateway provides all the functionality for a team to independently publish, monitor, and update a microservice. diff --git a/content/en/docs/2.5/topics/concepts/progressive-delivery.md b/content/en/docs/2.5/topics/concepts/progressive-delivery.md index 4e2f0d42..dd86753a 100644 --- a/content/en/docs/2.5/topics/concepts/progressive-delivery.md +++ b/content/en/docs/2.5/topics/concepts/progressive-delivery.md @@ -1,4 +1,6 @@ -# Progressive delivery +--- +title: "Progressive Delivery" +--- Today's cloud-native applications may consist of hundreds of services, each of which are being updated at any time. Thus, many cloud-native organizations augment regression test strategies with testing in production using progressive delivery techniques. @@ -18,7 +20,7 @@ There are a number of different strategies for progressive delivery. These inclu Observability is a critical requirement for testing in production. Regardless of progressive delivery strategy, collecting key metrics around latency, traffic, errors, and saturation (the [“Four Golden Signals of Monitoring”](https://landing.google.com/sre/sre-book/chapters/monitoring-distributed-systems/#xref_monitoring_golden-signals)) provides valuable insight into the stability and performance of a new version of the service. Moreover, application developers can compare the metrics (e.g., latency) between the production version and an updated version. If the metrics are similar, then updates can proceed with much greater confidence. -$productName$ supports a variety of strategies for progressive delivery. These strategies are discussed in further detail below. +Emissary supports a variety of strategies for progressive delivery. These strategies are discussed in further detail below. ### Canary releases diff --git a/content/en/docs/2.5/topics/concepts/rate-limiting-at-the-edge.md b/content/en/docs/2.5/topics/concepts/rate-limiting-at-the-edge.md index 1f849861..106cf6c5 100644 --- a/content/en/docs/2.5/topics/concepts/rate-limiting-at-the-edge.md +++ b/content/en/docs/2.5/topics/concepts/rate-limiting-at-the-edge.md @@ -1,4 +1,6 @@ -# Rate limiting concepts at the edge +--- +title: "Rate limiting at the edge" +--- Rate limiting at the edge is a technique that is used to prevent a sudden or sustained increase in user traffic from breaking an API or underlying service. On the Internet, users can do whatever they want to your APIs, as you have no direct control over these end-users. Whether it’s intentional or not, these users can impact the availability, responsiveness, and scalability of your service. @@ -22,9 +24,9 @@ The table below outlines several scenarios where rate limiting and load shedding ## Avoiding contention with rate limiting configuration: Decoupling Dev and Ops -One of the core features of $productName$ is the decentralization of configuration, allowing operations and development teams to independently control $productName$, as well as individual application development teams to minimize collaboration when configuring independently deployable services. This same approach applies to rate limiting configuration. +One of the core features of Emissary is the decentralization of configuration, allowing operations and development teams to independently control Emissary, as well as individual application development teams to minimize collaboration when configuring independently deployable services. This same approach applies to rate limiting configuration. -The $productName$ rate limiting configuration allows centralized operations teams to define and implement global rate limiting and load shedding policies to protect the system, while still allowing individual application teams to define rate limiting policies that enforce business rules, for example, around paying and non-paying customers (perhaps implementing the so-called “freemium” model). See [Advanced Rate Limiting](../../../howtos/advanced-rate-limiting) documentation for examples. +The Emissary rate limiting configuration allows centralized operations teams to define and implement global rate limiting and load shedding policies to protect the system, while still allowing individual application teams to define rate limiting policies that enforce business rules, for example, around paying and non-paying customers (perhaps implementing the so-called “freemium” model). See [Advanced Rate Limiting](../../../howtos/advanced-rate-limiting) documentation for examples. ## Benefits of applying a rate limiter to the edge diff --git a/content/en/docs/3.1/topics/install/index.md b/content/en/docs/2.5/topics/install/_index.md similarity index 52% rename from content/en/docs/3.1/topics/install/index.md rename to content/en/docs/2.5/topics/install/_index.md index 40fa95fd..c0c54068 100644 --- a/content/en/docs/3.1/topics/install/index.md +++ b/content/en/docs/2.5/topics/install/_index.md @@ -1,34 +1,36 @@ -import Alert from '@material-ui/lab/Alert'; -import './index.less' +--- +title: "Install" +description: "This section of the documentation provides installation instructions" +--- -# Installing $productName$ +# Installing Emissary ## Install with Helm Helm, the package manager for Kubernetes, is the recommended way to install -$productName$. Full details are in the [Helm instructions.](helm/) +Emissary. 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 +Another way to install Emissary 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/) +The Docker install will let you try the Emissary locally in seconds, +but is not supported for production workloads. [Try Emissary 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/) +If you already have an existing installation of Ambassador Edge Stack or +Emissary, 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. +we publish Ambassador Edge Stack and Emissary releases to multiple registries. Starting with version 1.0.0, you can pull the emissary image from any of the following registries: @@ -36,12 +38,12 @@ Starting with version 1.0.0, you can pull the emissary image from any of the fol - `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). +your production needs for Ambassador Edge Stack or Emissary. Read more about +[Running Emissary 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$ +Emissary has a comprehensive range of [features](/features/) to +support the requirements of any edge microservice. To learn more about how Emissary works, along with use cases, best practices, and more, +check out the [Welcome page](../../tutorials/getting-started) or read the [Emissary Story](../../about/why-ambassador). diff --git a/content/en/docs/2.5/topics/install/ambassador-oss-community.md b/content/en/docs/2.5/topics/install/ambassador-oss-community.md index b53d1407..e4150e2f 100644 --- a/content/en/docs/2.5/topics/install/ambassador-oss-community.md +++ b/content/en/docs/2.5/topics/install/ambassador-oss-community.md @@ -1,14 +1,14 @@ -# Integration in community projects +--- +title: Integration to community projects +--- -import Table from "../../../../../src/components/CommunityTable"; - -**$AESproductName$ is now available and includes additional functionality beyond the current $OSSproductName$.** +**Ambassador Edge Stack is now available and includes additional functionality beyond the current Emissary.** These features include automatic HTTPS, OAuth/OpenID Connect authentication support, integrated rate limiting, a developer portal, and [more](/edge-stack-faq/). -## $OSSproductName$ integrations +## Emissary integrations -If you still want to use just $OSSproductName$, don't worry! $OSSproductName$ +If you still want to use just Emissary, don't worry! Emissary is currently available out-of-the-box in some Kubernetes installers and local environments. - \ No newline at end of file +
diff --git a/content/en/docs/2.5/topics/install/bare-metal.md b/content/en/docs/2.5/topics/install/bare-metal.md index 84ac1c8d..7a7cbfb5 100644 --- a/content/en/docs/2.5/topics/install/bare-metal.md +++ b/content/en/docs/2.5/topics/install/bare-metal.md @@ -1,12 +1,12 @@ -import Alert from '@material-ui/lab/Alert'; - -# Install with bare metal +--- +title: Bare metal +--- -In cloud environments, provisioning a readily available network load balancer with $productName$ is the best option for handling ingress into your Kubernetes cluster. When running Kubernetes on a bare metal setup, where network load balancers are not available by default, we need to consider different options for exposing $productName$. +In cloud environments, provisioning a readily available network load balancer with Emissary is the best option for handling ingress into your Kubernetes cluster. When running Kubernetes on a bare metal setup, where network load balancers are not available by default, we need to consider different options for exposing Emissary. -## Exposing $productName$ via NodePort +## Exposing Emissary via NodePort -The simplest way to expose an application in Kubernetes is via a `NodePort` service. In this configuration, we create the $productName$ service] and identify `type: NodePort` instead of `LoadBalancer`. Kubernetes will then create a service and assign that service a port to be exposed externally and direct traffic to $productName$ via the defined `port`. +The simplest way to expose an application in Kubernetes is via a `NodePort` service. In this configuration, we create the Emissary service] and identify `type: NodePort` instead of `LoadBalancer`. Kubernetes will then create a service and assign that service a port to be exposed externally and direct traffic to Emissary via the defined `port`. ```yaml --- @@ -26,15 +26,15 @@ spec: service: ambassador ``` -Using a `NodePort` leaves $productName$ isolated from the host network, allowing the Kubernetes service to handle routing to $productName$ pods. You can drop-in this YAML to replace the `LoadBalancer` service in the [YAML installation guide](../yaml-install) and use `http://:/` as the host for requests. +Using a `NodePort` leaves Emissary isolated from the host network, allowing the Kubernetes service to handle routing to Emissary pods. You can drop-in this YAML to replace the `LoadBalancer` service in the [YAML installation guide](../yaml-install) and use `http://:/` as the host for requests. -## Exposing $productName$ via host network +## Exposing Emissary via host network -When running $productName$ on a bare metal install of Kubernetes, you have the option to configure $productName$ pods to use the network of the host they are running on. This method allows you to bind $productName$ directly to port 80 or 443 so you won't need to identify the port in requests. +When running Emissary on a bare metal install of Kubernetes, you have the option to configure Emissary pods to use the network of the host they are running on. This method allows you to bind Emissary directly to port 80 or 443 so you won't need to identify the port in requests. i.e `http://:/` becomes `http:///` -This can be configured by setting `hostNetwork: true` in the $productName$ deployment. `dnsPolicy: ClusterFirstWithHostNet` will also need to set to tell $productName$ to use *KubeDNS* when attempting to resolve mappings. +This can be configured by setting `hostNetwork: true` in the Emissary deployment. `dnsPolicy: ClusterFirstWithHostNet` will also need to set to tell Emissary to use *KubeDNS* when attempting to resolve mappings. ```diff --- @@ -88,6 +88,6 @@ spec: restartPolicy: Always ``` -This configuration does not require a defined $productName$ service, so you can remove that service if you have defined one. +This configuration does not require a defined Emissary service, so you can remove that service if you have defined one. -**Note:** Before configuring $productName$ with this method, consider some of the functionality that is lost by bypassing the Kubernetes service including only having one $productName$ able to bind to port 8080 or 8443 per node and losing any load balancing that is typically performed by Kubernetes services. +**Note:** Before configuring Emissary with this method, consider some of the functionality that is lost by bypassing the Kubernetes service including only having one Emissary able to bind to port 8080 or 8443 per node and losing any load balancing that is typically performed by Kubernetes services. diff --git a/content/en/docs/2.5/topics/install/convert-to-v3alpha1.md b/content/en/docs/2.5/topics/install/convert-to-v3alpha1.md index e12d9aed..53e8f932 100644 --- a/content/en/docs/2.5/topics/install/convert-to-v3alpha1.md +++ b/content/en/docs/2.5/topics/install/convert-to-v3alpha1.md @@ -1,18 +1,18 @@ -import Alert from '@material-ui/lab/Alert'; - -# Convert Configuration Resources to `getambassador.io/v3alpha1` +--- +title: Convert to v3alpha1 +--- -Once your $productName$ $version$ installation is running, it is **strongly recommended** that +Once your Emissary $version$ installation is running, it is **strongly recommended** that you convert your existing configuration resources from `getambassador.io/v2` to `getambassador.io/v3alpha1`. While it is not necessary to convert all your resources to getambassador.io/v3alpha1 - immediately, you should ultimately update them all for full functionality with $productName$ + immediately, you should ultimately update them all for full functionality with Emissary In general, the best way to convert any resource is to start with `kubectl get`: using -`kubectl get -o yaml` on any `getambassador.io/v2` resource will cause $productName$ to +`kubectl get -o yaml` on any `getambassador.io/v2` resource will cause Emissary to translate it to a `getambassador.io/v3alpha1` resource. You can then verify that the `getambassador.io/v3alpha1` resource looks correct and re-apply it, which will convert the stored copy to `getambassador.io/v3alpha1`. @@ -23,10 +23,10 @@ As you do the conversion, here are the things to bear in mind: `getambassador.io/v2` allowed `ambassador_id` to be either an array of strings, or a simple string. In `getambassador.io/v3alpha1`, only the array form is supported: instead of -`ambassador_id: "foo"`, use `ambassador_id: [ "foo" ]`. This applies to all $productName$ +`ambassador_id: "foo"`, use `ambassador_id: [ "foo" ]`. This applies to all Emissary resources, and is supported by all versions of Ambassador 1.X. -## 2. You must have a `Listener` for each port on which $productName$ should listen. +## 2. You must have a `Listener` for each port on which Emissary should listen. Learn more about Listener @@ -38,7 +38,7 @@ are matched with them (see below). ## 3. `Listener`, `Host`, and `Mapping` must be explicit about how they associate. -You need to have `Listener`s, `Host`s, and `Mapping`s correctly associated with each other for $productName$ 2.X configuration. +You need to have `Listener`s, `Host`s, and `Mapping`s correctly associated with each other for Emissary 2.X configuration. ### 3.1. `Listener` and `Host` are associated through `Listener.hostBinding` @@ -76,8 +76,8 @@ can also result in larger Envoy configurations that slow reconfiguration. ### 3.2. `Host` and `Mapping` are associated through `Host.mappingSelector` -In $productName$ 1.X, `Mapping`s were nearly always associated with every `Host`. Since this -tends to result in larger Envoy configurations that slow down reconfiguration, $productName$ 2.X +In Emissary 1.X, `Mapping`s were nearly always associated with every `Host`. Since this +tends to result in larger Envoy configurations that slow down reconfiguration, Emissary 2.X inverts this behavior: **`Host` and `Mapping` will not associate without explicit selection**. To have a `Mapping` associate with a `Host`, at least one of the following must hold: @@ -117,7 +117,7 @@ has no `mappingSelector`, and Learn more about TLSContext -In $productName$ 1.X, simply creating a `TLSContext` is sufficient to terminate TLS, but in +In Emissary 1.X, simply creating a `TLSContext` is sufficient to terminate TLS, but in 2.X you _must_ use a `Host`. The minimal setup to terminate TLS is now something like this: ```yaml @@ -265,7 +265,7 @@ certificate (the semantic of `tls: true`), omit the `tls` element and prefix the A few settings have moved from the `Module` in 2.0. Make sure you review the following settings and move them to their new locations if you are using them in a `Module`: -- Configuration for the `PROXY` protocol is part of the `Listener` resource in $productName$ 2.0, +- Configuration for the `PROXY` protocol is part of the `Listener` resource in Emissary 2.0, so the `use_proxy_protocol` element of the `ambassador` `Module` is no longer supported. - `xff_num_trusted_hops` has been removed from the `Module`, and its functionality has been moved diff --git a/content/en/docs/2.5/topics/install/docker.md b/content/en/docs/2.5/topics/install/docker.md index e430a55c..f2ad9db5 100644 --- a/content/en/docs/2.5/topics/install/docker.md +++ b/content/en/docs/2.5/topics/install/docker.md @@ -1,22 +1,22 @@ -import Alert from '@material-ui/lab/Alert'; +--- +title: Docker +--- -# Run the demo with Docker - -In this Docker quickstart guide, we'll get $productName$ running locally +In this Docker quickstart guide, we'll get Emissary running locally with a demo configuration. In the next section, we'll then walk through how to -deploy $productName$ in Kubernetes with a custom configuration. +deploy Emissary in Kubernetes with a custom configuration. ## 1. Running the demo configuration -By default, $productName$ uses a demo configuration to show some of its basic features. Get it running with Docker, and expose $productName$ on port 8080: +By default, Emissary uses a demo configuration to show some of its basic features. Get it running with Docker, and expose Emissary on port 8080: ``` docker run -it -p 8080:8080 --name=$productDeploymentName$ --rm docker.io/emissaryingress/emissary:$version$ --demo ``` -## 2. $productName$'s diagnostics +## 2. Emissary's diagnostics -$productName$ provides live diagnostics viewable with a web browser. While this would normally not be exposed to the public network, the Docker demo publishes the diagnostics service at the following URL: +Emissary provides live diagnostics viewable with a web browser. While this would normally not be exposed to the public network, the Docker demo publishes the diagnostics service at the following URL: `http://localhost:8080/ambassador/v0/diag/` @@ -26,11 +26,11 @@ We'll talk more about authentication shortly. To access the Diagnostics page with authentication, use `curl http://localhost:8080/ambassador/v0/diag/ -u admin:admin` -Some of the most important information - your $productName$ version, how recently $productName$'s configuration was updated, and how recently Envoy last reported status to $productName$ - is right at the top. The diagnostics overview can show you what it sees in your configuration map, and which Envoy objects were created based on your configuration. +Some of the most important information - your Emissary version, how recently Emissary's configuration was updated, and how recently Envoy last reported status to Emissary - is right at the top. The diagnostics overview can show you what it sees in your configuration map, and which Envoy objects were created based on your configuration. ## 3. The Quote service -Since $productName$ is a comprehensive, self-service edge stack, its primary purpose is to provide access and control to microservices for the teams that manage them. The demo is preconfigured with a mapping that connects the `/qotm/` resource to the "Quote" service -- a demo service that supplies quotations. You can try it out by opening +Since Emissary is a comprehensive, self-service edge stack, its primary purpose is to provide access and control to microservices for the teams that manage them. The demo is preconfigured with a mapping that connects the `/qotm/` resource to the "Quote" service -- a demo service that supplies quotations. You can try it out by opening `http://localhost:8080/qotm/` @@ -46,7 +46,7 @@ You can see details of the mapping by clicking the blue `http://localhost:8080/q ## 4. Authentication -On the diagnostic overview, you can also see that $productName$ is configured to do authentication -- in the middle of the overview page, you'll see the `Ambassador Services In Use` section, and you can click the `tcp://127.0.0.1:5050` link for details on the `AuthService` configuration. This demo auth service is running inside the Docker container with $productName$ and the Quote service, and $productName$ uses it to mediate access to everything behind $productName$. +On the diagnostic overview, you can also see that Emissary is configured to do authentication -- in the middle of the overview page, you'll see the `Ambassador Services In Use` section, and you can click the `tcp://127.0.0.1:5050` link for details on the `AuthService` configuration. This demo auth service is running inside the Docker container with Emissary and the Quote service, and Emissary uses it to mediate access to everything behind Emissary. You saw above that access to the diagnostic overview required you to authenticate as an administrator. Getting a random quote does not require authentication, but to get a specific quote, you'll have to authenticate as a demo user. To see this in action, open @@ -66,8 +66,8 @@ curl -Lv -u username:password 'http://localhost:8080/qotm/quote/5?json=true' will succeed. (Note that that's literally "username" and "password" -- the demo auth service is deliberately not very secure!) -Note that it's up to the auth service to decide what needs authentication -- teaming $productName$ with an authentication service can be as flexible or strict as you need it to be. +Note that it's up to the auth service to decide what needs authentication -- teaming Emissary with an authentication service can be as flexible or strict as you need it to be. ## Next steps -We've just walked through some of the core features of $productName$ in a local configuration. To see $productName$ in action on Kubernetes, check out the [Installation Guide](../). +We've just walked through some of the core features of Emissary in a local configuration. To see Emissary in action on Kubernetes, check out the [Installation Guide](../). diff --git a/content/en/docs/2.5/topics/install/helm.md b/content/en/docs/2.5/topics/install/helm.md index 4c8a9836..3b2f2aa5 100644 --- a/content/en/docs/2.5/topics/install/helm.md +++ b/content/en/docs/2.5/topics/install/helm.md @@ -1,21 +1,21 @@ -import Alert from '@material-ui/lab/Alert'; - -# Install with Helm +--- +title: Helm +--- - To migrate from $productName$ 1.X to $productName$ 2.X, see the - [$productName$ migration matrix](../migration-matrix/). This guide + To migrate from Emissary 1.X to Emissary 2.X, see the + [Emissary migration matrix](../migration-matrix/). This guide **will not work** for that, due to changes to the configuration - resources used for $productName$ 2.X. + resources used for Emissary 2.X. -[Helm](https://helm.sh) is a package manager for Kubernetes that automates the release and management of software on Kubernetes. $productName$ can be installed via a Helm chart with a few simple steps, depending on if you are deploying for the first time, upgrading $productName$ from an existing installation, or migrating from $productName$. +[Helm](https://helm.sh) is a package manager for Kubernetes that automates the release and management of software on Kubernetes. Emissary can be installed via a Helm chart with a few simple steps, depending on if you are deploying for the first time, upgrading Emissary from an existing installation, or migrating from Emissary. ## Before you begin -The $productName$ Helm chart is hosted by Datawire and published at `https://app.getambassador.io`. +The Emissary Helm chart is hosted by Datawire and published at `https://app.getambassador.io`. Start by adding this repo to your helm client with the following command: @@ -26,11 +26,11 @@ helm repo update ## Install with Helm -When you run the Helm chart, it installs $productName$. +When you run the Helm chart, it installs Emissary. -1. Install the $productName$ CRDs. +1. Install the Emissary CRDs. - Before installing $productName$ $version$ itself, you must configure your + Before installing Emissary $version$ itself, you must configure your Kubernetes cluster to support the `getambassador.io/v3alpha1` and `getambassador.io/v2` configuration resources. This is required. @@ -40,9 +40,9 @@ When you run the Helm chart, it installs $productName$. ``` - $productName$ $version$ includes a Deployment in the `emissary-system` namespace + Emissary $version$ includes a Deployment in the `emissary-system` namespace called emissary-apiext. This is the APIserver extension - that supports converting $productName$ CRDs between getambassador.io/v2 + that supports converting Emissary CRDs between getambassador.io/v2 and getambassador.io/v3alpha1. This Deployment needs to be running at all times. @@ -54,11 +54,11 @@ When you run the Helm chart, it installs $productName$. - There is a known issue with the 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. + There is a known issue with the emissary-apiext service that impacts all Emissary 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 Emissary/Ambassador Edge Stack 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. -2. Install the $productName$ Chart with the following command: +2. Install the Emissary Chart with the following command: ``` helm install -n $productNamespace$ --create-namespace \ @@ -68,21 +68,21 @@ When you run the Helm chart, it installs $productName$. 3. Next Steps - $productName$ shold now be successfully installed and running, but in order to get started deploying Services and test routing to them you need to configure a few more resources. + Emissary shold now be successfully installed and running, but in order to get started deploying Services and test routing to them you need to configure a few more resources. - - [The `Listener` Resource](../../running/listener/) is required to configure which ports the $productName$ pods listen on so that they can begin responding to requests. + - [The `Listener` Resource](../../running/listener/) is required to configure which ports the Emissary pods listen on so that they can begin responding to requests. - [The `Mapping` Resouce](../../using/intro-mappings/) is used to configure routing requests to services in your cluster. - [The `Host` Resource](../../running/host-crd/) configures TLS termination for enablin HTTPS communication. - - Explore how $productName$ [configures communication with clients](../../../howtos/configure-communications) + - Explore how Emissary [configures communication with clients](../../../howtos/configure-communications) - We strongly recommend following along with our Quickstart Guide to get started by creating a Listener, deploying a simple service to test with, and setting up a Mapping to route requests from $productName$ to the demo service. + We strongly recommend following along with our Quickstart Guide to get started by creating a Listener, deploying a simple service to test with, and setting up a Mapping to route requests from Emissary to the demo service. - $productName$ $version$ includes a Deployment in the $productNamespace$ namespace + Emissary $version$ includes a Deployment in the $productNamespace$ namespace called emissary-apiext. This is the APIserver extension - that supports converting $productName$ CRDs between getambassador.io/v2 + that supports converting Emissary CRDs between getambassador.io/v2 and getambassador.io/v3alpha1. This Deployment needs to be running at all times. @@ -99,4 +99,4 @@ For more advanced configuration and details about helm values, ## Upgrading an existing installation See the [migration matrix](../migration-matrix) for instructions about upgrading -$productName$. +Emissary. diff --git a/content/en/docs/2.5/topics/install/index.less b/content/en/docs/2.5/topics/install/index.less deleted file mode 100644 index bc649e7c..00000000 --- a/content/en/docs/2.5/topics/install/index.less +++ /dev/null @@ -1,57 +0,0 @@ -@media (max-width: 769px) { - #index-installContainer { - flex-direction: column; - } - .index-dropdown { - width: auto; - } - .index-dropBtn { - width: 100%; - } -} - -.index-dropBtn { - background-color: #8e77ff; - color: white; - padding: 10px; - font-size: 16px; - border: none; - margin-top: -20px; -} - -.index-dropdown { - position: relative; - display: inline-block; -} - -.index-dropdownContent { - display: none; - position: absolute; - background-color: #f1f1f1; - width: 100%; - box-shadow: 0px 8px 16px 0px rgba(0, 0, 0, 0.2); - z-index: 1; -} - -.index-dropdownContent a { - color: black; - padding: 12px 16px; - text-decoration: none; - display: block; -} - -.index-dropdownContent a:hover { - background-color: #ddd; -} - -.index-dropdown:hover .index-dropdownContent { - display: block; -} - -.index-dropdown:hover .index-dropBtn { - background-color: #5f3eff; -} - -#index-installContainer { - display: flex; -} diff --git a/content/en/docs/2.5/topics/install/index.md b/content/en/docs/2.5/topics/install/index.md deleted file mode 100644 index 40fa95fd..00000000 --- a/content/en/docs/2.5/topics/install/index.md +++ /dev/null @@ -1,47 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; -import './index.less' - -# Installing $productName$ - -## 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/content/en/docs/2.5/topics/install/migrate-to-2-alternate.md b/content/en/docs/2.5/topics/install/migrate-to-2-alternate.md index d0b791a1..ff958ce9 100644 --- a/content/en/docs/2.5/topics/install/migrate-to-2-alternate.md +++ b/content/en/docs/2.5/topics/install/migrate-to-2-alternate.md @@ -1,36 +1,37 @@ -import Alert from '@material-ui/lab/Alert'; +--- +title: Migrate to Emissary 2.x +description: "Instructions for how to upgrade Emissary to 2.x. Transfer your current configuration of Ambassador Edge Stack or Emissary to 2.x" +--- -# Upgrading $productName$ with a separate cluster - -You can upgrade from any version of $AESproductName$ or $OSSproductName$ to +You can upgrade from any version of Ambassador Edge Stack or Emissary 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$: +For example, to upgrade from some other version of Ambassador Edge Stack or +Emissary to Emissary $version$: -1. Install $productName$ $version$ in a completely new cluster. +1. Install Emissary $version$ in a completely new cluster. -2. **Create `Listener`s for $productName$ $version$.** +2. **Create `Listener`s for Emissary $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$ + When Emissary $version$ starts, it will not have any `Listener`s, and it will not + create any. You must create `Listener` resources by hand, or Emissary $version$ will not listen on any ports. -3. Copy the entire configuration from the $productName$ 1.X cluster to the $productName$ +3. Copy the entire configuration from the Emissary 1.X cluster to the Emissary $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` + This will create `getambassador.io/v2` resources in the Emissary $version$ cluster. + Emissary $version$ will translate them internally to `getambassador.io/v3alpha1` resources. -4. Each $productName$ instance has its own cluster, so you can test the new +4. Each Emissary 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$ +6. Once everything is working with both versions, transfer incoming traffic to the Emissary $version$ cluster. diff --git a/content/en/docs/2.5/topics/install/migration-matrix.md b/content/en/docs/2.5/topics/install/migration-matrix.md index b4f658ac..54dae07d 100644 --- a/content/en/docs/2.5/topics/install/migration-matrix.md +++ b/content/en/docs/2.5/topics/install/migration-matrix.md @@ -1,42 +1,42 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrading $productName$ +--- +title: Migration Matrix +--- Read the instructions below before making any changes to your cluster! -There are currently multiple paths for upgrading $productName$, depending on what version you're currently -running, what you want to be running, and whether you installed $productName$ using [Helm](../helm) or +There are currently multiple paths for upgrading Emissary, depending on what version you're currently +running, what you want to be running, and whether you installed Emissary using [Helm](../helm) or YAML. -(To check out if you installed $productName$ using Helm, run `helm list --all` and see if -$productName$ is listed. If so, you installed using Helm.) +(To check out if you installed Emissary using Helm, run `helm list --all` and see if +Emissary is listed. If so, you installed using Helm.) Read the instructions below before making any changes to your cluster! -## If you are currently running $AESproductName$ +## If you are currently running Ambassador Edge Stack -See the [instructions on updating $AESproductName$](../../../../../edge-stack/$aesDocsVersion$/topics/install/migration-matrix). +See the [instructions on updating Ambassador Edge Stack](../../../../../edge-stack/$aesDocsVersion$/topics/install/migration-matrix). -## If you installed $OSSproductName$ using Helm +## If you installed Emissary using Helm | If you're running. | You can upgrade to | |----------------------------------|----------------------------------------------------------------------------------------------------------------------------| -| $OSSproductName$ $version$ | [$AESproductName$ $aesVersion$](/docs/edge-stack/$aesDocsVersion$/topics/install/upgrade/helm/emissary-2.5/edge-stack-2.5) | -| $OSSproductName$ 2.4.X | [$OSSproductName$ $version$](../upgrade/helm/emissary-2.4/emissary-2.5) | -| $OSSproductName$ 2.0.5 | [$OSSproductName$ $version$](../upgrade/helm/emissary-2.0/emissary-2.5) | -| $OSSproductName$ 1.14.X | [$OSSproductName$ $version$](../upgrade/helm/emissary-1.14/emissary-2.5) | -| $OSSproductName$ prior to 1.14.X | [$OSSproductName$ 1.14.X](../../../../1.14/topics/install/upgrading) | +| Emissary $version$ | [Ambassador Edge Stack $aesVersion$](/docs/edge-stack/$aesDocsVersion$/topics/install/upgrade/helm/emissary-2.5/edge-stack-2.5) | +| Emissary 2.4.X | [Emissary $version$](../upgrade/helm/emissary-2.4/emissary-2.5) | +| Emissary 2.0.5 | [Emissary $version$](../upgrade/helm/emissary-2.0/emissary-2.5) | +| Emissary 1.14.X | [Emissary $version$](../upgrade/helm/emissary-1.14/emissary-2.5) | +| Emissary prior to 1.14.X | [Emissary 1.14.X](../../../../1.14/topics/install/upgrading) | -## If you installed $OSSproductName$ manually by applying YAML +## If you installed Emissary manually by applying YAML | If you're running. | You can upgrade to | |----------------------------------|----------------------------------------------------------------------------------------------------------------------------| -| $OSSproductName$ $version$ | [$AESproductName$ $aesVersion$](/docs/edge-stack/$aesDocsVersion$/topics/install/upgrade/yaml/emissary-2.5/edge-stack-2.5) | -| $OSSproductName$ 2.4.X | [$OSSproductName$ $version$](../upgrade/yaml/emissary-2.4/emissary-2.5) | -| $OSSproductName$ 2.0.5 | [$OSSproductName$ $version$](../upgrade/yaml/emissary-2.0/emissary-2.5) | -| $OSSproductName$ 1.14.X | [$OSSproductName$ $version$](../upgrade/yaml/emissary-1.14/emissary-2.5) | -| $OSSproductName$ prior to 1.14.X | [$OSSproductName$ 1.14.X](../../../../1.14/topics/install/upgrading) | +| Emissary $version$ | [Ambassador Edge Stack $aesVersion$](/docs/edge-stack/$aesDocsVersion$/topics/install/upgrade/yaml/emissary-2.5/edge-stack-2.5) | +| Emissary 2.4.X | [Emissary $version$](../upgrade/yaml/emissary-2.4/emissary-2.5) | +| Emissary 2.0.5 | [Emissary $version$](../upgrade/yaml/emissary-2.0/emissary-2.5) | +| Emissary 1.14.X | [Emissary $version$](../upgrade/yaml/emissary-1.14/emissary-2.5) | +| Emissary prior to 1.14.X | [Emissary 1.14.X](../../../../1.14/topics/install/upgrading) | diff --git a/content/en/docs/2.5/topics/install/upgrade/_index.md b/content/en/docs/2.5/topics/install/upgrade/_index.md new file mode 100644 index 00000000..65f73d96 --- /dev/null +++ b/content/en/docs/2.5/topics/install/upgrade/_index.md @@ -0,0 +1,4 @@ +--- +title: Upgrade +weight: -10 +--- diff --git a/content/en/docs/2.5/topics/install/upgrade/helm/_index.md b/content/en/docs/2.5/topics/install/upgrade/helm/_index.md new file mode 100644 index 00000000..a7e3d4b1 --- /dev/null +++ b/content/en/docs/2.5/topics/install/upgrade/helm/_index.md @@ -0,0 +1,3 @@ +--- +title: Helm +--- diff --git a/content/en/docs/2.5/topics/install/upgrade/helm/emissary-1.14/_index.md b/content/en/docs/2.5/topics/install/upgrade/helm/emissary-1.14/_index.md new file mode 100644 index 00000000..a1248d01 --- /dev/null +++ b/content/en/docs/2.5/topics/install/upgrade/helm/emissary-1.14/_index.md @@ -0,0 +1,3 @@ +--- +title: 1.14 +--- diff --git a/content/en/docs/2.5/topics/install/upgrade/helm/emissary-1.14/emissary-2.5.md b/content/en/docs/2.5/topics/install/upgrade/helm/emissary-1.14/emissary-2.5.md index dc4c9e41..3d7ec376 100644 --- a/content/en/docs/2.5/topics/install/upgrade/helm/emissary-1.14/emissary-2.5.md +++ b/content/en/docs/2.5/topics/install/upgrade/helm/emissary-1.14/emissary-2.5.md @@ -1,9 +1,9 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 1.14.X to $productName$ $version$ (Helm) +--- +title: 1.14.x to 2.x +--- - This guide covers migrating from $productName$ 1.14.X to $productName$ $version$. If + This guide covers migrating from Emissary 1.14.X to Emissary $version$. If this is not your exact situation, see the migration matrix. @@ -14,12 +14,12 @@ import Alert from '@material-ui/lab/Alert'; upgrade instructions. -We're pleased to introduce $productName$ $version$! The 2.X family introduces a number of -changes to allow $productName$ to more gracefully handle larger installations (including +We're pleased to introduce Emissary $version$! The 2.X family introduces a number of +changes to allow Emissary to more gracefully handle larger installations (including multitenant or multiorganizational installations), reduce memory footprint, and improve -performance. In keeping with [SemVer](https://semver.org), $productName$ 2.X introduces +performance. In keeping with [SemVer](https://semver.org), Emissary 2.X introduces some changes that aren't backward-compatible with 1.X. These changes are detailed in -[Major Changes in $productName$ 2.X](../../../../../../about/changes-2.x/). +[Major Changes in Emissary 2.X](../../../../../../about/changes-2.x/). ## Migration Overview @@ -28,35 +28,35 @@ some changes that aren't backward-compatible with 1.X. These changes are detaile cluster! -The recommended strategy for migration is to run $productName$ 1.14 and $productName$ -$version$ side-by-side in the same cluster. This gives $productName$ $version$ -and $productName$ 1.14 access to all the same configuration resources, with some +The recommended strategy for migration is to run Emissary 1.14 and Emissary +$version$ side-by-side in the same cluster. This gives Emissary $version$ +and Emissary 1.14 access to all the same configuration resources, with some important caveats: -1. **$productName$ 1.14 will not see any `getambassador.io/v3alpha1` resources.** +1. **Emissary 1.14 will not see any `getambassador.io/v3alpha1` resources.** This is intentional; it provides a way to apply configuration only to - $productName$ $version$, while not interfering with the operation of your - $productName$ 1.14 installation. + Emissary $version$, while not interfering with the operation of your + Emissary 1.14 installation. 2. **If needed, you can use labels to further isolate configurations.** - If you need to prevent your $productName$ $version$ installation from - seeing a particular bit of $productName$ 1.14 configuration, you can apply + If you need to prevent your Emissary $version$ installation from + seeing a particular bit of Emissary 1.14 configuration, you can apply a Kubernetes label to the configuration resources that should be seen by - your $productName$ $version$ installation, then set its + your Emissary $version$ installation, then set its `AMBASSADOR_LABEL_SELECTOR` environment variable to restrict its 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$ $version$, then set + that should be visible to Emissary $version$, then set `AMBASSADOR_LABEL_SELECTOR=version-two=true` in its Deployment. 3. **Be careful about label selectors on Kubernetes Services!** - If you have services in $productName$ 1.14 that use selectors that will match - Pods from $productName$ $version$, traffic will be erroneously split between - $productName$ 1.14 and $productName$ $version$. The labels used by $productName$ + If you have services in Emissary 1.14 that use selectors that will match + Pods from Emissary $version$, traffic will be erroneously split between + Emissary 1.14 and Emissary $version$. The labels used by Emissary $version$ include: ```yaml @@ -68,20 +68,20 @@ important caveats: profile: main ``` -4. **Be careful to only have one $productName$ Agent running at a time.** +4. **Be careful to only have one Emissary Agent running at a time.** - The $productName$ Agent is responsible for communications between - $productName$ and Ambassador Cloud. If multiple versions of the Agent are + The Emissary Agent is responsible for communications between + Emissary and Ambassador Cloud. If multiple versions of the Agent are running simultaneously, Ambassador Cloud could see conflicting information about your cluster. The best way to avoid multiple agents when installing with Helm is to use `--set agent.enabled=false` to tell Helm not to install a new Agent with - $productName$ $version$. Once testing is done, you can switch Agents safely. + Emissary $version$. Once testing is done, you can switch Agents safely. -You can also migrate by [installing $productName$ $version$ in a separate cluster](../../../../migrate-to-2-alternate). -This permits absolute certainty that your $productName$ 1.14 configuration will not be -affected by changes meant for $productName$ $version$, and it eliminates concerns about +You can also migrate by [installing Emissary $version$ in a separate cluster](../../../../migrate-to-2-alternate). +This permits absolute certainty that your Emissary 1.14 configuration will not be +affected by changes meant for Emissary $version$, and it eliminates concerns about ACME, but it is more effort. ## Side-by-Side Migration Steps @@ -90,7 +90,7 @@ Migration is a seven-step process: 1. **Make sure that older configuration resources are not present.** - $productName$ 2.X does not support `getambassador.io/v0` or `getambassador.io/v1` + Emissary 2.X does not support `getambassador.io/v0` or `getambassador.io/v1` resources, and Kubernetes will not permit removing support for CRD versions that are still in use for stored resources. To verify that no resources older than `getambassador.io/v2` are active, run @@ -106,10 +106,10 @@ Migration is a seven-step process: 2. **Install new CRDs.** - Before installing $productName$ $version$ itself, you must configure your + Before installing Emissary $version$ itself, you must configure your Kubernetes cluster to support its new `getambassador.io/v3alpha1` configuration resources. Note that `getambassador.io/v2` resources are still supported, but **you - must install support for `getambassador.io/v3alpha1`** to run $productName$ $version$, + must install support for `getambassador.io/v3alpha1`** to run Emissary $version$, even if you intend to continue using only `getambassador.io/v2` resources for some time. @@ -119,9 +119,9 @@ Migration is a seven-step process: ``` - $productName$ $version$ includes a Deployment in the `emissary-system` namespace + Emissary $version$ includes a Deployment in the `emissary-system` namespace called emissary-apiext. This is the APIserver extension - that supports converting $productName$ CRDs between getambassador.io/v2 + that supports converting Emissary CRDs between getambassador.io/v2 and getambassador.io/v3alpha1. This Deployment needs to be running at all times. @@ -133,14 +133,14 @@ Migration is a seven-step process: - There is a known issue with the 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. + There is a known issue with the emissary-apiext service that impacts all Emissary 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 Emissary/Ambassador Edge Stack 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. -3. **Install $productName$ $version$.** +3. **Install Emissary $version$.** - After installing the new CRDs, you need to install $productName$ $version$ itself - **in the same namespace as your existing $productName$ 1.14 installation**. It's important + After installing the new CRDs, you need to install Emissary $version$ itself + **in the same namespace as your existing Emissary 1.14 installation**. It's important to use the same namespace so that the two installations can see the same secrets, etc. Start by making sure that your `emissary` Helm repo is set correctly: @@ -151,8 +151,8 @@ Migration is a seven-step process: helm repo update ``` - Typically, $productName$ 1.14 was installed in the `ambassador` namespace. If you installed - $productName$ 1.14 in a different namespace, change the namespace in the commands below. + Typically, Emissary 1.14 was installed in the `ambassador` namespace. If you installed + Emissary 1.14 in a different namespace, change the namespace in the commands below. - If you do not need to set `AMBASSADOR_LABEL_SELECTOR`: @@ -174,14 +174,14 @@ Migration is a seven-step process: ``` - You must use the $productHelmName$ Helm chart for $productName$ 2.X. + You must use the $productHelmName$ Helm chart for Emissary 2.X. Do not use the ambassador Helm chart. - $productName$ $version$ includes a Deployment in the $productNamespace$ namespace + Emissary $version$ includes a Deployment in the $productNamespace$ namespace called emissary-apiext. This is the APIserver extension - that supports converting $productName$ CRDs between getambassador.io/v2 + that supports converting Emissary CRDs between getambassador.io/v2 and getambassador.io/v3alpha1. This Deployment needs to be running at all times. @@ -194,9 +194,9 @@ Migration is a seven-step process: 4. **Install `Listener`s and `Host`s as needed.** - An important difference between $productName$ 1.14 and $productName$ $version$ is the + An important difference between Emissary 1.14 and Emissary $version$ is the new **mandatory** `Listener` CRD. Also, when running both installations side by side, - you will need to make sure that a `Host` is present for the new $productName$ $version$ + you will need to make sure that a `Host` is present for the new Emissary $version$ Service. For example: ```bash @@ -237,15 +237,15 @@ Migration is a seven-step process: EOF ``` - This example requires that you know the hostname for the $productName$ Service (`$EMISSARY_HOSTNAME`) + This example requires that you know the hostname for the Emissary Service (`$EMISSARY_HOSTNAME`) and that you have created a TLS Secret for it in `$EMISSARY_TLS_SECRET`. 5. **Test!** - Your $productName$ $version$ installation can support the `getambassador.io/v2` - configuration resources used by $productName$ 1.14, but you may need to make some + Your Emissary $version$ installation can support the `getambassador.io/v2` + configuration resources used by Emissary 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) + [configuring Emissary Communications](../../../../../../howtos/configure-communications) and [updating CRDs to `getambassador.io/v3alpha1`](../../../../convert-to-v3alpha1). @@ -253,24 +253,24 @@ Migration is a seven-step process: with the same name as a getambassador.io/v2 resource or vice versa: only one version can be stored at a time.

- If you find that your $productName$ $version$ installation and your $productName$ 1.14 + If you find that your Emissary $version$ installation and your Emissary 1.14 installation absolutely must have resources that are only seen by one version or the other way, see overview section 2, "If needed, you can use labels to further isolate configurations". **If you find that you need to roll back**, just reinstall your 1.14 CRDs and delete your - installation of $productName$ $version$. + installation of Emissary $version$. -6. **When ready, switch over to $productName$ $version$.** +6. **When ready, switch over to Emissary $version$.** - You can run $productName$ 1.14 and $productName$ $version$ side-by-side as long as you care - to. However, taking full advantage of $productName$ 2.X's capabilities **requires** + You can run Emissary 1.14 and Emissary $version$ side-by-side as long as you care + to. However, taking full advantage of Emissary 2.X's capabilities **requires** [updating your configuration to use `getambassador.io/v3alpha1` configuration resources](../../../../convert-to-v3alpha1), - since some useful features in $productName$ $version$ are only available using + since some useful features in Emissary $version$ are only available using `getambassador.io/v3alpha1` resources. - When you're ready to have $productName$ $version$ handle traffic on its own, switch - your original $productName$ 1.14 Service to point to $productName$ $version$. Use + When you're ready to have Emissary $version$ handle traffic on its own, switch + your original Emissary 1.14 Service to point to Emissary $version$. Use `kubectl edit service ambassador` and change the `selectors` to: ``` @@ -282,7 +282,7 @@ Migration is a seven-step process: Repeat using `kubectl edit service ambassador-admin` for the `ambassador-admin` Service. -7. **Finally, install the $productName$ $version$ Ambassador Agent.** +7. **Finally, install the Emissary $version$ Ambassador Agent.** First, scale the 1.14 agent to 0: @@ -300,13 +300,13 @@ Migration is a seven-step process: kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w ``` -Congratulations! At this point, $productName$ $version$ is fully running and it's safe to remove the `ambassador` and `ambassador-agent` Deployments: +Congratulations! At this point, Emissary $version$ is fully running and it's safe to remove the `ambassador` and `ambassador-agent` Deployments: ``` kubectl delete deployment/ambassador deployment/ambassador-agent ``` -Once $productName$ 1.14 is no longer running, you may [convert](../../../../convert-to-v3alpha1) +Once Emissary 1.14 is no longer running, you may [convert](../../../../convert-to-v3alpha1) any remaining `getambassador.io/v2` resources to `getambassador.io/v3alpha1`. You may also want to redirect DNS to the `edge-stack` Service and remove the `ambassador` Service. diff --git a/content/en/docs/2.5/topics/install/upgrade/helm/emissary-2.0/_index.md b/content/en/docs/2.5/topics/install/upgrade/helm/emissary-2.0/_index.md new file mode 100644 index 00000000..a17e8935 --- /dev/null +++ b/content/en/docs/2.5/topics/install/upgrade/helm/emissary-2.0/_index.md @@ -0,0 +1,3 @@ +--- +title: 2.0 +--- diff --git a/content/en/docs/2.5/topics/install/upgrade/helm/emissary-2.0/emissary-2.5.md b/content/en/docs/2.5/topics/install/upgrade/helm/emissary-2.0/emissary-2.5.md index 5d8f7e0d..3bcb295e 100644 --- a/content/en/docs/2.5/topics/install/upgrade/helm/emissary-2.0/emissary-2.5.md +++ b/content/en/docs/2.5/topics/install/upgrade/helm/emissary-2.0/emissary-2.5.md @@ -1,9 +1,9 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.0.5 to $productName$ $version$ (Helm) +--- +title: 2.0.x to latest 2.x +--- - This guide covers migrating from $productName$ 2.0.5 to $productName$ $version$. If + This guide covers migrating from Emissary 2.0.5 to Emissary $version$. If this is not your exact situation, see the migration matrix. @@ -14,15 +14,15 @@ import Alert from '@material-ui/lab/Alert'; upgrade instructions. -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor +Since Emissary's configuration is entirely stored in Kubernetes resources, upgrading between minor versions is straightforward. Migration is a two-step process: 1. **Install new CRDs.** - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster; Helm will not do this for you. This is mandatory during any upgrade of $productName$. + Before installing Emissary $version$ itself, you need to update the CRDs in + your cluster; Helm will not do this for you. This is mandatory during any upgrade of Emissary. ``` kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml @@ -30,9 +30,9 @@ Migration is a two-step process: ``` - $productName$ $version$ includes a Deployment in the `emissary-system` namespace + Emissary $version$ includes a Deployment in the `emissary-system` namespace called emissary-apiext. This is the APIserver extension - that supports converting $productName$ CRDs between getambassador.io/v2 + that supports converting Emissary CRDs between getambassador.io/v2 and getambassador.io/v3alpha1. This Deployment needs to be running at all times. @@ -44,13 +44,13 @@ Migration is a two-step process: - There is a known issue with the 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. + There is a known issue with the emissary-apiext service that impacts all Emissary 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 Emissary/Ambassador Edge Stack 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. -2. **Install $productName$ $version$.** +2. **Install Emissary $version$.** - After installing the new CRDs, use Helm to install $productName$ $version$. Start by + After installing the new CRDs, use Helm to install Emissary $version$. Start by making sure that your `datawire` Helm repo is set correctly: ```bash @@ -59,7 +59,7 @@ Migration is a two-step process: helm repo update ``` - Then, update your $productName$ installation in the `$productNamespace$` namespace. + Then, update your Emissary installation in the `$productNamespace$` namespace. If necessary for your installation (e.g. if you were running with `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. @@ -70,6 +70,6 @@ Migration is a two-step process: ``` - You must use the $productHelmName$ Helm chart for $productName$ 2.X. + You must use the $productHelmName$ Helm chart for Emissary 2.X. Do not use the ambassador Helm chart. diff --git a/content/en/docs/2.5/topics/install/upgrade/helm/emissary-2.4/_index.md b/content/en/docs/2.5/topics/install/upgrade/helm/emissary-2.4/_index.md new file mode 100644 index 00000000..39dfcfd6 --- /dev/null +++ b/content/en/docs/2.5/topics/install/upgrade/helm/emissary-2.4/_index.md @@ -0,0 +1,3 @@ +--- +title: 2.4 +--- diff --git a/content/en/docs/2.5/topics/install/upgrade/helm/emissary-2.4/emissary-2.5.md b/content/en/docs/2.5/topics/install/upgrade/helm/emissary-2.4/emissary-2.5.md index a438f20f..44015a28 100644 --- a/content/en/docs/2.5/topics/install/upgrade/helm/emissary-2.4/emissary-2.5.md +++ b/content/en/docs/2.5/topics/install/upgrade/helm/emissary-2.4/emissary-2.5.md @@ -1,9 +1,9 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.4.X to $productName$ $version$ (Helm) +--- +title: 2.4.x to latest 2.x +--- - This guide covers migrating from $productName$ 2.4 to $productName$ $version$. If + This guide covers migrating from Emissary 2.4 to Emissary $version$. If this is not your exact situation, see the migration matrix. @@ -14,15 +14,15 @@ import Alert from '@material-ui/lab/Alert'; upgrade instructions. -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor +Since Emissary's configuration is entirely stored in Kubernetes resources, upgrading between minor versions is straightforward. Migration is a two-step process: 1. **Install new CRDs.** - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster; Helm will not do this for you. This is mandatory during any upgrade of $productName$. + Before installing Emissary $version$ itself, you need to update the CRDs in + your cluster; Helm will not do this for you. This is mandatory during any upgrade of Emissary. ``` kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml @@ -30,9 +30,9 @@ Migration is a two-step process: ``` - $productName$ $version$ includes a Deployment in the `emissary-system` namespace + Emissary $version$ includes a Deployment in the `emissary-system` namespace called emissary-apiext. This is the APIserver extension - that supports converting $productName$ CRDs between getambassador.io/v2 + that supports converting Emissary CRDs between getambassador.io/v2 and getambassador.io/v3alpha1. This Deployment needs to be running at all times. @@ -44,13 +44,13 @@ Migration is a two-step process: - There is a known issue with the 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. + There is a known issue with the emissary-apiext service that impacts all Emissary 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 Emissary/Ambassador Edge Stack 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. -2. **Install $productName$ $version$.** +2. **Install Emissary $version$.** - After installing the new CRDs, use Helm to install $productName$ $version$. Start by + After installing the new CRDs, use Helm to install Emissary $version$. Start by making sure that your `datawire` Helm repo is set correctly: ```bash @@ -59,7 +59,7 @@ Migration is a two-step process: helm repo update ``` - Then, update your $productName$ installation in the `$productNamespace$` namespace. + Then, update your Emissary installation in the `$productNamespace$` namespace. If necessary for your installation (e.g. if you were running with `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. @@ -70,6 +70,6 @@ Migration is a two-step process: ``` - You must use the $productHelmName$ Helm chart for $productName$ 2.X. + You must use the $productHelmName$ Helm chart for Emissary 2.X. Do not use the ambassador Helm chart. diff --git a/content/en/docs/2.5/topics/install/upgrade/yaml/_index.md b/content/en/docs/2.5/topics/install/upgrade/yaml/_index.md new file mode 100644 index 00000000..07ce4fef --- /dev/null +++ b/content/en/docs/2.5/topics/install/upgrade/yaml/_index.md @@ -0,0 +1,3 @@ +--- +title: YAML +--- diff --git a/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-1.14/_index.md b/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-1.14/_index.md new file mode 100644 index 00000000..a1248d01 --- /dev/null +++ b/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-1.14/_index.md @@ -0,0 +1,3 @@ +--- +title: 1.14 +--- diff --git a/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-1.14/emissary-2.5.md b/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-1.14/emissary-2.5.md index 449d0565..4719e4a5 100644 --- a/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-1.14/emissary-2.5.md +++ b/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-1.14/emissary-2.5.md @@ -1,9 +1,9 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 1.14.X to $productName$ $version$ (YAML) +--- +title: 1.14 to latest 2.x +--- - This guide covers migrating from $productName$ 1.14.X to $productName$ $version$. If + This guide covers migrating from Emissary 1.14.X to Emissary $version$. If this is not your exact situation, see the migration matrix. @@ -14,12 +14,12 @@ import Alert from '@material-ui/lab/Alert'; upgrade instructions. -We're pleased to introduce $productName$ $version$! The 2.X family introduces a number of -changes to allow $productName$ to more gracefully handle larger installations (including +We're pleased to introduce Emissary $version$! The 2.X family introduces a number of +changes to allow Emissary to more gracefully handle larger installations (including multitenant or multiorganizational installations), reduce memory footprint, and improve -performance. In keeping with [SemVer](https://semver.org), $productName$ 2.X introduces +performance. In keeping with [SemVer](https://semver.org), Emissary 2.X introduces some changes that aren't backward-compatible with 1.X. These changes are detailed in -[Major Changes in $productName$ 2.X](../../../../../../about/changes-2.x/). +[Major Changes in Emissary 2.X](../../../../../../about/changes-2.x/). ## Migration Overview @@ -28,35 +28,35 @@ some changes that aren't backward-compatible with 1.X. These changes are detaile cluster! -The recommended strategy for migration is to run $productName$ 1.14 and $productName$ -$version$ side-by-side in the same cluster. This gives $productName$ $version$ -and $productName$ 1.14 access to all the same configuration resources, with some +The recommended strategy for migration is to run Emissary 1.14 and Emissary +$version$ side-by-side in the same cluster. This gives Emissary $version$ +and Emissary 1.14 access to all the same configuration resources, with some important caveats: -1. **$productName$ 1.14 will not see any `getambassador.io/v3alpha1` resources.** +1. **Emissary 1.14 will not see any `getambassador.io/v3alpha1` resources.** This is intentional; it provides a way to apply configuration only to - $productName$ $version$, while not interfering with the operation of your - $productName$ 1.14 installation. + Emissary $version$, while not interfering with the operation of your + Emissary 1.14 installation. 2. **If needed, you can use labels to further isolate configurations.** - If you need to prevent your $productName$ $version$ installation from - seeing a particular bit of $productName$ 1.14 configuration, you can apply + If you need to prevent your Emissary $version$ installation from + seeing a particular bit of Emissary 1.14 configuration, you can apply a Kubernetes label to the configuration resources that should be seen by - your $productName$ $version$ installation, then set its + your Emissary $version$ installation, then set its `AMBASSADOR_LABEL_SELECTOR` environment variable to restrict its 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$ $version$, then set + that should be visible to Emissary $version$, then set `AMBASSADOR_LABEL_SELECTOR=version-two=true` in its Deployment. 3. **Be careful about label selectors on Kubernetes Services!** - If you have services in $productName$ 1.14 that use selectors that will match - Pods from $productName$ $version$, traffic will be erroneously split between - $productName$ 1.14 and $productName$ $version$. The labels used by $productName$ + If you have services in Emissary 1.14 that use selectors that will match + Pods from Emissary $version$, traffic will be erroneously split between + Emissary 1.14 and Emissary $version$. The labels used by Emissary $version$ include: ```yaml @@ -68,20 +68,20 @@ important caveats: profile: main ``` -4. **Be careful to only have one $productName$ Agent running at a time.** +4. **Be careful to only have one Emissary Agent running at a time.** - The $productName$ Agent is responsible for communications between - $productName$ and Ambassador Cloud. If multiple versions of the Agent are + The Emissary Agent is responsible for communications between + Emissary and Ambassador Cloud. If multiple versions of the Agent are running simultaneously, Ambassador Cloud could see conflicting information about your cluster. - The migration YAML used below to install $productName$ $version$ will not + The migration YAML used below to install Emissary $version$ will not install a duplicate agent. If you are building your own YAML, make sure not to include a duplicate agent. -You can also migrate by [installing $productName$ $version$ in a separate cluster](../../../../migrate-to-2-alternate). -This permits absolute certainty that your $productName$ 1.14 configuration will not be -affected by changes meant for $productName$ $version$, and it eliminates concerns about +You can also migrate by [installing Emissary $version$ in a separate cluster](../../../../migrate-to-2-alternate). +This permits absolute certainty that your Emissary 1.14 configuration will not be +affected by changes meant for Emissary $version$, and it eliminates concerns about ACME, but it is more effort. ## Side-by-Side Migration Steps @@ -90,7 +90,7 @@ Migration is a seven-step process: 1. **Make sure that older configuration resources are not present.** - $productName$ 2.X does not support `getambassador.io/v0` or `getambassador.io/v1` + Emissary 2.X does not support `getambassador.io/v0` or `getambassador.io/v1` resources, and Kubernetes will not permit removing support for CRD versions that are still in use for stored resources. To verify that no resources older than `getambassador.io/v2` are active, run @@ -106,10 +106,10 @@ Migration is a seven-step process: 2. **Install new CRDs.** - Before installing $productName$ $version$ itself, you must configure your + Before installing Emissary $version$ itself, you must configure your Kubernetes cluster to support its new `getambassador.io/v3alpha1` configuration resources. Note that `getambassador.io/v2` resources are still supported, but **you - must install support for `getambassador.io/v3alpha1`** to run $productName$ $version$, + must install support for `getambassador.io/v3alpha1`** to run Emissary $version$, even if you intend to continue using only `getambassador.io/v2` resources for some time. @@ -119,9 +119,9 @@ Migration is a seven-step process: ``` - $productName$ $version$ includes a Deployment in the `emissary-system` namespace + Emissary $version$ includes a Deployment in the `emissary-system` namespace called emissary-apiext. This is the APIserver extension - that supports converting $productName$ CRDs between getambassador.io/v2 + that supports converting Emissary CRDs between getambassador.io/v2 and getambassador.io/v3alpha1. This Deployment needs to be running at all times. @@ -133,23 +133,23 @@ Migration is a seven-step process: - There is a known issue with the 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. + There is a known issue with the emissary-apiext service that impacts all Emissary 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 Emissary/Ambassador Edge Stack 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. -3. **Install $productName$ $version$.** +3. **Install Emissary $version$.** - After installing the new CRDs, you need to install $productName$ $version$ itself - **in the same namespace as your existing $productName$ 1.14 installation**. It's important + After installing the new CRDs, you need to install Emissary $version$ itself + **in the same namespace as your existing Emissary 1.14 installation**. It's important to use the same namespace so that the two installations can see the same secrets, etc. We publish two manifests for different namespaces. Use only the one that - matches the namespace into which you installed $productName$ 1.14: + matches the namespace into which you installed Emissary 1.14: - [`emissary-emissaryns.yaml`] for the `emissary` namespace; or - [`emissary-defaultns.yaml`] for the `default` namespace. - If you installed $productName$ 1.14 into some other namespace, you'll need to + If you installed Emissary 1.14 into some other namespace, you'll need to download one of the files and edit it to match your namespace. [`emissary-emissaryns.yaml`]: https://app.getambassador.io/yaml/emissary/$version$/emissary-emissaryns.yaml @@ -166,9 +166,9 @@ Migration is a seven-step process: ``` - $productName$ $version$ includes a Deployment in the $productNamespace$ namespace + Emissary $version$ includes a Deployment in the $productNamespace$ namespace called emissary-apiext. This is the APIserver extension - that supports converting $productName$ CRDs between getambassador.io/v2 + that supports converting Emissary CRDs between getambassador.io/v2 and getambassador.io/v3alpha1. This Deployment needs to be running at all times. @@ -181,9 +181,9 @@ Migration is a seven-step process: 4. **Install `Listener`s and `Host`s as needed.** - An important difference between $productName$ 1.14 and $productName$ $version$ is the + An important difference between Emissary 1.14 and Emissary $version$ is the new **mandatory** `Listener` CRD. Also, when running both installations side by side, - you will need to make sure that a `Host` is present for the new $productName$ $version$ + you will need to make sure that a `Host` is present for the new Emissary $version$ Service. For example: ```bash @@ -224,15 +224,15 @@ Migration is a seven-step process: EOF ``` - This example requires that you know the hostname for the $productName$ Service (`$EMISSARY_HOSTNAME`) + This example requires that you know the hostname for the Emissary Service (`$EMISSARY_HOSTNAME`) and that you have created a TLS Secret for it in `$EMISSARY_TLS_SECRET`. 5. **Test!** - Your $productName$ $version$ installation can support the `getambassador.io/v2` - configuration resources used by $productName$ 1.14, but you may need to make some + Your Emissary $version$ installation can support the `getambassador.io/v2` + configuration resources used by Emissary 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) + [configuring Emissary Communications](../../../../../../howtos/configure-communications) and [updating CRDs to `getambassador.io/v3alpha1`](../../../../convert-to-v3alpha1). @@ -240,24 +240,24 @@ Migration is a seven-step process: with the same name as a getambassador.io/v2 resource or vice versa: only one version can be stored at a time.

- If you find that your $productName$ $version$ installation and your $productName$ 1.14 + If you find that your Emissary $version$ installation and your Emissary 1.14 installation absolutely must have resources that are only seen by one version or the other way, see overview section 2, "If needed, you can use labels to further isolate configurations". **If you find that you need to roll back**, just reinstall your 1.14 CRDs and delete your - installation of $productName$ $version$. + installation of Emissary $version$. -6. **When ready, switch over to $productName$ $version$.** +6. **When ready, switch over to Emissary $version$.** - You can run $productName$ 1.14 and $productName$ $version$ side-by-side as long as you care - to. However, taking full advantage of $productName$ 2.X's capabilities **requires** + You can run Emissary 1.14 and Emissary $version$ side-by-side as long as you care + to. However, taking full advantage of Emissary 2.X's capabilities **requires** [updating your configuration to use `getambassador.io/v3alpha1` configuration resources](../../../../convert-to-v3alpha1), - since some useful features in $productName$ $version$ are only available using + since some useful features in Emissary $version$ are only available using `getambassador.io/v3alpha1` resources. - When you're ready to have $productName$ $version$ handle traffic on its own, switch - your original $productName$ 1.14 Service to point to $productName$ $version$. Use + When you're ready to have Emissary $version$ handle traffic on its own, switch + your original Emissary 1.14 Service to point to Emissary $version$. Use `kubectl edit service ambassador` and change the `selectors` to: ``` @@ -269,7 +269,7 @@ Migration is a seven-step process: Repeat using `kubectl edit service ambassador-admin` for the `ambassador-admin` Service. -7. **Finally, install the $productName$ $version$ Ambassador Agent.** +7. **Finally, install the Emissary $version$ Ambassador Agent.** First, scale the 1.14 agent to 0: @@ -280,12 +280,12 @@ Migration is a seven-step process: Once that's done, install the new Agent into the same namespace as your Emissary deployment. Again, we supply two files for two different namespaces: use only the one that matches the namespace into which you - installed $productName$ 1.14. + installed Emissary 1.14. - [`emissary-emissaryns-agent.yaml`] for the `emissary` namespace; or - [`emissary-defaultns-agent.yaml`] for the `default` namespace. - If you installed $productName$ 1.14 into some other namespace, you'll need to + If you installed Emissary 1.14 into some other namespace, you'll need to download one of the files and edit it to match your namespace. [`emissary-emissaryns-agent.yaml`]: https://app.getambassador.io/yaml/emissary/$version$/emissary-emissaryns-agent.yaml @@ -297,13 +297,13 @@ Migration is a seven-step process: kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-defaultns-agent.yaml ``` -Congratulations! At this point, $productName$ $version$ is fully running and it's safe to remove the `ambassador` and `ambassador-agent` Deployments: +Congratulations! At this point, Emissary $version$ is fully running and it's safe to remove the `ambassador` and `ambassador-agent` Deployments: ``` kubectl delete deployment/ambassador deployment/ambassador-agent ``` -Once $productName$ 1.14 is no longer running, you may [convert](../../../../convert-to-v3alpha1) +Once Emissary 1.14 is no longer running, you may [convert](../../../../convert-to-v3alpha1) any remaining `getambassador.io/v2` resources to `getambassador.io/v3alpha1`. You may also want to redirect DNS to the `edge-stack` Service and remove the `ambassador` Service. diff --git a/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-2.0/_index.md b/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-2.0/_index.md new file mode 100644 index 00000000..a17e8935 --- /dev/null +++ b/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-2.0/_index.md @@ -0,0 +1,3 @@ +--- +title: 2.0 +--- diff --git a/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-2.0/emissary-2.5.md b/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-2.0/emissary-2.5.md index df4663b2..8c0c4ef5 100644 --- a/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-2.0/emissary-2.5.md +++ b/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-2.0/emissary-2.5.md @@ -1,9 +1,9 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.0.5 to $productName$ $version$ (YAML) +--- +title: 2.0 to latest 2.x +--- - This guide covers migrating from $productName$ 2.0.5 to $productName$ $version$. If + This guide covers migrating from Emissary 2.0.5 to Emissary $version$. If this is not your exact situation, see the migration matrix. @@ -14,15 +14,15 @@ import Alert from '@material-ui/lab/Alert'; upgrade instructions. -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor +Since Emissary's configuration is entirely stored in Kubernetes resources, upgrading between minor versions is straightforward. Migration is a two-step process: 1. **Install new CRDs.** - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. + Before installing Emissary $version$ itself, you need to update the CRDs in + your cluster. This is mandatory during any upgrade of Emissary. ``` kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml @@ -30,9 +30,9 @@ Migration is a two-step process: ``` - $productName$ $version$ includes a Deployment in the `emissary-system` namespace + Emissary $version$ includes a Deployment in the `emissary-system` namespace called emissary-apiext. This is the APIserver extension - that supports converting $productName$ CRDs between getambassador.io/v2 + that supports converting Emissary CRDs between getambassador.io/v2 and getambassador.io/v3alpha1. This Deployment needs to be running at all times. @@ -44,17 +44,17 @@ Migration is a two-step process: - There is a known issue with the 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. + There is a known issue with the emissary-apiext service that impacts all Emissary 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 Emissary/Ambassador Edge Stack 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. -2. **Install $productName$ $version$.** +2. **Install Emissary $version$.** - After installing the new CRDs, upgrade $productName$ $version$. + After installing the new CRDs, upgrade Emissary $version$. Our emissary-emissaryns.yaml file - uses the `emissary` namespace, since this is the default for $productName$. + uses the `emissary` namespace, since this is the default for Emissary. 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. diff --git a/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-2.3/_index.md b/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-2.3/_index.md new file mode 100644 index 00000000..e6730521 --- /dev/null +++ b/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-2.3/_index.md @@ -0,0 +1,3 @@ +--- +title: 2.3 +--- diff --git a/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-2.3/emissary-2.5.md b/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-2.3/emissary-2.5.md index 65018b74..1f5abbd7 100644 --- a/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-2.3/emissary-2.5.md +++ b/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-2.3/emissary-2.5.md @@ -1,9 +1,9 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.4.X to $productName$ $version$ (YAML) +--- +title: 2.3 to latest 2.x +--- - This guide covers migrating from $productName$ 2.4 to $productName$ $version$. If + This guide covers migrating from Emissary 2.3 to Emissary $version$. If this is not your exact situation, see the migration matrix. @@ -14,15 +14,15 @@ import Alert from '@material-ui/lab/Alert'; upgrade instructions. -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor +Since Emissary's configuration is entirely stored in Kubernetes resources, upgrading between minor versions is straightforward. Migration is a two-step process: 1. **Install new CRDs.** - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. + Before installing Emissary $version$ itself, you need to update the CRDs in + your cluster. This is mandatory during any upgrade of Emissary. ``` kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml @@ -30,9 +30,9 @@ Migration is a two-step process: ``` - $productName$ $version$ includes a Deployment in the `emissary-system` namespace + Emissary $version$ includes a Deployment in the `emissary-system` namespace called emissary-apiext. This is the APIserver extension - that supports converting $productName$ CRDs between getambassador.io/v2 + that supports converting Emissary CRDs between getambassador.io/v2 and getambassador.io/v3alpha1. This Deployment needs to be running at all times. @@ -44,17 +44,17 @@ Migration is a two-step process: - There is a known issue with the 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. + There is a known issue with the emissary-apiext service that impacts all Emissary 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 Emissary/Ambassador Edge Stack 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. -2. **Install $productName$ $version$.** +2. **Install Emissary $version$.** - After installing the new CRDs, upgrade $productName$ $version$. + After installing the new CRDs, upgrade Emissary $version$. Our emissary-emissaryns.yaml file - uses the `emissary` namespace, since this is the default for $productName$. + uses the `emissary` namespace, since this is the default for Emissary. 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. diff --git a/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-2.4/_index.md b/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-2.4/_index.md new file mode 100644 index 00000000..39dfcfd6 --- /dev/null +++ b/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-2.4/_index.md @@ -0,0 +1,3 @@ +--- +title: 2.4 +--- diff --git a/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-2.4/emissary-2.5.md b/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-2.4/emissary-2.5.md index 65018b74..fef3c7a7 100644 --- a/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-2.4/emissary-2.5.md +++ b/content/en/docs/2.5/topics/install/upgrade/yaml/emissary-2.4/emissary-2.5.md @@ -1,9 +1,9 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.4.X to $productName$ $version$ (YAML) +--- +title: 2.4 to latest 2.x +--- - This guide covers migrating from $productName$ 2.4 to $productName$ $version$. If + This guide covers migrating from Emissary 2.4 to Emissary $version$. If this is not your exact situation, see the migration matrix. @@ -14,15 +14,15 @@ import Alert from '@material-ui/lab/Alert'; upgrade instructions. -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor +Since Emissary's configuration is entirely stored in Kubernetes resources, upgrading between minor versions is straightforward. Migration is a two-step process: 1. **Install new CRDs.** - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. + Before installing Emissary $version$ itself, you need to update the CRDs in + your cluster. This is mandatory during any upgrade of Emissary. ``` kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml @@ -30,9 +30,9 @@ Migration is a two-step process: ``` - $productName$ $version$ includes a Deployment in the `emissary-system` namespace + Emissary $version$ includes a Deployment in the `emissary-system` namespace called emissary-apiext. This is the APIserver extension - that supports converting $productName$ CRDs between getambassador.io/v2 + that supports converting Emissary CRDs between getambassador.io/v2 and getambassador.io/v3alpha1. This Deployment needs to be running at all times. @@ -44,17 +44,17 @@ Migration is a two-step process: - There is a known issue with the 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. + There is a known issue with the emissary-apiext service that impacts all Emissary 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 Emissary/Ambassador Edge Stack 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. -2. **Install $productName$ $version$.** +2. **Install Emissary $version$.** - After installing the new CRDs, upgrade $productName$ $version$. + After installing the new CRDs, upgrade Emissary $version$. Our emissary-emissaryns.yaml file - uses the `emissary` namespace, since this is the default for $productName$. + uses the `emissary` namespace, since this is the default for Emissary. 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. diff --git a/content/en/docs/2.5/topics/install/yaml-install.md b/content/en/docs/2.5/topics/install/yaml-install.md index b28e6265..51c3539c 100644 --- a/content/en/docs/2.5/topics/install/yaml-install.md +++ b/content/en/docs/2.5/topics/install/yaml-install.md @@ -1,36 +1,33 @@ --- - description: In this guide, we'll walk through the process of deploying $productName$ in Kubernetes for ingress routing. +title: YAML +description: In this guide, we'll walk through the process of deploying Emissary in Kubernetes for ingress routing. --- -import Alert from '@material-ui/lab/Alert'; - -# Install manually - - To migrate from $productName$ 1.X to $productName$ 2.X, see the - [$productName$ migration matrix](../migration-matrix/). This guide + To migrate from Emissary 1.X to Emissary 2.X, see the + [Emissary migration matrix](../migration-matrix/). This guide **will not work** for that, due to changes to the configuration - resources used for $productName$ 2.X. + resources used for Emissary 2.X. -In this guide, we'll walk you through installing $productName$ in your Kubernetes cluster. +In this guide, we'll walk you through installing Emissary in your Kubernetes cluster. The manual install process does not allow for as much control over configuration -as the [Helm install method](../helm), so if you need more control over your $productName$ +as the [Helm install method](../helm), so if you need more control over your Emissary installation, it is recommended that you use helm. ## Before you begin -$productName$ is designed to run in Kubernetes for production. The most essential requirements are: +Emissary is designed to run in Kubernetes for production. The most essential requirements are: * Kubernetes 1.11 or later * The `kubectl` command-line tool ## Install with YAML -$productName$ is typically deployed to Kubernetes from the command line. If you don't have Kubernetes, you should use our [Docker](../docker) image to deploy $productName$ locally. +Emissary is typically deployed to Kubernetes from the command line. If you don't have Kubernetes, you should use our [Docker](../docker) image to deploy Emissary locally. 1. In your terminal, run the following command: @@ -42,9 +39,9 @@ $productName$ is typically deployed to Kubernetes from the command line. If you ``` - $productName$ $version$ includes a Deployment in the $productNamespace$ namespace + Emissary $version$ includes a Deployment in the $productNamespace$ namespace called emissary-apiext. This is the APIserver extension - that supports converting $productName$ CRDs between getambassador.io/v2 + that supports converting Emissary CRDs between getambassador.io/v2 and getambassador.io/v3alpha1. This Deployment needs to be running at all times. @@ -56,7 +53,7 @@ $productName$ is typically deployed to Kubernetes from the command line. If you - There is a known issue with the 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. + There is a known issue with the emissary-apiext service that impacts all Emissary 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 Emissary/Ambassador Edge Stack 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. @@ -70,18 +67,18 @@ $productName$ is typically deployed to Kubernetes from the command line. If you 3. Next Steps - $productName$ shold now be successfully installed and running, but in order to get started deploying Services and test routing to them you need to configure a few more resources. + Emissary shold now be successfully installed and running, but in order to get started deploying Services and test routing to them you need to configure a few more resources. - - [The `Listener` Resource](../../running/listener/) is required to configure which ports the $productName$ pods listen on so that they can begin responding to requests. + - [The `Listener` Resource](../../running/listener/) is required to configure which ports the Emissary pods listen on so that they can begin responding to requests. - [The `Mapping` Resouce](../../using/intro-mappings/) is used to configure routing requests to services in your cluster. - [The `Host` Resource](../../running/host-crd/) configures TLS termination for enablin HTTPS communication. - - Explore how $productName$ [configures communication with clients](../../../howtos/configure-communications) + - Explore how Emissary [configures communication with clients](../../../howtos/configure-communications) - We strongly recommend following along with our Quickstart Guide to get started by creating a Listener, deploying a simple service to test with, and setting up a Mapping to route requests from $productName$ to the demo service. + We strongly recommend following along with our Quickstart Guide to get started by creating a Listener, deploying a simple service to test with, and setting up a Mapping to route requests from Emissary to the demo service. ## Upgrading an existing installation See the [migration matrix](../migration-matrix) for instructions about upgrading -$productName$. +Emissary. diff --git a/content/en/docs/2.5/topics/running/_index.md b/content/en/docs/2.5/topics/running/_index.md new file mode 100644 index 00000000..ab4f1421 --- /dev/null +++ b/content/en/docs/2.5/topics/running/_index.md @@ -0,0 +1,19 @@ +--- +title: "Running" +description: "This section of the documentation provides instructions on running Emissary in a production environment" +--- + +This section of the documentation is designed for operators and site reliability engineers who are managing the deployment of Emissary. Learn more below: + +* *Global Configuration:* The [Ambassador module](ambassador) is used to set system-wide configuration. +* *Exposing Emissary to the Internet:* The [`Listener` CRD](listener) defines which ports are exposed, including their protocols and security models. The [`Host` CRD](host-crd) defines how Emissary manages TLS, domains, and such. +* *Load Balancing:* Emissary supports a number of different [load balancing strategies](load-balancer) as well as different ways to configure [service discovery](resolvers) +* [Gzip Compression](gzip) +* *Deploying Emissary:* On [Amazon Web Services](ambassador-with-aws) | [Google Cloud](ambassador-with-gke) | [general security and operational notes](running), including running multiple $productNamePlural$ on a cluster +* *TLS/SSL:* [Simultaneously Routing HTTP and HTTPS](tls/cleartext-redirection#cleartext-routing) | [HTTP -> HTTPS Redirection](tls/cleartext-redirection#http-https-redirection) | [Mutual TLS](tls/mtls) | [TLS origination](tls/origination) +* *Statistics and Monitoring:* [Integrating with Prometheus, DataDog, and other monitoring systems](statistics) +* *Extending Emissary* Emissary can be extended with custom plug-ins that connect via HTTP/gRPC interfaces. [Custom Authentication](services/auth-service) | [The External Auth protocol](services/ext_authz) | [Custom Logging](services/log-service) | [Rate Limiting](services/rate-limit-service) | [Distributed Tracing](services/tracing-service) +* *Troubleshooting:* [Diagnostics](diagnostics) | [Debugging](debugging) +* *Scaling Emissary:* [Scaling Emissary](scaling) +* *Ingress:* Emissary can function as an [Ingress Controller](ingress-controller) +* *Error Response Overrides:* Emissary can override 4xx and 5xx responses with [custom response bodies](custom-error-responses) diff --git a/content/en/docs/2.5/topics/running/ambassador-deployment.md b/content/en/docs/2.5/topics/running/ambassador-deployment.md index fb559d69..9cd1bd3e 100644 --- a/content/en/docs/2.5/topics/running/ambassador-deployment.md +++ b/content/en/docs/2.5/topics/running/ambassador-deployment.md @@ -1,21 +1,23 @@ -# Deployment architecture +--- +title: Deployment architecture +--- -$productName$ can be deployed in a variety of configurations. The specific configuration depends on your data center. +Emissary can be deployed in a variety of configurations. The specific configuration depends on your data center. ## Public cloud -If you're using a public cloud provider such as Amazon, Azure, or Google, $productName$ can be deployed directly to a Kubernetes cluster running in the data center. Traffic is routed to $productName$ via a cloud-managed load balancer such as an Amazon Elastic Load Balancer or Google Cloud Load Balancer. Typically, this load balancer is transparently managed by Kubernetes in the form of the `LoadBalancer` service type. $productName$ then routes traffic to your services running in Kubernetes. +If you're using a public cloud provider such as Amazon, Azure, or Google, Emissary can be deployed directly to a Kubernetes cluster running in the data center. Traffic is routed to Emissary via a cloud-managed load balancer such as an Amazon Elastic Load Balancer or Google Cloud Load Balancer. Typically, this load balancer is transparently managed by Kubernetes in the form of the `LoadBalancer` service type. Emissary then routes traffic to your services running in Kubernetes. ## On-Premise data center -In an on-premise data center, $productName$ is deployed on the Kubernetes cluster. Instead of exposing it via the `LoadBalancer` service type, $productName$ is exposed as a `NodePort`. Traffic is sent to a specific port on any of the nodes in the cluster, which route the traffic to $productName$, which then routes the traffic to your services running in Kubernetes. You'll also need to deploy a separate load balancer to route traffic from your core routers to $productName$. [MetalLB](https://metallb.universe.tf/) is an open-source external load balancer for Kubernetes designed for this problem. Other options are traditional TCP load balancers such as F5 or Citrix Netscaler. +In an on-premise data center, Emissary is deployed on the Kubernetes cluster. Instead of exposing it via the `LoadBalancer` service type, Emissary is exposed as a `NodePort`. Traffic is sent to a specific port on any of the nodes in the cluster, which route the traffic to Emissary, which then routes the traffic to your services running in Kubernetes. You'll also need to deploy a separate load balancer to route traffic from your core routers to Emissary. [MetalLB](https://metallb.universe.tf/) is an open-source external load balancer for Kubernetes designed for this problem. Other options are traditional TCP load balancers such as F5 or Citrix Netscaler. ## Hybrid data center -Many data centers include services that are running outside of Kubernetes on virtual machines. For $productName$ to route to services both inside and outside of Kubernetes, it needs the real-time network location of all services. This problem is known as "[service discovery](https://www.datawire.io/guide/traffic/service-discovery-microservices/)" and $productName$ supports using [Consul](https://www.consul.io). Services in your data center register themselves with Consul, and $productName$ uses Consul-supplied data to dynamically route requests to available services. +Many data centers include services that are running outside of Kubernetes on virtual machines. For Emissary to route to services both inside and outside of Kubernetes, it needs the real-time network location of all services. This problem is known as "[service discovery](https://www.datawire.io/guide/traffic/service-discovery-microservices/)" and Emissary supports using [Consul](https://www.consul.io). Services in your data center register themselves with Consul, and Emissary uses Consul-supplied data to dynamically route requests to available services. ## Hybrid on-premise data center -The diagram below details a common network architecture for a hybrid on-premise data center. Traffic flows from core routers to MetalLB, which routes to $productName$ running in Kubernetes. $productName$ routes traffic to individual services running on both Kubernetes and VMs. Consul tracks the real-time network location of the services, which $productName$ uses to route to the given services. +The diagram below details a common network architecture for a hybrid on-premise data center. Traffic flows from core routers to MetalLB, which routes to Emissary running in Kubernetes. Emissary routes traffic to individual services running on both Kubernetes and VMs. Consul tracks the real-time network location of the services, which Emissary uses to route to the given services. ![Architecture](../../../images/consul-ambassador.png) diff --git a/content/en/docs/2.5/topics/running/ambassador-with-aws.md b/content/en/docs/2.5/topics/running/ambassador-with-aws.md index b321543a..cf058510 100644 --- a/content/en/docs/2.5/topics/running/ambassador-with-aws.md +++ b/content/en/docs/2.5/topics/running/ambassador-with-aws.md @@ -1,16 +1,18 @@ -# $productName$ with AWS +--- +title: AWS +--- -$productName$ is a platform agnostic Kubernetes API gateway. It will run in any distribution of Kubernetes whether it is managed by a cloud provider or on homegrown bare-metal servers. +Emissary is a platform agnostic Kubernetes API gateway. It will run in any distribution of Kubernetes whether it is managed by a cloud provider or on homegrown bare-metal servers. -This document serves as a reference for different configuration options available when running Kubernetes in AWS. See [Installing $productName$](../../install) for the various installation methods available. +This document serves as a reference for different configuration options available when running Kubernetes in AWS. See [Installing Emissary](../../install) for the various installation methods available. ## Recommended configuration -There are lot of configuration options available to you when running $productName$ in AWS. While you should read this entire document to understand what is best for you, the following is the recommended configuration when running $productName$ in AWS: +There are lot of configuration options available to you when running Emissary in AWS. While you should read this entire document to understand what is best for you, the following is the recommended configuration when running Emissary in AWS: -It is recommended to terminate TLS at $productName$ so you can take advantage of all the TLS configuration options available in $productName$ including setting the allowed TLS versions, setting `alpn_protocol` options, enforcing HTTP -> HTTPS redirection, and [automatic certificate management](../host-crd) in the $productName$. +It is recommended to terminate TLS at Emissary so you can take advantage of all the TLS configuration options available in Emissary including setting the allowed TLS versions, setting `alpn_protocol` options, enforcing HTTP -> HTTPS redirection, and [automatic certificate management](../host-crd) in the Emissary. -When terminating TLS at $productName$, you should deploy a L4 [Network Load Balancer (NLB)](#network-load-balancer-nlb) with the proxy protocol enabled to get the best performance out of your load balancer while still preserving the client IP address. +When terminating TLS at Emissary, you should deploy a L4 [Network Load Balancer (NLB)](#network-load-balancer-nlb) with the proxy protocol enabled to get the best performance out of your load balancer while still preserving the client IP address. The following `Service` should be configured to deploy an NLB with cross zone load balancing enabled (see [NLB notes](#network-load-balancer-nlb) for caveat on the cross-zone-load-balancing annotation). You will need to configure the proxy protocol in the NLB manually in the AWS Console. @@ -36,7 +38,7 @@ spec: service: ambassador ``` - After deploying the `Service` above and manually enabling the proxy protocol you will need to deploy the following [Ambassador `Module`](../ambassador) to tell $productName$ to use the proxy protocol and then restart $productName$ for the configuration to take effect. + After deploying the `Service` above and manually enabling the proxy protocol you will need to deploy the following [Ambassador `Module`](../ambassador) to tell Emissary to use the proxy protocol and then restart Emissary for the configuration to take effect. ```yaml apiVersion: getambassador.io/v3alpha1 @@ -49,7 +51,7 @@ spec: use_proxy_proto: true ``` - $productName$ will now expect traffic from the load balancer to be wrapped with the proxy protocol so it can read the client IP address. + Emissary will now expect traffic from the load balancer to be wrapped with the proxy protocol so it can read the client IP address. ## AWS load balancer notes @@ -94,9 +96,9 @@ The NLB is a second generation AWS Elastic Load Balancer. It can be ensure by a * Can perform TLS termination **Notes:** -- The NLB is the most efficient load balancer capable of handling millions of requests per second. It is recommended for streaming connections since it will maintain the connection stream between the client and $productName$. +- The NLB is the most efficient load balancer capable of handling millions of requests per second. It is recommended for streaming connections since it will maintain the connection stream between the client and Emissary. - Most of the [load balancer annotations](#load-balancer-annotations) are respected by the NLB. You will need to manually configure the proxy protocol and take an extra step to enable cross zone load balancing. -- Since it operates at L4 and cannot modify the request, you will need to tell $productName$ if it is terminating TLS or not (see [TLS termination](#tls-termination) notes below). +- Since it operates at L4 and cannot modify the request, you will need to tell Emissary if it is terminating TLS or not (see [TLS termination](#tls-termination) notes below). ### Application Load Balancer (ALB) @@ -112,20 +114,20 @@ The ALB is a second generation AWS Elastic Load Balancer. It cannot be ensured b **Notes:** -- The ALB can perform routing based on the path, headers, host, etc.. Since $productName$ performs this kind of routing in your cluster, unless you are using the same load balancer to route to services outside of Kubernetes, the overhead of provisioning an ALB is often not worth the benefits. -- If you would like to use an ALB, you will need to expose $productName$ with a `type: NodePort` service and manually configure the ALB to forward to the correct ports. +- The ALB can perform routing based on the path, headers, host, etc.. Since Emissary performs this kind of routing in your cluster, unless you are using the same load balancer to route to services outside of Kubernetes, the overhead of provisioning an ALB is often not worth the benefits. +- If you would like to use an ALB, you will need to expose Emissary with a `type: NodePort` service and manually configure the ALB to forward to the correct ports. - None of the [load balancer annotations](#load-balancer-annotations) are respected by the ALB. You will need to manually configure all options. - The ALB will properly set the `X-Forward-Proto` header if terminating TLS. See (see [TLS termination](#tls-termination) notes below). ## Load balancer annotations -Kubernetes on AWS exposes a mechanism to request certain load balancer configurations by annotating the `type: LoadBalancer` `Service`. The most complete set and explanations of these annotations can be found in this [Kubernetes document](https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer). This document will go over the subset that is most relevant when deploying $productName$. +Kubernetes on AWS exposes a mechanism to request certain load balancer configurations by annotating the `type: LoadBalancer` `Service`. The most complete set and explanations of these annotations can be found in this [Kubernetes document](https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer). This document will go over the subset that is most relevant when deploying Emissary. - `service.beta.kubernetes.io/aws-load-balancer-ssl-cert`: Configures the load balancer to use a valid certificate ARN to terminate TLS at the Load Balancer. - Traffic from the client into the load balancer is encrypted but, since TLS is being terminated at the load balancer, traffic from the load balancer to $productName$ will be cleartext. You will need to configure $productName$ differently depending on whether the load balancer is running in L4 or L7 (see [TLS termination](#tls-termination) notes below). + Traffic from the client into the load balancer is encrypted but, since TLS is being terminated at the load balancer, traffic from the load balancer to Emissary will be cleartext. You will need to configure Emissary differently depending on whether the load balancer is running in L4 or L7 (see [TLS termination](#tls-termination) notes below). - `service.beta.kubernetes.io/aws-load-balancer-ssl-ports`: @@ -153,25 +155,25 @@ Kubernetes on AWS exposes a mechanism to request certain load balancer configura The proxy protocol can be used to preserve the client IP address. - If setting this value, you need to make sure $productName$ is configured to use the proxy protocol (see [preserving the client IP address](#preserving-the-client-ip-address) below). + If setting this value, you need to make sure Emissary is configured to use the proxy protocol (see [preserving the client IP address](#preserving-the-client-ip-address) below). **Note:** This annotation will not be recognized if `aws-load-balancer-type: "nlb"` is configured. Proxy protocol must be manually enabled for NLBs. ## TLS termination -TLS termination is an important part of any modern web app. $productName$ exposes a lot of TLS termination configuration options that make it a powerful tool for managing encryption between your clients and microservices. Refer to the [TLS Termination](../tls) documentation for more information on how to configure TLS termination at $productName$. +TLS termination is an important part of any modern web app. Emissary exposes a lot of TLS termination configuration options that make it a powerful tool for managing encryption between your clients and microservices. Refer to the [TLS Termination](../tls) documentation for more information on how to configure TLS termination at Emissary. With AWS, the AWS Certificate Manager (ACM) makes it easy to configure TLS termination at an AWS load balancer using the annotations explained above. -This means that, when running $productName$ in AWS, you have the choice between terminating TLS at the load balancer using a certificate from the ACM or at $productName$ using a certificate stored as a `Secret` in your cluster. +This means that, when running Emissary in AWS, you have the choice between terminating TLS at the load balancer using a certificate from the ACM or at Emissary using a certificate stored as a `Secret` in your cluster. -The following documentation will cover the different options available to you and how to configure $productName$ and the load balancer to get the most of each. +The following documentation will cover the different options available to you and how to configure Emissary and the load balancer to get the most of each. -### TLS termination at $productName$ +### TLS termination at Emissary -Terminating TLS at $productName$ will guarantee you to be able to use all of the TLS termination options that $productName$ exposes including enforcing the minimum TLS version, setting the `alpn_protocols`, and redirecting cleartext to HTTPS. +Terminating TLS at Emissary will guarantee you to be able to use all of the TLS termination options that Emissary exposes including enforcing the minimum TLS version, setting the `alpn_protocols`, and redirecting cleartext to HTTPS. -If terminating TLS at $productName$, you can provision any AWS load balancer that you want with the following (default) port assignments: +If terminating TLS at Emissary, you can provision any AWS load balancer that you want with the following (default) port assignments: ```yaml spec: @@ -184,13 +186,13 @@ spec: targetPort: 8443 ``` -While terminating TLS at $productName$ makes it easier to expose more advanced TLS configuration options, it does have the drawback of not being able to use the ACM to manage certificates. You will have to manage your TLS certificates yourself or use the [automatic certificate management](../host-crd) available in $productName$ to have $productName$ do it for you. +While terminating TLS at Emissary makes it easier to expose more advanced TLS configuration options, it does have the drawback of not being able to use the ACM to manage certificates. You will have to manage your TLS certificates yourself or use the [automatic certificate management](../host-crd) available in Emissary to have Emissary do it for you. ### TLS termination at the load balancer -If you choose to terminate TLS at your Amazon load balancer you will be able to use the ACM to manage TLS certificates. This option does add some complexity to your $productName$ configuration, depending on which load balancer you are using. +If you choose to terminate TLS at your Amazon load balancer you will be able to use the ACM to manage TLS certificates. This option does add some complexity to your Emissary configuration, depending on which load balancer you are using. -Terminating TLS at the load balancer means that $productName$ will be receiving all traffic as un-encrypted cleartext traffic. Since $productName$ expects to be serving both encrypted and cleartext traffic by default, you will need to make the following configuration changes to $productName$ to support this: +Terminating TLS at the load balancer means that Emissary will be receiving all traffic as un-encrypted cleartext traffic. Since Emissary expects to be serving both encrypted and cleartext traffic by default, you will need to make the following configuration changes to Emissary to support this: #### L4 load balancer (default ELB or NLB) @@ -218,11 +220,11 @@ Terminating TLS at the load balancer means that $productName$ will be receiving service: ambassador ``` - Note that the `spec.ports` has been changed so both the HTTP and HTTPS ports forward to the cleartext port 8080 on $productName$. + Note that the `spec.ports` has been changed so both the HTTP and HTTPS ports forward to the cleartext port 8080 on Emissary. * **`Host`:** - The `Host` configures how $productName$ handles encrypted and cleartext traffic. The following `Host` configuration will tell $productName$ to `Route` cleartext traffic that comes in from the load balancer: + The `Host` configures how Emissary handles encrypted and cleartext traffic. The following `Host` configuration will tell Emissary to `Route` cleartext traffic that comes in from the load balancer: ```yaml apiVersion: getambassador.io/v3alpha1 @@ -243,7 +245,7 @@ Terminating TLS at the load balancer means that $productName$ will be receiving **Important:** -Because L4 load balancers do not set `X-Forwarded` headers, $productName$ will not be able to distinguish between traffic that came in to the load balancer as encrypted or cleartext. Because of this, **HTTP -> HTTPS redirection is not possible when terminating TLS at a L4 load balancer**. +Because L4 load balancers do not set `X-Forwarded` headers, Emissary will not be able to distinguish between traffic that came in to the load balancer as encrypted or cleartext. Because of this, **HTTP -> HTTPS redirection is not possible when terminating TLS at a L4 load balancer**. #### L7 load balancer (ELB or ALB) @@ -273,11 +275,11 @@ Because L4 load balancers do not set `X-Forwarded` headers, $productName$ will n service: ambassador ``` - Note that the `spec.ports` has been changed so both the HTTP and HTTPS ports forward to the cleartext port 8080 on $productName$. + Note that the `spec.ports` has been changed so both the HTTP and HTTPS ports forward to the cleartext port 8080 on Emissary. * **`Host`:** - The `Host` configures how $productName$ handles encrypted and cleartext traffic. The following `Host` configuration will tell $productName$ to `Redirect` cleartext traffic that comes in from the load balancer: + The `Host` configures how Emissary handles encrypted and cleartext traffic. The following `Host` configuration will tell Emissary to `Redirect` cleartext traffic that comes in from the load balancer: ```yaml apiVersion: getambassador.io/v3alpha1 @@ -298,7 +300,7 @@ Because L4 load balancers do not set `X-Forwarded` headers, $productName$ will n * **Module:** - Since a L7 load balancer will be able to append to `X-Forwarded` headers, we need to configure $productName$ to trust the value of these headers. The following `Module` will configure $productName$ to trust a single L7 proxy in front of $productName$: + Since a L7 load balancer will be able to append to `X-Forwarded` headers, we need to configure Emissary to trust the value of these headers. The following `Module` will configure Emissary to trust a single L7 proxy in front of Emissary: ```yaml apiVersion: getambassador.io/v3alpha1 @@ -314,11 +316,11 @@ Because L4 load balancers do not set `X-Forwarded` headers, $productName$ will n **Note:** -$productName$ uses the value of `X-Forwarded-Proto` to know if the request originated as encrypted or cleartext. Unlike L4 load balancers, L7 load balancers will set this header so HTTP -> HTTPS redirection is possible when terminating TLS at a L7 load balancer. +Emissary uses the value of `X-Forwarded-Proto` to know if the request originated as encrypted or cleartext. Unlike L4 load balancers, L7 load balancers will set this header so HTTP -> HTTPS redirection is possible when terminating TLS at a L7 load balancer. ## Preserving the client IP address -Many applications will want to know the IP address of the connecting client. In Kubernetes, this IP address is often obscured by the IP address of the `Node` that is forwarding the request to $productName$ so extra configuration must be done if you need to preserve the client IP address. +Many applications will want to know the IP address of the connecting client. In Kubernetes, this IP address is often obscured by the IP address of the `Node` that is forwarding the request to Emissary so extra configuration must be done if you need to preserve the client IP address. In AWS, there are two options for preserving the client IP address. @@ -326,7 +328,7 @@ In AWS, there are two options for preserving the client IP address. A L7 load balancer will populate the `X-Forwarded-For` header with the IP address of the downstream connecting client. If your clients are connecting directly to the load balancer, this will be the IP address of your client. - When using L7 load balancers, you must configure $productName$ to trust the value of `X-Forwarded-For` and not append its own IP address to it by setting `xff_num_trusted_hops` and `use_remote_address: false` in the [Ambassador `Module`](../ambassador): + When using L7 load balancers, you must configure Emissary to trust the value of `X-Forwarded-For` and not append its own IP address to it by setting `xff_num_trusted_hops` and `use_remote_address: false` in the [Ambassador `Module`](../ambassador): ```yaml apiVersion: getambassador.io/v3alpha1 @@ -340,7 +342,7 @@ In AWS, there are two options for preserving the client IP address. use_remote_address: false ``` - After configuring the above `Module`, you will need to restart $productName$ for the changes to take effect. + After configuring the above `Module`, you will need to restart Emissary for the changes to take effect. 2. Use the proxy protocol @@ -348,7 +350,7 @@ In AWS, there are two options for preserving the client IP address. In AWS, you can configure ELBs to use the proxy protocol by setting the `service.beta.kubernetes.io/aws-load-balancer-proxy-protocol: "*"` annotation on the service. You must manually configure this on ALBs and NLBs. - After configuring the load balancer to use the proxy protocol, you need to tell $productName$ to expect it on the request. + After configuring the load balancer to use the proxy protocol, you need to tell Emissary to expect it on the request. ```yaml apiVersion: getambassador.io/v3alpha1 @@ -361,4 +363,4 @@ In AWS, there are two options for preserving the client IP address. use_proxy_proto: true ``` - After configuring the above `Module`, you will need to restart $productName$ for the changes to take effect. + After configuring the above `Module`, you will need to restart Emissary for the changes to take effect. diff --git a/content/en/docs/2.5/topics/running/ambassador-with-gke.md b/content/en/docs/2.5/topics/running/ambassador-with-gke.md index 2b90581d..d13d7e8e 100644 --- a/content/en/docs/2.5/topics/running/ambassador-with-gke.md +++ b/content/en/docs/2.5/topics/running/ambassador-with-gke.md @@ -1,8 +1,10 @@ -# $productName$ with GKE +--- +title: GKE +--- Google offers a [L7 load balancer](https://cloud.google.com/kubernetes-engine/docs/concepts/ingress) to leverage network services such as managed SSL certificates, SSL offloading or the Google content delivery network. -A L7 load balancer in front of $productName$ can be configured by hand or by using the Ingress-GCE resource. Using the +A L7 load balancer in front of Emissary can be configured by hand or by using the Ingress-GCE resource. Using the Ingress resource also allows you to create Google-managed SSL certificates through Kubernetes. With this setup, HTTPS will be terminated at the Google load balancer. The load balancer will be created and configured by @@ -11,25 +13,25 @@ the Ingress-GCE resource. The load balancer consists of a set of [backend services](https://cloud.google.com/load-balancing/docs/backend-service). In this setup, the ingress resource creates two forwarding rules, one for HTTP and one for HTTPS. The HTTPS forwarding rule has the SSL certificates attached. Also, one backend service will be created to point to -a list of instance groups at a static port. This will be the NodePort of the $productName$ service. +a list of instance groups at a static port. This will be the NodePort of the Emissary service. -With this setup, the load balancer terminates HTTPS and then directs the traffic to the $productName$ service -via the `NodePort`. $productName$ is then doing all the routing to the other internal/external services. +With this setup, the load balancer terminates HTTPS and then directs the traffic to the Emissary service +via the `NodePort`. Emissary is then doing all the routing to the other internal/external services. # Overview of steps 1. Install and configure the ingress with the HTTP(S) load balancer -2. Install $productName$ -3. Configure and connect $productName$ to ingress +2. Install Emissary +3. Configure and connect Emissary to ingress 4. Create an SSL certificate and enable HTTPS 5. Create BackendConfig for health checks -6. Configure $productName$ to do HTTP -> HTTPS redirection +6. Configure Emissary to do HTTP -> HTTPS redirection `ambassador` will be running as a `NodePort` service. Health checks will be configured to go to a BackendConfig resource. -## 0. $productName$ +## 0. Emissary -This guide will install $OSSproductName$. You can also install $AESproductName$. Please note: +This guide will install Emissary. You can also install Ambassador Edge Stack. Please note: - The ingress and the `ambassador` service need to run in the same namespace - The `ambassador` service needs to be of type `NodePort` and not `LoadBalancer`. Also remove the line with `externalTrafficPolicy: Local` - Ambassador-Admin needs to be of type `NodePort` instead of `ClusterIP` since it needs to be available for health checks @@ -41,12 +43,12 @@ is up and running follow [this tutorial from Google](https://cloud.google.com/ku an ingress and a L7 load balancer. After you have completed these steps you will have a running L7 load balancer and one service. -## 2. Install $productName$ +## 2. Install Emissary -Follow the first section of the [$OSSproductName$ installation guide](../../install/) to install $OSSproductName$. +Follow the first section of the [Emissary installation guide](../../install/) to install Emissary. Stop before defining the `ambassador` service. -$productName$ needs to be deployed as `NodePort` instead of `LoadBalancer` to work with the L7 load balancer and the ingress. +Emissary needs to be deployed as `NodePort` instead of `LoadBalancer` to work with the L7 load balancer and the ingress. Save the YAML below in ambassador.yaml and apply with `kubectl apply -f ambassador.yaml` @@ -178,9 +180,9 @@ spec: service: ambassador ``` -## 6. Configure $productName$ to do HTTP -> HTTPS redirection +## 6. Configure Emissary to do HTTP -> HTTPS redirection -Configure $productName$ to [redirect traffic from HTTP to HTTPS](../tls/cleartext-redirection/#http-https-redirection). You will need to restart $productName$ to effect the changes with `kubectl rollout restart deployment ambassador`. +Configure Emissary to [redirect traffic from HTTP to HTTPS](../tls/cleartext-redirection/#http-https-redirection). You will need to restart Emissary to effect the changes with `kubectl rollout restart deployment ambassador`. The result should be that `http://www.example.com` will redirect to `https://www.example.com`. diff --git a/content/en/docs/2.5/topics/running/ambassador.md b/content/en/docs/2.5/topics/running/ambassador.md index 3af41d93..d12a84e1 100644 --- a/content/en/docs/2.5/topics/running/ambassador.md +++ b/content/en/docs/2.5/topics/running/ambassador.md @@ -1,6 +1,6 @@ -import Alert from '@material-ui/lab/Alert'; - -# The `Ambassador` `Module` Resource +--- +title: Ambassador Module +---

Contents

@@ -18,9 +18,9 @@ import Alert from '@material-ui/lab/Alert';
-If present, the `ambassador` `Module` defines system-wide configuration for $productName$. You won't need it unless you need to change one of the system-wide configuration settings below. +If present, the `ambassador` `Module` defines system-wide configuration for Emissary. You won't need it unless you need to change one of the system-wide configuration settings below. -To use the `ambassador` `Module` to configure $productName$, it MUST be named `ambassador`, otherwise it will be ignored. To create multiple `ambassador` `Module`s in the same Kubernetes namespace, you will need to apply them as annotations with separate `ambassador_id`s: you will not be able to use multiple CRDs. +To use the `ambassador` `Module` to configure Emissary, it MUST be named `ambassador`, otherwise it will be ignored. To create multiple `ambassador` `Module`s in the same Kubernetes namespace, you will need to apply them as annotations with separate `ambassador_id`s: you will not be able to use multiple CRDs. There are many items that can be configured on the `ambassador` `Module`. They are listed below with examples and grouped by category. @@ -30,7 +30,7 @@ There are many items that can be configured on the `ambassador` `Module`. They a * `allow_chunked_length: true` tells Envoy to allow requests or responses with both `Content-Length` and `Transfer-Encoding` headers set. The default is `false`. -By default, messages with both `Content-Length` and `Content-Transfer-Encoding` are rejected. If `allow_chunked_length` is `true`, $productName$ will remove the `Content-Length` header and process the message. See the [Envoy documentation for more details](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto.html?highlight=allow_chunked_length#config-core-v3-http1protocoloptions). +By default, messages with both `Content-Length` and `Content-Transfer-Encoding` are rejected. If `allow_chunked_length` is `true`, Emissary will remove the `Content-Length` header and process the message. See the [Envoy documentation for more details](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto.html?highlight=allow_chunked_length#config-core-v3-http1protocoloptions). ##### Envoy access logs @@ -70,7 +70,7 @@ would allow 30 seconds to validate the generated Envoy configuration. * `error_response_overrides` permits changing the status code and body text for 4XX and 5XX response codes. The default is not to override any error responses. -By default, $productName$ will pass through error responses without modification, and errors generated locally will use Envoy's default response body, if any. +By default, Emissary will pass through error responses without modification, and errors generated locally will use Envoy's default response body, if any. See [using error response overrides](../custom-error-responses) for usage details. For example, this configuration: @@ -92,7 +92,7 @@ Two attributes allow providing information about the client's TLS certificate to * `set_current_client_cert_details` will tell Envoy what information to include in the `X-Forwarded-Client-Cert` header. The default is not to include the `X-Forwarded-Client-Cert` header at all. -$productName$ will not forward information about a certificate that it cannot validate. +Emissary will not forward information about a certificate that it cannot validate. See the Envoy documentation on [X-Forwarded-Client-Cert](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers.html?highlight=xfcc#x-forwarded-client-cert) and [SetCurrentClientCertDetails](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto.html#extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-setcurrentclientcertdetails) for more information. @@ -107,7 +107,7 @@ set_current_client_cert_details: SANITIZE ##### Suppress Envoy headers -* `suppress_envoy_headers: true` will prevent $productName$ from emitting certain additional +* `suppress_envoy_headers: true` will prevent Emissary from emitting certain additional headers to HTTP requests and responses. The default is `false`. For the exact set of headers covered by this config, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter#config-http-filters-router-headers-set) @@ -117,9 +117,9 @@ For the exact set of headers covered by this config, see the [Envoy documentatio ##### Ambassador ID -* `ambassador_id` allows using multiple instances of $productName$ in the same cluster. The default is unset. +* `ambassador_id` allows using multiple instances of Emissary in the same cluster. The default is unset. -We recommend _not_ setting `ambassador_id` if you are running only one instance of $productName$ in your cluster. For more information, see the [Running and Deployment documentation](../running/#ambassador_id). +We recommend _not_ setting `ambassador_id` if you are running only one instance of Emissary in your cluster. For more information, see the [Running and Deployment documentation](../running/#ambassador_id). If used, the `ambassador_id` value must be an array, for example: @@ -129,7 +129,7 @@ ambassador_id: [ "test_environment" ] ##### Defaults -* `defaults` provides a dictionary of default values that will be applied to various $productName$ resources. The default is to have no defaults configured. +* `defaults` provides a dictionary of default values that will be applied to various Emissary resources. The default is to have no defaults configured. See [Using `ambassador` `Module` Defaults](../../using/defaults) for more information. @@ -144,9 +144,9 @@ See [Using `ambassador` `Module` Defaults](../../using/defaults) for more inform gRPC is a binary HTTP/2-based protocol. While this allows high performance, it can be problematic for clients that are unable to speak HTTP/2 (such as JavaScript in many browsers, or legacy clients in difficult-to-update environments). -The gRPC-HTTP/1.1 bridge can translate HTTP/1.1 calls with `Content-Type: application/grpc` into gRPC calls: $productName$ will perform buffering and translation as necessary. For more details on the translation process, see the [Envoy gRPC HTTP/1.1 bridge documentation](https://www.envoyproxy.io/docs/envoy/v1.11.2/configuration/http_filters/grpc_http1_bridge_filter.html). +The gRPC-HTTP/1.1 bridge can translate HTTP/1.1 calls with `Content-Type: application/grpc` into gRPC calls: Emissary will perform buffering and translation as necessary. For more details on the translation process, see the [Envoy gRPC HTTP/1.1 bridge documentation](https://www.envoyproxy.io/docs/envoy/v1.11.2/configuration/http_filters/grpc_http1_bridge_filter.html). -Likewise, gRPC-Web is a JSON and HTTP-based protocol that allows browser-based clients to take advantage of gRPC protocols. The gRPC-Web specification requires a server-side proxy to translate between gRPC-Web requests and gRPC backend services, and $productName$ can fill this role when the gRPC-Web bridge is enabled. For more details on the translation process, see the [Envoy gRPC HTTP/1.1 bridge documentation](https://www.envoyproxy.io/docs/envoy/v1.11.2/configuration/http_filters/grpc_http1_bridge_filter.html); for more details on gRPC-Web itself, see the [gRPC-Web client GitHub repo](https://github.com/grpc/grpc-web). +Likewise, gRPC-Web is a JSON and HTTP-based protocol that allows browser-based clients to take advantage of gRPC protocols. The gRPC-Web specification requires a server-side proxy to translate between gRPC-Web requests and gRPC backend services, and Emissary can fill this role when the gRPC-Web bridge is enabled. For more details on the translation process, see the [Envoy gRPC HTTP/1.1 bridge documentation](https://www.envoyproxy.io/docs/envoy/v1.11.2/configuration/http_filters/grpc_http1_bridge_filter.html); for more details on gRPC-Web itself, see the [gRPC-Web client GitHub repo](https://github.com/grpc/grpc-web). ##### Statistics @@ -221,13 +221,13 @@ header_case_overrides: - X-EXPERIMENTAL ``` -If the upstream service responds with `x-my-header: 1`, $productName$ will return `X-MY-Header: 1` to the client. Similarly, if the client includes `x-ExperiMENTAL: yes` in its request, the request to the upstream service will include `X-EXPERIMENTAL: yes`. Other headers will not be altered; $productName$ will use its default lowercase header. +If the upstream service responds with `x-my-header: 1`, Emissary will return `X-MY-Header: 1` to the client. Similarly, if the client includes `x-ExperiMENTAL: yes` in its request, the request to the upstream service will include `X-EXPERIMENTAL: yes`. Other headers will not be altered; Emissary will use its default lowercase header. Please see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto.html#config-core-v3-http1protocoloptions-headerkeyformat) for more information. Note that in general, we recommend updating clients and services rather than relying on `header_case_overrides`. ##### Linkerd interoperability -* `add_linkerd_headers: true` will force $productName$ to include the `l5d-dst-override` header for Linkerd. The default is `false`. +* `add_linkerd_headers: true` will force Emissary to include the `l5d-dst-override` header for Linkerd. The default is `false`. When using older Linkerd installations, requests going to an upstream service may need to include the `l5d-dst-override` header to ensure that Linkerd will route them correctly. Setting `add_linkerd_headers` does this automatically. See the [Mapping](../../using/mappings#linkerd-interoperability-add_linkerd_headers) documentation for more details. @@ -243,9 +243,9 @@ See [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/ext ##### Strip matching host port -* `strip_matching_host_port: true` will tell $productName$ to strip any port number from the host/authority header before processing and routing the request if that port number matches the port number of Envoy's listener. The default is `false`, which will preserve any port number. +* `strip_matching_host_port: true` will tell Emissary to strip any port number from the host/authority header before processing and routing the request if that port number matches the port number of Envoy's listener. The default is `false`, which will preserve any port number. -In the default installation of $productName$ the public port is 443, which then maps internally to 8443, so this only works in custom installations where the public Service port and Envoy listener port match. +In the default installation of Emissary the public port is 443, which then maps internally to 8443, so this only works in custom installations where the public Service port and Envoy listener port match. A common reason to try using this property is if you are using gRPC with TLS and your client library appends the port to the Host header (i.e. `myurl.com:443`). We have an alternative solution in our [gRPC guide](../../../howtos/grpc#working-with-host-headers-that-include-the-port) that uses a [Lua script](#lua-scripts) to remove all ports from every Host header for that use case. @@ -256,7 +256,7 @@ A common reason to try using this property is if you are using gRPC with TLS and ##### Envoy's admin port -* `admin_port` specifies the port where $productName$'s Envoy will listen for low-level admin requests. The default is 8001; it should almost never need changing. +* `admin_port` specifies the port where Emissary's Envoy will listen for low-level admin requests. The default is 8001; it should almost never need changing. ##### Lua scripts @@ -277,29 +277,29 @@ Some caveats around the embedded scripts: * They run in-process, so any bugs in your Lua script can break every request. * They're run on every request/response to every URL. -* They're inlined in the $productName$ YAML; as such, we do not recommend using Lua scripts for long, complex logic. +* They're inlined in the Emissary YAML; as such, we do not recommend using Lua scripts for long, complex logic. -If you need more flexible and configurable options, $AESproductName$ supports a [pluggable Filter system](/docs/edge-stack/latest/topics/using/filters/). +If you need more flexible and configurable options, Ambassador Edge Stack supports a [pluggable Filter system](/docs/edge-stack/latest/topics/using/filters/). ##### Merge slashes -* `merge_slashes: true` will cause $productName$ to merge adjacent slashes in incoming paths when doing route matching and request filtering. The default is `false`. +* `merge_slashes: true` will cause Emissary to merge adjacent slashes in incoming paths when doing route matching and request filtering. The default is `false`. For example, with `merge_slashes: true`, a request for `//foo///bar` would be matched to a `Mapping` with prefix `/foo/bar`. ##### Modify Default Buffer Size -By default, the Envoy that ships with $productName$ uses a defailt of 1MiB soft limit for an upstream service's read and write buffer limits. This setting allows you to configure that buffer limit. See the [Envoy docs](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto.html?highlight=per_connection_buffer_limit_bytes) for more information. +By default, the Envoy that ships with Emissary uses a defailt of 1MiB soft limit for an upstream service's read and write buffer limits. This setting allows you to configure that buffer limit. See the [Envoy docs](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto.html?highlight=per_connection_buffer_limit_bytes) for more information. ```yaml buffer_limit_bytes: 5242880 # Sets the default buffer limit to 5 MiB ``` -##### Use $productName$ namespace for service resolution +##### Use Emissary namespace for service resolution -* `use_ambassador_namespace_for_service_resolution: true` tells $productName$ to assume that unqualified services are in the same namespace as $productName$. The default is `false`. +* `use_ambassador_namespace_for_service_resolution: true` tells Emissary to assume that unqualified services are in the same namespace as Emissary. The default is `false`. -By default, when $productName$ sees a service name without a namespace, it assumes that the namespace is the same as the resource referring to the service. For example, for this `Mapping`: +By default, when Emissary sees a service name without a namespace, it assumes that the namespace is the same as the resource referring to the service. For example, for this `Mapping`: ```yaml apiVersion: getambassador.io/v3alpha1 @@ -313,9 +313,9 @@ spec: service: upstream ``` -$productName$ would look for a Service named `upstream` in namespace `foo`. +Emissary would look for a Service named `upstream` in namespace `foo`. -However, if `use_ambassador_namespace_for_service_resolution` is `true`, this `Mapping` would look for a Service named `foo` in the namespace in which $productName$ is installed instead. +However, if `use_ambassador_namespace_for_service_resolution` is `true`, this `Mapping` would look for a Service named `foo` in the namespace in which Emissary is installed instead. --- @@ -325,7 +325,7 @@ However, if `use_ambassador_namespace_for_service_resolution` is `true`, this `M * `diagnostics` controls access to the diagnostics interface. -By default, $productName$ creates a `Mapping` that allows access to the diagnostic interface at `/ambassador/v0/diag` from anywhere in the cluster. To disable the `Mapping` entirely, set `diagnostics.enabled` to `false`: +By default, Emissary creates a `Mapping` that allows access to the diagnostic interface at `/ambassador/v0/diag` from anywhere in the cluster. To disable the `Mapping` entirely, set `diagnostics.enabled` to `false`: ```yaml @@ -333,7 +333,7 @@ diagnostics: enabled: false ``` -With diagnostics disabled, `/ambassador/v0/diag` will respond with 404; however, the service itself is still running, and `/ambassador/v0/diag/` is reachable from inside the $productName$ Pod at `https://localhost:8877`. You can use Kubernetes port forwarding to set up remote access to the diagnostics page temporarily: +With diagnostics disabled, `/ambassador/v0/diag` will respond with 404; however, the service itself is still running, and `/ambassador/v0/diag/` is reachable from inside the Emissary Pod at `https://localhost:8877`. You can use Kubernetes port forwarding to set up remote access to the diagnostics page temporarily: ``` kubectl port-forward -n ambassador deploy/ambassador 8877 @@ -356,9 +356,9 @@ See [Protecting Access to the Diagnostics Interface](../../../howtos/protecting- * `enable_ipv4` determines whether IPv4 DNS lookups are enabled. The default is `true`. * `enable_ipv6` determines whether IPv6 DNS lookups are enabled. The default is `false`. -If both IPv4 and IPv6 are enabled, $productName$ will prefer IPv6. This can have strange effects if $productName$ receives `AAAA` records from a DNS lookup, but the underlying network of the pod doesn't actually support IPv6 traffic. For this reason, the default is IPv4 only. +If both IPv4 and IPv6 are enabled, Emissary will prefer IPv6. This can have strange effects if Emissary receives `AAAA` records from a DNS lookup, but the underlying network of the pod doesn't actually support IPv6 traffic. For this reason, the default is IPv4 only. -An [`Mapping`](../../using/mappings) can override both `enable_ipv4` and `enable_ipv6`, but if either is not stated explicitly in a `Mapping`, the values here are used. Most $productName$ installations will probably be able to avoid overriding these settings in Mappings. +An [`Mapping`](../../using/mappings) can override both `enable_ipv4` and `enable_ipv6`, but if either is not stated explicitly in a `Mapping`, the values here are used. Most Emissary installations will probably be able to avoid overriding these settings in Mappings. ##### HTTP/1.0 support @@ -398,25 +398,25 @@ ip_allow: - remote: 99.99.0.0/16 ``` -The keyword `peer` specifies that the match should happen using the IP address of the other end of the network connection carrying the request: `X-Forwarded-For` and the `PROXY` protocol are both ignored. Here, our example specifies that connections originating from the $productName$ pod itself should always be allowed. +The keyword `peer` specifies that the match should happen using the IP address of the other end of the network connection carrying the request: `X-Forwarded-For` and the `PROXY` protocol are both ignored. Here, our example specifies that connections originating from the Emissary pod itself should always be allowed. -The keyword `remote` specifies that the match should happen using the IP address of the HTTP client, taking into account `X-Forwarded-For` and the `PROXY` protocol if they are allowed (if they are not allowed, or not present, the peer address will be used instead). This permits matches to behave correctly when, for example, $productName$ is behind a layer 7 load balancer. Here, our example specifies that HTTP clients from the IP address range `99.99.0.0` - `99.99.255.255` will be allowed. +The keyword `remote` specifies that the match should happen using the IP address of the HTTP client, taking into account `X-Forwarded-For` and the `PROXY` protocol if they are allowed (if they are not allowed, or not present, the peer address will be used instead). This permits matches to behave correctly when, for example, Emissary is behind a layer 7 load balancer. Here, our example specifies that HTTP clients from the IP address range `99.99.0.0` - `99.99.255.255` will be allowed. You may specify as many ranges for each kind of keyword as desired. ##### Rejecting Client Requests With Escaped Slashes -* `reject_requests_with_escaped_slashes: true` will tell $productName$ to reject requests containing escaped slashes. The default is `false`. +* `reject_requests_with_escaped_slashes: true` will tell Emissary to reject requests containing escaped slashes. The default is `false`. -When set to `true`, $productName$ will reject any client requests that contain escaped slashes (`%2F`, `%2f`, `%5C`, or `%5c`) in their URI path by returning HTTP 400. By default, $productName$ will forward these requests unmodified. +When set to `true`, Emissary will reject any client requests that contain escaped slashes (`%2F`, `%2f`, `%5C`, or `%5c`) in their URI path by returning HTTP 400. By default, Emissary will forward these requests unmodified. In general, a request with an escaped slash will _not_ match a `Mapping` prefix with an unescaped slash. However, external authentication services and other upstream services may handle escaped slashes differently, which can lead to security issues if paths with escaped slashes are allowed. By setting `reject_requests_with_escaped_slashes: true`, this class of security concern can be largely avoided. ##### Trust downstream client IP -* `use_remote_address: false` tells $productName$ that it cannot trust the remote address of incoming connections, and must instead rely exclusively on the `X-Forwarded-For` header. The default is `true`. +* `use_remote_address: false` tells Emissary that it cannot trust the remote address of incoming connections, and must instead rely exclusively on the `X-Forwarded-For` header. The default is `true`. -When `true` (the default), $productName$ will append its own IP address to the `X-Forwarded-For` header so that upstream services of $productName$ can get the full set of IP addresses that have propagated a request. You may also need to set `externalTrafficPolicy: Local` on your `LoadBalancer` to propagate the original source IP address. +When `true` (the default), Emissary will append its own IP address to the `X-Forwarded-For` header so that upstream services of Emissary can get the full set of IP addresses that have propagated a request. You may also need to set `externalTrafficPolicy: Local` on your `LoadBalancer` to propagate the original source IP address. See the [Envoy documentation on the `X-Forwarded-For header` ](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers) and the [Kubernetes documentation on preserving the client source IP](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/#preserving-the-client-source-ip) for more details. @@ -434,7 +434,7 @@ See the [`Listener` documentation](../listener/#securitymodel) for more details. * `listener_idle_timeout_ms` sets the idle timeout for incoming connections. The default is no timeout, meaning that incoming connections may remain idle forever. -If set, this specifies the length of time (in milliseconds) that an incoming connection is allowed to be idle before being dropped. This can useful if you have proxies and/or firewalls in front of $productName$ and need to control how $productName$ initiates closing an idle TCP connection. +If set, this specifies the length of time (in milliseconds) that an incoming connection is allowed to be idle before being dropped. This can useful if you have proxies and/or firewalls in front of Emissary and need to control how Emissary initiates closing an idle TCP connection. Please see the [Envoy documentation on HTTP protocol options](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#config-core-v3-httpprotocoloptions) for more information. @@ -442,7 +442,7 @@ Please see the [Envoy documentation on HTTP protocol options](https://www.envoyp * `keepalive` sets the global TCP keepalive settings. -$productName$ will use these settings for all `AmbasasdorMapping`s unless overridden in a `Mapping`'s configuration. Without `keepalive`, $productName$ follows the operating system defaults. +Emissary will use these settings for all `AmbasasdorMapping`s unless overridden in a `Mapping`'s configuration. Without `keepalive`, Emissary follows the operating system defaults. For example, the following configuration: @@ -490,7 +490,7 @@ You can override this setting with [`timeout_ms` on a `Mapping`](../../using/tim * `readiness_probe` sets whether `/ambassador/v0/check_ready` is automatically mapped * `liveness_probe` sets whether `/ambassador/v0/check_alive` is automatically mapped -By default, $productName$ creates `Mapping`s that support readiness and liveness checks at `/ambassador/v0/check_ready` and `/ambassador/v0/check_alive`. To disable the readiness `Mapping` entirely, set `readiness_probe.enabled` to `false`: +By default, Emissary creates `Mapping`s that support readiness and liveness checks at `/ambassador/v0/check_ready` and `/ambassador/v0/check_alive`. To disable the readiness `Mapping` entirely, set `readiness_probe.enabled` to `false`: ```yaml @@ -506,7 +506,7 @@ liveness_probe: enabled: false ``` -A disabled probe endpoint will respond with 404; however, the service is still running, and will be accessible on localhost port 8877 from inside the $productName$ Pod. +A disabled probe endpoint will respond with 404; however, the service is still running, and will be accessible on localhost port 8877 from inside the Emissary Pod. You can change these to route requests to some other service. For example, to have the readiness probe map to the `quote` application's health check: @@ -536,7 +536,7 @@ retry_policy: * `circuit_breakers` sets the global circuit breaking configuration defaults -You can override the circuit breaker settings for individual `Mapping`s. By default, $productName$ does not configure any circuit breakers. For more information, see the [circuit breaking reference](../../using/circuit-breakers). +You can override the circuit breaker settings for individual `Mapping`s. By default, Emissary does not configure any circuit breakers. For more information, see the [circuit breaking reference](../../using/circuit-breakers). ##### Default label domain and labels diff --git a/content/en/docs/2.5/topics/running/custom-error-responses.md b/content/en/docs/2.5/topics/running/custom-error-responses.md index b0ad9877..690c4482 100644 --- a/content/en/docs/2.5/topics/running/custom-error-responses.md +++ b/content/en/docs/2.5/topics/running/custom-error-responses.md @@ -1,11 +1,11 @@ -import Alert from '@material-ui/lab/Alert'; - -# Custom error responses +--- +title: Custom error responses +--- Custom error responses set overrides for HTTP response statuses generated either -by $productName$ or upstream services. +by Emissary or upstream services. -They can be configured either on the $productName$ +They can be configured either on the Emissary [`Module`](../ambassador) or on an [`Mapping`](../../using/intro-mappings/), the schema is identical. See below for more information on [rule precedence](#rule-precedence). @@ -22,8 +22,8 @@ below for more information on [rule precedence](#rule-precedence). serialized as JSON and used as the new response body. + `text_format_source`: Describes a file to be used as the response. If used, `filename` must be set and the file must exist - on the $productName$ pod. - * `filename`: A file path on the $productName$ pod that will be used + on the Emissary pod. + * `filename`: A file path on the Emissary pod that will be used as the new response body. Only one of `text_format`, `json_format`, or `text_format_source` may be provided. @@ -52,7 +52,7 @@ for a request that resulted in a response code of 401. 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. + substitution nor an escape, Emissary will ignore the custom error response. ## Simple response bodies @@ -83,10 +83,10 @@ spec: For more complex response bodies a file can be returned as the response. This could be used for a customer friendly HTML document for example. Use -`text_format_source` with a `filename` set as a path on the $productName$ pod. +`text_format_source` with a `filename` set as a path on the Emissary pod. `content_type` should be used set the specific file type, such as `text/html`. -First configure the $productName$ module: +First configure the Emissary module: ```yaml apiVersion: getambassador.io/v3alpha1 @@ -122,7 +122,7 @@ data: ``` -Finally, mount the configmap to the $productName$ pod: +Finally, mount the configmap to the Emissary 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. diff --git a/content/en/docs/2.5/topics/running/debugging.md b/content/en/docs/2.5/topics/running/debugging.md index bd376483..ab832de9 100644 --- a/content/en/docs/2.5/topics/running/debugging.md +++ b/content/en/docs/2.5/topics/running/debugging.md @@ -1,22 +1,24 @@ -# Debugging +--- +title: 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. +If you’re experiencing issues with the Emissary and cannot diagnose the issue through the `/ambassador/v0/diag/` diagnostics endpoint, this document covers various approaches and advanced use cases for debugging Emissary issues. -We assume that you already have a running $productName$ installation in the following sections. +We assume that you already have a running Emissary 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 +having trouble with TLS, always [check the logs] of your Emissary Pods and look for certificate errors. [TLS]: ../tls [certificates]: ../tls#certificates-and-secrets [check the logs]: #review-logs -## Check $productName$ status +## Check Emissary status -1. First, check the $productName$ Deployment with the following: `kubectl get -n $productNamespace$ deployments` +1. First, check the Emissary Deployment with the following: `kubectl get -n $productNamespace$ deployments` After a brief period, the terminal will print something similar to the following: @@ -81,30 +83,30 @@ In both the Deployment Pod and the individual Pods, take the necessary action to ## 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. +Emissary 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 Emissary 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. +Emissary has two major log mechanisms: Emissary logging and Envoy logging. Both appear in the normal `kubectl logs` output, and both can have additional debug-level logging enabled. Enabling debug-level logging can produce a lot of log output — enough to - potentially impact the performance of $productName$. We don't recommend running with debug + potentially impact the performance of Emissary. We don't recommend running with debug logging enabled as a matter of course; it's usually better to enable it only when needed, then reset logging to normal once you're finished debugging. -### $productName$ debug logging +### Emissary debug logging -Much of $productName$'s logging is concerned with the business of noticing changes to -Kubernetes resources that specify the $productName$ configuration, and generating new +Much of Emissary's logging is concerned with the business of noticing changes to +Kubernetes resources that specify the Emissary configuration, and generating new Envoy configuration in response to those changes. Enabling debug logging for this part of the system is under the control of two environment variables: -- Set `AES_LOG_LEVEL=debug` to debug the early boot sequence and $productName$'s interactions +- Set `AES_LOG_LEVEL=debug` to debug the early boot sequence and Emissary's interactions with the Kubernetes cluster (finding changed resources, etc.). - Set `AMBASSADOR_DEBUG=diagd` to debug the process of generating an Envoy configuration from the input resources. -### $productName$ Envoy logging +### Emissary Envoy logging Envoy logging is concerned with the actions Envoy is taking for incoming requests. Typically, Envoy will only output access logs, and certain errors, but enabling Envoy @@ -114,7 +116,7 @@ an error status is coming from Envoy or from the upstream service. It is possible to enable Envoy logging at boot, but for the most part, it's safer to enable it at runtime, right before sending a request that is known to have problems. -To enable Envoy debug logging, use `kubectl exec` to get a shell on the $productName$ +To enable Envoy debug logging, use `kubectl exec` to get a shell on the Emissary pod, then: ``` @@ -127,9 +129,9 @@ This will turn on Envoy debug logging for ten seconds, then turn it off again. ### Viewing logs -To view the logs from $productName$: +To view the logs from Emissary: -1. Use the following command to target an individual $productName$ Pod: `kubectl get pods -n $productNamespace$` +1. Use the following command to target an individual Emissary Pod: `kubectl get pods -n $productNamespace$` The terminal will print something similar to the following: @@ -163,21 +165,21 @@ Note that many deployments will have multiple logs, and the logs are independent ## Examine Pod and container contents -You can examine the contents of the $productName$ Pod for issues, such as if volume mounts are correct and TLS certificates are present in the required directory, to determine if the Pod has the latest $productName$ configuration, or if the generated Envoy configuration is correct or as expected. In these instructions, we will look for problems related to the Envoy configuration. +You can examine the contents of the Emissary Pod for issues, such as if volume mounts are correct and TLS certificates are present in the required directory, to determine if the Pod has the latest Emissary configuration, or if the generated Envoy configuration is correct or as expected. In these instructions, we will look for problems related to the Envoy configuration. -1. To look into an $productName$ Pod, get a shell on the Pod using `kubectl exec`. For example, +1. To look into an Emissary Pod, get a shell on the Pod using `kubectl exec`. For example, ``` kubectl exec -it -n $productNamespace$ <$productDeploymentName$-pod-name> -- bash ``` -2. Determine the latest configuration. If you haven't overridden the configuration directory, the latest configuration will be in `/ambassador/snapshots`. If you have overridden it, $productName$ saves configurations in `$AMBASSADOR_CONFIG_BASE_DIR/snapshots`. +2. Determine the latest configuration. If you haven't overridden the configuration directory, the latest configuration will be in `/ambassador/snapshots`. If you have overridden it, Emissary saves configurations in `$AMBASSADOR_CONFIG_BASE_DIR/snapshots`. In the snapshots directory: - * `snapshot.yaml` contains the full input configuration that $productName$ has found; - * `aconf.json` contains the $productName$ configuration extracted from the snapshot; - * `ir.json` contains the IR constructed from the $productName$ configuration; and + * `snapshot.yaml` contains the full input configuration that Emissary has found; + * `aconf.json` contains the Emissary configuration extracted from the snapshot; + * `ir.json` contains the IR constructed from the Emissary configuration; and * `econf.json` contains the Envoy configuration generated from the IR. In the snapshots directory, the current configuration will be stored in files with no digit suffix, and older configurations have increasing numbers. For example, `ir.json` is current, `ir-1.json` is the next oldest, then `ir-2.json`, etc. diff --git a/content/en/docs/2.5/topics/running/diagnostics.md b/content/en/docs/2.5/topics/running/diagnostics.md index 1e10f9a0..26b2eac5 100644 --- a/content/en/docs/2.5/topics/running/diagnostics.md +++ b/content/en/docs/2.5/topics/running/diagnostics.md @@ -1,19 +1,21 @@ -# Diagnostics +--- +title: Diagnostics +--- -If you're experiencing issues with $productName$, log in to your Edge Policy Console and choose from the left menu whether you want to: +If you're experiencing issues with Emissary, log in to your Edge Policy Console and choose from the left menu whether you want to: * Debug issues from the Debugging tab * Check the health status of your services from the Mappings tab ## Debugging -If $productName$ is not routing your services as you'd expect, your first step should be $productName$ Diagnostics in the Edge Policy Console. Login to your Edge Policy Console and select the "Debugging" tab from the left menu. +If Emissary is not routing your services as you'd expect, your first step should be Emissary Diagnostics in the Edge Policy Console. Login to your Edge Policy Console and select the "Debugging" tab from the left menu. -Some of the most important information (your $productName$ version, how recently $productName$'s configuration was updated, and how recently Envoy last reported status to $productName$) is right at the top. See [Debugging](../debugging) for more information. +Some of the most important information (your Emissary version, how recently Emissary's configuration was updated, and how recently Envoy last reported status to Emissary) is right at the top. See [Debugging](../debugging) for more information. ## Health status -$productName$ displays the health of your services on the Dashboard of your Edge Policy Console. Health is computed as successful requests / total requests and expressed as a percentage. The "total requests" comes from Envoy `upstream_rq_pending_total` stat. "Successful requests" is calculated by substracting `upstream_rq_4xx` and `upstream_rq_5xx` from the total. +Emissary displays the health of your services on the Dashboard of your Edge Policy Console. Health is computed as successful requests / total requests and expressed as a percentage. The "total requests" comes from Envoy `upstream_rq_pending_total` stat. "Successful requests" is calculated by substracting `upstream_rq_4xx` and `upstream_rq_5xx` from the total. * Red is used when the success rate ranges from 0% - 70%. * Yellow is used when the success rate ranges from 70% - 90%. @@ -31,11 +33,11 @@ The RIGHT image shows the dial on the hompage of the Edge Policy Console, this w If the diagnostics service does not provide sufficient information, Kubernetes and Envoy provide additional debugging information. -If $productName$ isn't working at all, start by looking at the data from the following: +If Emissary isn't working at all, start by looking at the data from the following: -* `kubectl describe pod ` will give you a list of all events on the $productName$ pod -* `kubectl logs ambassador` will give you a log from $productName$ itself +* `kubectl describe pod ` will give you a list of all events on the Emissary pod +* `kubectl logs ambassador` will give you a log from Emissary itself If you need additional help, feel free to join our [Slack channel](http://a8r.io/slack) with the above information (along with your Kubernetes manifest). -You can also increase the debug of Envoy through the button in the diagnostics panel. Turn on debug logging, issue a request, and capture the log output from the $productName$ pod using `kubectl logs` as described above. +You can also increase the debug of Envoy through the button in the diagnostics panel. Turn on debug logging, issue a request, and capture the log output from the Emissary pod using `kubectl logs` as described above. diff --git a/content/en/docs/2.5/topics/running/environment.md b/content/en/docs/2.5/topics/running/environment.md index 849c28fc..9afd1ca3 100644 --- a/content/en/docs/2.5/topics/running/environment.md +++ b/content/en/docs/2.5/topics/running/environment.md @@ -1,6 +1,8 @@ -# $productName$ Environment variables +--- +title: Environment Variables +--- -Use the following variables for the environment of your $productName$ container: +Use the following variables for the environment of your Emissary container: | Variable | Default value | Value type | |----------------------------------------------------------------------------------------------------------- |-----------------------------------------------------|-------------------------------------------------------------------------------| @@ -52,7 +54,7 @@ Use the following variables for the environment of your $productName$ container: ### `AMBASSADOR_ID` -$productName$ supports running multiple installs in the same cluster without restricting a given instance of $productName$ to a single namespace. +Emissary supports running multiple installs in the same cluster without restricting a given instance of Emissary 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) @@ -86,16 +88,16 @@ Set it to 0 to disable. ### `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 +Each Emissary installation generates a unique cluster ID based on the UID of its Kubernetes namespace and its Emissary ID: the resulting cluster ID is a UUID which cannot be used +to reveal the namespace name nor Emissary ID itself. Emissary 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 Emissary 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`. +Controls where Emissary will store snapshots. By default, the latest configuration will be in `/ambassador/snapshots`. If you have overridden it, Emissary saves configurations in `$AMBASSADOR_CONFIG_BASE_DIR/snapshots`. [More information](../../running/debugging#examine-pod-and-container-contents) @@ -107,18 +109,18 @@ To completely disable feature reporting, set the environment variable `AMBASSADO ### `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 +At each reconfiguration, Emissary 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 Emissary provides active clients when reconfiguration happens. +Its unit is seconds and it defaults to 600 (10 minutes). This can impact memory usage because Emissary 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 may switch back to Envoy V2 by setting the `AMBASSADOR_ENVOY_API_VERSION` environment variable to "V2". -Using the V2 API is not recommended since $productName$ 3.0 removes support for the V2 API. +By default, Emissary will configure Envoy using the [V3 Envoy API](https://www.envoyproxy.io/docs/envoy/latest/api-v3/api). +In Emissary 2.0, you may switch back to Envoy V2 by setting the `AMBASSADOR_ENVOY_API_VERSION` environment variable to "V2". +Using the V2 API is not recommended since Emissary 3.0 removes support for the V2 API. ### `AMBASSADOR_GRPC_METRICS_SINK` @@ -128,7 +130,7 @@ Agent which has no negative effect on general routing or Edgissary uptime. ### `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` +Emissary 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) @@ -142,8 +144,8 @@ Some (but few) logs from `gunicorn` and the Kubernetes `client-go` package will ### `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. +Restricts Emissary'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 Emissary, then set `AMBASSADOR_LABEL_SELECTOR=version-two=true` in its Deployment. Resources without the specified label will be ignored. ### `AMBASSADOR_NAMESPACE` @@ -159,58 +161,58 @@ in seconds and must be > 0. ### `AMBASSADOR_SINGLE_NAMESPACE` -When set, configures $productName$ to only work within a single namespace. +When set, configures Emissary to only work within a single namespace. [More information](../../running/running#namespaces) ### `AMBASSADOR_SNAPSHOT_COUNT` -The number of snapshots that $productName$ should save. +The number of snapshots that Emissary 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 +By default, Emissary 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 +Emissary 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 +If you are a user of the [Datadog](https://docs.datadoghq.com/) monitoring system, pulling in the Envoy statistics from Emissary is very easy. +Because the DogStatsD protocol is slightly different than the normal StatsD protocol, in addition to setting Emissary'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 +Emissary integrates Scout, a service that periodically checks with Datawire servers to advise of available updates. Scout also sends anonymized usage +data and the Emissary version. This information is important to us as we prioritize test coverage, bug fixes, and feature development. Note that the Emissary 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. +the environment variable `SCOUT_DISABLE` to `1` in your Emissary 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 +If enabled, then Emissary 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 Emissary'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 +When this variable is set, Emissary 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 Emissary 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) @@ -229,7 +231,7 @@ How often, in seconds, to submit statsd reports (if `STATSD_ENABLED`) ### `_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` +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 Emissary `Deployment` [More information](../../../howtos/consul#environment-variables) @@ -283,8 +285,8 @@ 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 +If `AMBASSADOR_UPDATE_MAPPING_STATUS` is set to the string `true`, Emissary will update the `status` of every `Mapping` +CRD that it accepts for its configuration. This has no effect on the proper functioning of Emissary 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. @@ -298,7 +300,7 @@ This controls the number of worker threads used to serve requests and can be use ## Port assignments -$productName$ uses the following ports to listen for HTTP/HTTPS traffic automatically via TCP: +Emissary uses the following ports to listen for HTTP/HTTPS traffic automatically via TCP: | Port | Process | Function | |------|----------|---------------------------------------------------------| @@ -306,7 +308,7 @@ $productName$ uses the following ports to listen for HTTP/HTTPS traffic automati | 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 | +| 8005 | snapshot | Exposes a scrubbed Emissary 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` | diff --git a/content/en/docs/2.5/topics/running/gzip.md b/content/en/docs/2.5/topics/running/gzip.md index e3005c83..11f2968c 100644 --- a/content/en/docs/2.5/topics/running/gzip.md +++ b/content/en/docs/2.5/topics/running/gzip.md @@ -1,6 +1,8 @@ -# Gzip compression +--- +title: 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. +Gzip enables Emissary 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? diff --git a/content/en/docs/2.5/topics/running/host-crd.md b/content/en/docs/2.5/topics/running/host-crd.md index db561ee1..5b94ca5c 100644 --- a/content/en/docs/2.5/topics/running/host-crd.md +++ b/content/en/docs/2.5/topics/running/host-crd.md @@ -1,24 +1,24 @@ -import Alert from '@material-ui/lab/Alert'; - -# The **Host** CRD +--- +title: Host CRD +--- -The custom `Host` resource defines how $productName$ will be +The custom `Host` resource defines how Emissary 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 +* The hostname by which Emissary will be reachable +* How Emissary should handle TLS certificates +* How Emissary should handle secure and insecure requests * Which `Mappings` should be associated with this `Host` Remember that Listener resources are required for a functioning - $productName$ installation!
+ Emissary installation!
Learn more about Listener. - Remember than $productName$ does not make sure that a wildcard Host exists! If the + Remember than Emissary does not make sure that a wildcard Host exists! If the wildcard behavior is needed, a Host with a hostname of "*" must be defined by the user. @@ -34,18 +34,18 @@ spec: hostname: host.example.com ``` -This `Host` tells $productName$ to expect to be reached at `host.example.com`, +This `Host` tells Emissary to expect to be reached at `host.example.com`, with no TLS termination, and only associating with `Mapping`s that also set a `hostname` that matches `host.example.com`. Remember that a 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) +in the [Configuring Emissary Communications](../../../howtos/configure-communications) document. ## Setting the `hostname` -The `hostname` element tells $productName$ which hostnames to expect. `hostname` is a DNS glob, +The `hostname` element tells Emissary which hostnames to expect. `hostname` is a DNS glob, so all of the following are valid: - `host.example.com` @@ -167,7 +167,7 @@ spec: # and if the Host specifies mappingSelector AND t service: http://httpbin.org ``` -Future versions of $productName$ will support `matchExpressions` as well. +Future versions of Emissary will support `matchExpressions` as well. ## Secure and insecure requests @@ -197,11 +197,11 @@ 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. +* Ambassador Edge Stack provides native handling of ACME challenges. If you are using this support, Ambassador Edge Stack will automatically arrange for insecure ACME challenges to be handled correctly. If you are handling ACME yourself - as you must when running Emissary - 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 +The `Host` is responsible for high-level TLS configuration in Emissary. There are several settings covering TLS: ### `tlsSecret` enables TLS termination @@ -209,7 +209,7 @@ several settings covering TLS: `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 +The following `Host` will configure Emissary to read a `Secret` named `tls-cert` for a certificate to use when terminating TLS. ```yaml @@ -241,21 +241,21 @@ 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$ +In a typical installation, Emissary runs behind a load balancer. The +configuration of the load balancer can affect how Emissary sees requests +arriving from the outside world, which can in turn can affect whether Emissary 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. +- **Emissary 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. + - 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 Emissary (in the typical case, where the client speaks to the load balancer, which then speaks to Emissary, 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. +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 Emissary is behind only layer 4 load balancers; it should need to be changed **only** when layer 7 load balancers are involved. ### CRD specification diff --git a/content/en/docs/2.5/topics/running/index.md b/content/en/docs/2.5/topics/running/index.md deleted file mode 100644 index c196e969..00000000 --- a/content/en/docs/2.5/topics/running/index.md +++ /dev/null @@ -1,16 +0,0 @@ -# Running $productName$ in production - -This section of the documentation is designed for operators and site reliability engineers who are managing the deployment of $productName$. Learn more below: - -* *Global Configuration:* The [Ambassador module](ambassador) is used to set system-wide configuration. -* *Exposing $productName$ to the Internet:* The [`Listener` CRD](listener) defines which ports are exposed, including their protocols and security models. The [`Host` CRD](host-crd) defines how $productName$ manages TLS, domains, and such. -* *Load Balancing:* $productName$ supports a number of different [load balancing strategies](load-balancer) as well as different ways to configure [service discovery](resolvers) -* [Gzip Compression](gzip) -* *Deploying $productName$:* On [Amazon Web Services](ambassador-with-aws) | [Google Cloud](ambassador-with-gke) | [general security and operational notes](running), including running multiple $productNamePlural$ on a cluster -* *TLS/SSL:* [Simultaneously Routing HTTP and HTTPS](tls/cleartext-redirection#cleartext-routing) | [HTTP -> HTTPS Redirection](tls/cleartext-redirection#http-https-redirection) | [Mutual TLS](tls/mtls) | [TLS origination](tls/origination) -* *Statistics and Monitoring:* [Integrating with Prometheus, DataDog, and other monitoring systems](statistics) -* *Extending $productName$* $productName$ can be extended with custom plug-ins that connect via HTTP/gRPC interfaces. [Custom Authentication](services/auth-service) | [The External Auth protocol](services/ext_authz) | [Custom Logging](services/log-service) | [Rate Limiting](services/rate-limit-service) | [Distributed Tracing](services/tracing-service) -* *Troubleshooting:* [Diagnostics](diagnostics) | [Debugging](debugging) -* *Scaling $productName$:* [Scaling $productName$](scaling) -* *Ingress:* $productName$ can function as an [Ingress Controller](ingress-controller) -* *Error Response Overrides:* $productName$ can override 4xx and 5xx responses with [custom response bodies](custom-error-responses) diff --git a/content/en/docs/2.5/topics/running/ingress-controller.md b/content/en/docs/2.5/topics/running/ingress-controller.md index 9b7afb82..82e17a0b 100644 --- a/content/en/docs/2.5/topics/running/ingress-controller.md +++ b/content/en/docs/2.5/topics/running/ingress-controller.md @@ -1,6 +1,6 @@ -import Alert from '@material-ui/lab/Alert'; - -# Ingress controller +--- +title: Ingress controller +---

Contents

@@ -17,11 +17,11 @@ import Alert from '@material-ui/lab/Alert';
-An Ingress resource is a popular way to expose Kubernetes services to the Internet. In order to use Ingress resources, you need to install an [ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/). $productName$ can function as a fully-fledged Ingress controller, making it easy to work with other Ingress-oriented tools within the Kubernetes ecosystem. +An Ingress resource is a popular way to expose Kubernetes services to the Internet. In order to use Ingress resources, you need to install an [ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/). Emissary can function as a fully-fledged Ingress controller, making it easy to work with other Ingress-oriented tools within the Kubernetes ecosystem. ## When and how to use the Ingress resource -If you're new to $productName$ and to Kubernetes, we'd recommend you start with our [quickstart](../../../tutorials/getting-started/) instead of this Ingress guide. If you're a power user and need to integrate with other software that leverages the Ingress resource, read on. The Ingress specification is very basic and does not support many of the features of $productName$, so you'll be using both the Ingress resource and $productName$'s Mapping resource to manage your Kubernetes services. +If you're new to Emissary and to Kubernetes, we'd recommend you start with our [quickstart](../../../tutorials/getting-started/) instead of this Ingress guide. If you're a power user and need to integrate with other software that leverages the Ingress resource, read on. The Ingress specification is very basic and does not support many of the features of Emissary, so you'll be using both the Ingress resource and Emissary's Mapping resource to manage your Kubernetes services. ### What is required to use the Ingress resource? @@ -42,10 +42,10 @@ If you're new to $productName$ and to Kubernetes, we'd recommend you start with Kubernetes) or the `networking.k8s.io` `apiGroup` (introduced in Kubernetes 1.14). -- $productName$ will need RBAC permissions to get, list, watch, and update Ingress resources. +- Emissary will need RBAC permissions to get, list, watch, and update Ingress resources. You can see this in the [`aes-crds.yaml`](https://app.getambassador.io/yaml/ambassador-docs/latest/aes.yaml) - file, but this is the critical rule to add to $productName$'s `Role` or `ClusterRole`: + file, but this is the critical rule to add to Emissary's `Role` or `ClusterRole`: ```yaml - apiGroups: ['extensions', 'networking.k8s.io'] @@ -57,12 +57,12 @@ If you're new to $productName$ and to Kubernetes, we'd recommend you start with ``` - This is included by default in all $productName$ installations. + This is included by default in all Emissary installations. - You must create your Ingress resource with the correct `ingress.class`. - $productName$ will automatically read Ingress resources with the annotation + Emissary will automatically read Ingress resources with the annotation `kubernetes.io/ingress.class: ambassador`. - You may need to set your Ingress resource's `ambassador-id`. @@ -72,7 +72,7 @@ If you're new to $productName$ and to Kubernetes, we'd recommend you start with - You must create a Service resource with the correct `app.kubernetes.io/component` label. - $productName$ will automatically load balance Ingress resources using the endpoint exposed + Emissary will automatically load balance Ingress resources using the endpoint exposed from the Service with the annotation `app.kubernetes.io/component: ambassador-service`. ```yaml @@ -99,17 +99,17 @@ If you're new to $productName$ and to Kubernetes, we'd recommend you start with ### When to use an Ingress instead of annotations or CRDs -We recommend that $productName$ be configured using CRDs. The Ingress resource is available to users who need it for integration with other ecosystem tools, or who feel that it more closely matches their workflows. However, it is important to recognize that the Ingress resource is rather more limited than the $productName$ Mapping is (for example, the Ingress spec has no support for rewriting or for TLS origination). **When in doubt, use CRDs.** +We recommend that Emissary be configured using CRDs. The Ingress resource is available to users who need it for integration with other ecosystem tools, or who feel that it more closely matches their workflows. However, it is important to recognize that the Ingress resource is rather more limited than the Emissary Mapping is (for example, the Ingress spec has no support for rewriting or for TLS origination). **When in doubt, use CRDs.** ## Ingress support -$productName$ supports basic core functionality of the Ingress resource, as defined by the [Ingress resource](https://kubernetes.io/docs/concepts/services-networking/ingress/) itself: +Emissary supports basic core functionality of the Ingress resource, as defined by the [Ingress resource](https://kubernetes.io/docs/concepts/services-networking/ingress/) itself: -- Basic routing is supported, including the `route` specification and the default backend functionality. It's particularly easy to use a minimal Ingress to the $productName$ diagnostic UI. +- Basic routing is supported, including the `route` specification and the default backend functionality. It's particularly easy to use a minimal Ingress to the Emissary diagnostic UI. - [TLS termination](../tls/) is supported. You can use multiple Ingress resources for SNI. -- Using the Ingress resource in concert with $productName$ CRDs or annotations is supported. This includes $productName$ annotations on the Ingress resource itself. +- Using the Ingress resource in concert with Emissary CRDs or annotations is supported. This includes Emissary annotations on the Ingress resource itself. -$productName$ does **not** extend the basic Ingress specification with the following exceptions: +Emissary does **not** extend the basic Ingress specification with the following exceptions: - The `getambassador.io/ambassador-id` annotation allows you to set [the Ambassador ID](../running/#ambassador_id) for the Ingress itself. @@ -121,7 +121,7 @@ Note that if you need to set `getambassador.io/ambassador-id` on the Ingress, yo ### Ingress routes and Mappings -$productName$ actually creates Mapping objects from the Ingress route rules. These Mapping objects interact with Mappings defined in CRDs **exactly** as they would if the Ingress route rules had been specified with CRDs originally. +Emissary actually creates Mapping objects from the Ingress route rules. These Mapping objects interact with Mappings defined in CRDs **exactly** as they would if the Ingress route rules had been specified with CRDs originally. For example, this Ingress resource routes traffic to `/foo/` to `service1`: @@ -157,7 +157,7 @@ spec: service: service1:80 ``` -This YAML will set up $productName$ to do canary routing where 50% of the traffic will go to `service1` and 50% will go to `service2`. +This YAML will set up Emissary to do canary routing where 50% of the traffic will go to `service1` and 50% will go to `service2`. ```yaml --- diff --git a/content/en/docs/2.5/topics/running/listener.md b/content/en/docs/2.5/topics/running/listener.md index 152e1b74..b79a4a7a 100644 --- a/content/en/docs/2.5/topics/running/listener.md +++ b/content/en/docs/2.5/topics/running/listener.md @@ -1,9 +1,11 @@ -# The `Listener` CRD +--- +title: Listener CRD +--- -The `Listener` CRD defines where, and how, $productName$ should listen for requests from the network, and which `Host` definitions should be used to process those requests. For further examples of how to use `Listener`, see [Configuring $productName$ Communications](../../../howtos/configure-communications). +The `Listener` CRD defines where, and how, Emissary should listen for requests from the network, and which `Host` definitions should be used to process those requests. For further examples of how to use `Listener`, see [Configuring Emissary Communications](../../../howtos/configure-communications). -**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 +**Note that `Listener`s are never created by Emissary, and must be defined by the user.** If you do not +define any `Listener`s, Emissary will not listen anywhere for connections, and therefore won't do anything useful. It will log a `WARNING` to this effect. ```yaml @@ -26,17 +28,17 @@ spec: | Element | Type | Definition | | :------ | :--- | :--------- | -| `port` | `int32` | The network port on which $productName$ should listen. *Required.* | +| `port` | `int32` | The network port on which Emissary should listen. *Required.* | | `protocol` | `enum`; see below | A high-level protocol type, like "HTTPS". *Exactly one of `protocol` and `protocolStack` must be supplied.* | | `protocolStack` | array of `enum`; see below | A sequence of low-level protocols to layer together. *Exactly one of `protocol` and `protocolStack` must be supplied.* | -| `securityModel` | `enum`; see below | How does $productName$ decide whether requests here are secure? *Required.* | +| `securityModel` | `enum`; see below | How does Emissary decide whether requests here are secure? *Required.* | | `statsPrefix` | `string`; see below | Under what name do statistics for this `Listener` appear? *Optional; default depends on protocol.* | -| `l7Depth` | `int32` | How many layer 7 load balancers are between the edge of the network and $productName$? *Optional; default is 0.*| +| `l7Depth` | `int32` | How many layer 7 load balancers are between the edge of the network and Emissary? *Optional; default is 0.*| | `hostBinding` | `struct`, see below | Mechanism for determining which `Host`s will be associated with this `Listener`. *Required* | ### `protocol` and `protocolStack` -`protocol` is the **recommended** way to tell $productName$ that a `Listener` expects connections using a well-known protocol. When using `protocol`, `protocolStack` may not also be supplied. +`protocol` is the **recommended** way to tell Emissary that a `Listener` expects connections using a well-known protocol. When using `protocol`, `protocolStack` may not also be supplied. Valid `protocol` values are: @@ -60,44 +62,44 @@ Valid `protocol` values are: | `INSECURE` | Requests are always insecure. You might set this for an HTTP-only `Listener`, or a `Listener` for clients that are expected to be hostile. | The `X-Forwarded-Proto` header mentioned above is meant to reflect the protocol the _original client_ -used to contact $productName$. When no layer 7 proxies are in use, Envoy will make certain that the +used to contact Emissary. When no layer 7 proxies are in use, Envoy will make certain that the `X-Forwarded-Proto` header matches the wire protocol of the connection the client made to Envoy, -which allows $productName$ to trust `X-Forwarded-Proto` for routing decisions such as deciding to -redirect requests made using HTTP over to HTTPS for greater security. When using $productName$ as an +which allows Emissary to trust `X-Forwarded-Proto` for routing decisions such as deciding to +redirect requests made using HTTP over to HTTPS for greater security. When using Emissary as an edge proxy or a typical API gateway, this is a desirable configuration; setting `securityModel` to `XFP` makes this easy. When layer proxies _are_ in use, the `XFP` setting is often still desirable; however, you will also need to set `l7Depth` to allow it to function. See below. -`SECURE` and `INSECURE` are helpful for cases where something downstream of $productName$ should be -allowing only one kind of request to reach $productName$. For example, a `Listener` behind a load +`SECURE` and `INSECURE` are helpful for cases where something downstream of Emissary should be +allowing only one kind of request to reach Emissary. For example, a `Listener` behind a load balancer that terminates TLS and checks client certificates might use `SecurityModel: SECURE`, then use `Host`s to reject insecure requests if one somehow arrives. ### `l7Depth` -When layer 7 (L7) proxies are in use, the connection to $productName$ comes from the L7 proxy itself +When layer 7 (L7) proxies are in use, the connection to Emissary comes from the L7 proxy itself rather than from the client. Examining the protocol and IP address of that connection is useless, and -instead you need to configure the L7 proxy to pass extra information about the client to $productName$ +instead you need to configure the L7 proxy to pass extra information about the client to Emissary using the `X-Forwarded-Proto` and `X-Forwarded-For` headers. -However, if $productName$ always trusted `X-Forwarded-Proto` and `X-Forwarded-For`, any client could -use them to lie about itself to $productName$. As a security mechanism, therefore, you must _also_ -set `l7Depth` in the `Listener` to the number of trusted L7 proxies in front of $productName$. If +However, if Emissary always trusted `X-Forwarded-Proto` and `X-Forwarded-For`, any client could +use them to lie about itself to Emissary. As a security mechanism, therefore, you must _also_ +set `l7Depth` in the `Listener` to the number of trusted L7 proxies in front of Emissary. If `l7Depth` is not set in the `Listener`, the `xff_num_trusted_hops` value from the `ambassador` `Module` will be used. If neither is set, the default `l7Depth` is 0. When `l7Depth` is 0, any incoming `X-Forwarded-Proto` is stripped: Envoy always provides an `X-Forwarded-Proto` matching the wire protocol of the incoming connection, so that `X-Forwarded-Proto` can be trusted. When `l7Depth` is non-zero, `X-Forwarded-Proto` is accepted from the L7 proxy, and -trusted. The actual wire protocol in use from the L7 proxy to $productName$ is ignored. +trusted. The actual wire protocol in use from the L7 proxy to Emissary is ignored. -`l7Depth` also affects $productName$'s view of the client's source IP address, which is used as the +`l7Depth` also affects Emissary's view of the client's source IP address, which is used as the `remote_address` field when rate limiting, and for the `X-Envoy-External-Address` header: -- When `l7Depth` is 0, $productName$ uses the IP address of the incoming connection. +- When `l7Depth` is 0, Emissary uses the IP address of the incoming connection. - When `l7Depth` is some value N that is non-zero, the behavior is determined by the value of `use_remote_address` in the `ambassador` `Module`: @@ -126,7 +128,7 @@ trusted. The actual wire protocol in use from the L7 proxy to $productName$ is i ### `statsPrefix` -$productName$ produces detailed [statistics](../statistics) which can be monitored in a variety of ways. Statistics have hierarchical names, and the `Listener` will cause a set of statistics to be logged under the name specified by `statsPrefix`. +Emissary produces detailed [statistics](../statistics) which can be monitored in a variety of ways. Statistics have hierarchical names, and the `Listener` will cause a set of statistics to be logged under the name specified by `statsPrefix`. The default `statsPrefix` depends on the protocol for this `Listener`: @@ -215,4 +217,4 @@ The possible stack elements are: ## Examples -For further examples of how to use `Listener`, see [Configuring $productName$ to Communicate](../../../howtos/configure-communications). +For further examples of how to use `Listener`, see [Configuring Emissary to Communicate](../../../howtos/configure-communications). diff --git a/content/en/docs/2.5/topics/running/load-balancer.md b/content/en/docs/2.5/topics/running/load-balancer.md index 987a910b..07b45d01 100644 --- a/content/en/docs/2.5/topics/running/load-balancer.md +++ b/content/en/docs/2.5/topics/running/load-balancer.md @@ -1,6 +1,8 @@ -# Load balancing +--- +title: Load balancing +--- -Load balancing configuration can be set for all $productName$ mappings in the [`ambassador` `Module`](../ambassador), or set per [`Mapping`](../../using/mappings). If nothing is set, simple round robin balancing is used via Kubernetes services. +Load balancing configuration can be set for all Emissary mappings in the [`ambassador` `Module`](../ambassador), or set per [`Mapping`](../../using/mappings). If nothing is set, simple round robin balancing is used via Kubernetes services. To use advanced load balancing, you must first configure a [resolver](../resolvers) that supports advanced load balancing (e.g., the Kubernetes Endpoint Resolver or Consul Resolver). Once a resolver is configured, you can use the `load_balancer` attribute. The following fields are supported: @@ -19,7 +21,7 @@ Supported load balancer policies: For more information on the different policies and the implications, see [load balancing strategies in Kubernetes](https://blog.getambassador.io/load-balancing-strategies-in-kubernetes-l4-round-robin-l7-round-robin-ring-hash-and-more-6a5b81595d6c). ## Round robin -When `policy` is set to `round_robin`, $productName$ discovers healthy endpoints for the given mapping, and load balances the incoming L7 requests with round robin scheduling. To specify this: +When `policy` is set to `round_robin`, Emissary discovers healthy endpoints for the given mapping, and load balances the incoming L7 requests with round robin scheduling. To specify this: ```yaml apiVersion: getambassador.io/v3alpha1 @@ -54,7 +56,7 @@ Note that load balancing may not appear to be "even" due to Envoy's threading mo ## Least request -When `policy` is set to `least_request`, $productName$ discovers healthy endpoints for the given mapping, and load balances the incoming L7 requests to the endpoint with the fewest active requests. To specify this: +When `policy` is set to `least_request`, Emissary discovers healthy endpoints for the given mapping, and load balances the incoming L7 requests to the endpoint with the fewest active requests. To specify this: ```yaml apiVersion: getambassador.io/v3alpha1 @@ -87,13 +89,13 @@ spec: ## Sticky sessions / session affinity -Configuring sticky sessions makes $productName$ route requests to a specific pod providing your service in a given session. One pod serves all requests from a given session, eliminating the need for session data to be transferred between pods. $productName$ lets you configure session affinity based on the following parameters in an incoming request: +Configuring sticky sessions makes Emissary route requests to a specific pod providing your service in a given session. One pod serves all requests from a given session, eliminating the need for session data to be transferred between pods. Emissary lets you configure session affinity based on the following parameters in an incoming request: - Cookie - Header - Source IP -**NOTE:** $productName$ supports sticky sessions using two load balancing policies, `ring_hash` and `maglev`. +**NOTE:** Emissary supports sticky sessions using two load balancing policies, `ring_hash` and `maglev`. ### Cookie @@ -106,7 +108,7 @@ load_balancer: path: ``` -If the cookie you wish to set affinity on is already present in incoming requests, then you only need the `cookie.name` field. However, if you want $productName$ to generate and set a cookie in response to the first request, then you need to specify a value for the `cookie.ttl` field which generates a cookie with the given expiration time. +If the cookie you wish to set affinity on is already present in incoming requests, then you only need the `cookie.name` field. However, if you want Emissary to generate and set a cookie in response to the first request, then you need to specify a value for the `cookie.ttl` field which generates a cookie with the given expiration time. ```yaml apiVersion: getambassador.io/v3alpha1 @@ -133,7 +135,7 @@ load_balancer: header:
``` -$productName$ allows header based session affinity if the given header is present on incoming requests. +Emissary allows header based session affinity if the given header is present on incoming requests. Example: @@ -160,7 +162,7 @@ load_balancer: source_ip: ``` -$productName$ allows session affinity based on the source IP of incoming requests. +Emissary allows session affinity based on the source IP of incoming requests. ```yaml apiVersion: getambassador.io/v3alpha1 diff --git a/content/en/docs/2.5/topics/running/resolvers.md b/content/en/docs/2.5/topics/running/resolvers.md index 1ace9a86..1d725b29 100644 --- a/content/en/docs/2.5/topics/running/resolvers.md +++ b/content/en/docs/2.5/topics/running/resolvers.md @@ -1,10 +1,12 @@ -# Service discovery and resolvers +--- +title: Service discovery and resolvers +--- -Service discovery is how cloud applications and their microservices are located on the network. In a cloud environment, services are ephemeral, existing only as long as they are needed and in use, so a real-time service discovery mechanism is required. $productName$ uses information from service discovery to determine where to route incoming requests. +Service discovery is how cloud applications and their microservices are located on the network. In a cloud environment, services are ephemeral, existing only as long as they are needed and in use, so a real-time service discovery mechanism is required. Emissary uses information from service discovery to determine where to route incoming requests. -## $productName$ support for service discovery +## Emissary support for service discovery -$productName$ supports different mechanisms for service discovery. These mechanisms are: +Emissary supports different mechanisms for service discovery. These mechanisms are: * Kubernetes service-level discovery (default). * Kubernetes endpoint-level discovery. @@ -12,23 +14,23 @@ $productName$ supports different mechanisms for service discovery. These mechani ### Kubernetes service-level discovery -By default, $productName$ uses Kubernetes DNS and service-level discovery. In a `Mapping` resource, specifying `service: foo` will prompt $productName$ to look up the DNS address of the `foo` Kubernetes service. Traffic will be routed to the `foo` service. Kubernetes will then load balance that traffic between multiple pods. For more details on Kubernetes networking and how this works, see our blog post on [Session affinity, load balancing controls, gRPC-Web, and $productName$](https://blog.getambassador.io/session-affinity-load-balancing-controls-grpc-web-and-ambassador-0-52-2b916b396d0c). +By default, Emissary uses Kubernetes DNS and service-level discovery. In a `Mapping` resource, specifying `service: foo` will prompt Emissary to look up the DNS address of the `foo` Kubernetes service. Traffic will be routed to the `foo` service. Kubernetes will then load balance that traffic between multiple pods. For more details on Kubernetes networking and how this works, see our blog post on [Session affinity, load balancing controls, gRPC-Web, and Emissary](https://blog.getambassador.io/session-affinity-load-balancing-controls-grpc-web-and-ambassador-0-52-2b916b396d0c). ### Kubernetes endpoint-level discovery -$productName$ can also watch Kubernetes endpoints. This bypasses the Kubernetes service routing layer and enables the use of advanced load balancing controls such as session affinity and maglev. For more details, see the [load balancing reference](../load-balancer). +Emissary can also watch Kubernetes endpoints. This bypasses the Kubernetes service routing layer and enables the use of advanced load balancing controls such as session affinity and maglev. For more details, see the [load balancing reference](../load-balancer). ### Consul endpoint-level discovery -$productName$ natively integrates with [Consul](https://www.consul.io) for endpoint-level service discovery. In this mode, $productName$ obtains endpoint information from Consul. One of the primary use cases for this architecture is in hybrid cloud environments that run a mixture of Kubernetes services as well as VMs, as Consul can serve as the single global registry for all services. +Emissary natively integrates with [Consul](https://www.consul.io) for endpoint-level service discovery. In this mode, Emissary obtains endpoint information from Consul. One of the primary use cases for this architecture is in hybrid cloud environments that run a mixture of Kubernetes services as well as VMs, as Consul can serve as the single global registry for all services. ## The Resolver resource -The `Resolver` resource is used to configure the discovery service strategy for $productName$. +The `Resolver` resource is used to configure the discovery service strategy for Emissary. ### The Kubernetes service resolver -The Kubernetes Service Resolver configures $productName$ to use Kubernetes services. If no resolver is specified, this behavior is the default. When this resolver is used, the `service.namespace` value from a `Mapping` is handed to the Kubernetes cluster's DNS resolver to determine where requests are sent. +The Kubernetes Service Resolver configures Emissary to use Kubernetes services. If no resolver is specified, this behavior is the default. When this resolver is used, the `service.namespace` value from a `Mapping` is handed to the Kubernetes cluster's DNS resolver to determine where requests are sent. ```yaml --- @@ -40,7 +42,7 @@ metadata: ### The Kubernetes endpoint resolver -The Kubernetes Endpoint Resolver configures $productName$ to resolve Kubernetes endpoints. This enables the use of more a [advanced load balancing configuration](../load-balancer). When this resolver is used, the endpoints for the `service` defined in a `Mapping` are resolved and used to determine where requests are sent. +The Kubernetes Endpoint Resolver configures Emissary to resolve Kubernetes endpoints. This enables the use of more a [advanced load balancing configuration](../load-balancer). When this resolver is used, the endpoints for the `service` defined in a `Mapping` are resolved and used to determine where requests are sent. ```yaml --- @@ -52,7 +54,7 @@ metadata: ### The Consul resolver -The Consul Resolver configures $productName$ to use Consul for service discovery. When this resolver is used, the `service` defined in a `Mapping` is passed to Consul, along with the datacenter specified, to determine where requests are sent. +The Consul Resolver configures Emissary to use Consul for service discovery. When this resolver is used, the `service` defined in a `Mapping` is passed to Consul, along with the datacenter specified, to determine where requests are sent. ```yaml --- @@ -125,4 +127,4 @@ spec: policy: round_robin ``` -The YAML configuration above will configure $productName$ to use Kubernetes Service Discovery to route to the Consul Service Discovery to route to the `bar` service on requests with `prefix: /bar/`. +The YAML configuration above will configure Emissary to use Kubernetes Service Discovery to route to the Consul Service Discovery to route to the `bar` service on requests with `prefix: /bar/`. diff --git a/content/en/docs/2.5/topics/running/running.md b/content/en/docs/2.5/topics/running/running.md index 8cc5ca8a..43b837cf 100644 --- a/content/en/docs/2.5/topics/running/running.md +++ b/content/en/docs/2.5/topics/running/running.md @@ -1,20 +1,20 @@ # Running and deployment -This section is intended for operators running $productName$, and covers various aspects of deploying and configuring the $productName$ in production. +This section is intended for operators running Emissary, and covers various aspects of deploying and configuring the Emissary in production. -## $productName$ and Kubernetes +## Emissary and Kubernetes -$productName$ relies on Kubernetes for reliability, availability, and scalability. This means that features such as Kubernetes readiness and liveness probes, rolling updates, and the Horizontal Pod Autoscaling should be utilized to manage $productName$. +Emissary relies on Kubernetes for reliability, availability, and scalability. This means that features such as Kubernetes readiness and liveness probes, rolling updates, and the Horizontal Pod Autoscaling should be utilized to manage Emissary. ## Default configuration -The default configuration of $productName$ includes default [resource limits](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-requests-and-limits-of-pod-and-container), as well as [readiness and liveness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/). These values should be adjusted for your specific environment. +The default configuration of Emissary includes default [resource limits](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-requests-and-limits-of-pod-and-container), as well as [readiness and liveness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/). These values should be adjusted for your specific environment. ## Running as non-root -Starting with $productName$ 0.35, we support running $productName$ as non-root. This is the recommended configuration, and will be the default configuration in future releases. We recommend you configure $productName$ to run as non-root as follows: +Starting with Emissary 0.35, we support running Emissary as non-root. This is the recommended configuration, and will be the default configuration in future releases. We recommend you configure Emissary to run as non-root as follows: -* Have Kubernetes run $productName$ as non-root. This may happen by default (e.g., OpenShift) or you can set a `securityContext` in your Deployment as shown below in this abbreviated example: +* Have Kubernetes run Emissary as non-root. This may happen by default (e.g., OpenShift) or you can set a `securityContext` in your Deployment as shown below in this abbreviated example: ```yaml --- @@ -41,15 +41,15 @@ spec: serviceAccountName: ambassador ``` -* Set the `service_port` element in the `ambassador Module` to 8080 (cleartext) or 8443 (TLS). This is the port that $productName$ will use to listen to incoming traffic. Note that any port number above 1024 will work; $productName$ will use 8080/8443 as its defaults in the future. +* Set the `service_port` element in the `ambassador Module` to 8080 (cleartext) or 8443 (TLS). This is the port that Emissary will use to listen to incoming traffic. Note that any port number above 1024 will work; Emissary will use 8080/8443 as its defaults in the future. -* Make sure that incoming traffic to $productName$ is configured to route to the `service_port`. If you're using the default $productName$ configuration, this means configuring the `targetPort` to point to the `service_port` above. +* Make sure that incoming traffic to Emissary is configured to route to the `service_port`. If you're using the default Emissary configuration, this means configuring the `targetPort` to point to the `service_port` above. * If you are using `redirect_cleartext_from`, change the value of this field to point to your cleartext port (e.g., 8080) and set `service_port` to be your TLS port (e.g., 8443). ## Changing the configuration directory -While running, $productName$ needs to use a directory within its container for generated configuration data. Normally this is `/ambassador`, but in some situations - especially if running as non-root - it may be necessary to change to a different directory. To do so, set the environment variable `AMBASSADOR_CONFIG_BASE_DIR` to the full pathname of the directory to use, as shown below in this abbreviated example: +While running, Emissary needs to use a directory within its container for generated configuration data. Normally this is `/ambassador`, but in some situations - especially if running as non-root - it may be necessary to change to a different directory. To do so, set the environment variable `AMBASSADOR_CONFIG_BASE_DIR` to the full pathname of the directory to use, as shown below in this abbreviated example: ```yaml env: @@ -57,19 +57,19 @@ env: value: /tmp/ambassador-config ``` -With `AMBASSADOR_CONFIG_BASE_DIR` set as above, $productName$ will create and use the directory `/tmp/ambassador-config` for its generated data. (Note that, while the directory will be created if it does not exist, attempts to turn an existing file into a directory will fail.) +With `AMBASSADOR_CONFIG_BASE_DIR` set as above, Emissary will create and use the directory `/tmp/ambassador-config` for its generated data. (Note that, while the directory will be created if it does not exist, attempts to turn an existing file into a directory will fail.) ## Running as DaemonSet -$productName$ can be deployed as a DaemonSet to have one pod per node in a Kubernetes cluster. This setup is especially helpful when you have a Kubernetes cluster running on a private cloud. +Emissary can be deployed as a DaemonSet to have one pod per node in a Kubernetes cluster. This setup is especially helpful when you have a Kubernetes cluster running on a private cloud. -* In an ideal example scenario, you are running containers on Kubernetes alongside with your non-containerized applications running exposed via VIP using BIG-IP or similar products. In such cases, east-west traffic is routed based on iRules to certain a set of application pools consisting of application or web servers. In this setup, alongside traditional application servers, two or more $productName$ pods can also be part of the application pools. In case of failure there is at least one $productName$ pod available to BIG-IP that can take care of routing traffic to the Kubernetes cluster. +* In an ideal example scenario, you are running containers on Kubernetes alongside with your non-containerized applications running exposed via VIP using BIG-IP or similar products. In such cases, east-west traffic is routed based on iRules to certain a set of application pools consisting of application or web servers. In this setup, alongside traditional application servers, two or more Emissary pods can also be part of the application pools. In case of failure there is at least one Emissary pod available to BIG-IP that can take care of routing traffic to the Kubernetes cluster. * In manifest files `kind: Deployment` needs to be updated to `kind: DaemonSet` and `replicas` should be removed in `spec` section. ## Namespaces -$productName$ supports multiple namespaces within Kubernetes. To make this work correctly, you need to set the `AMBASSADOR_NAMESPACE` environment variable in $productName$'s container. By far the easiest way to do this is using Kubernetes' downward API (this is included in the YAML files from `getambassador.io`): +Emissary supports multiple namespaces within Kubernetes. To make this work correctly, you need to set the `AMBASSADOR_NAMESPACE` environment variable in Emissary's container. By far the easiest way to do this is using Kubernetes' downward API (this is included in the YAML files from `getambassador.io`): ```yaml env: @@ -79,9 +79,9 @@ env: fieldPath: metadata.namespace ``` -Given that `AMBASSADOR_NAMESPACE` is set, $productName$ [`Mappings`](../../using/mappings) can operate within the same namespace, or across namespaces. **Note well** that `Mappings` will have to explicitly include the namespace with the service to cross namespaces; see the [`Mapping`](../../using/mappings) documentation for more information. +Given that `AMBASSADOR_NAMESPACE` is set, Emissary [`Mappings`](../../using/mappings) can operate within the same namespace, or across namespaces. **Note well** that `Mappings` will have to explicitly include the namespace with the service to cross namespaces; see the [`Mapping`](../../using/mappings) documentation for more information. -If you want $productName$ to only work within a single namespace, set `AMBASSADOR_SINGLE_NAMESPACE` as an environment variable. +If you want Emissary to only work within a single namespace, set `AMBASSADOR_SINGLE_NAMESPACE` as an environment variable. ```yaml env: @@ -93,7 +93,7 @@ env: value: "true" ``` -With $productName$, if you set `AMBASSADOR_NAMESPACE` or `AMBASSADOR_SINGLE_NAMESPACE`, set it in the deployment container. +With Emissary, if you set `AMBASSADOR_NAMESPACE` or `AMBASSADOR_SINGLE_NAMESPACE`, set it in the deployment container. If you want to set a certificate for your `TLScontext` from another namespace, you can use the following: @@ -112,7 +112,7 @@ env: ## `AMBASSADOR_ID` -$productName$ supports running multiple $productNamePlural$ in the same cluster, without restricting a given $productName$ to a single namespace. This is done with the `AMBASSADOR_ID` setting. In the `ambassador Module`, set the `ambassador_id`, e.g., +Emissary supports running multiple $productNamePlural$ in the same cluster, without restricting a given Emissary to a single namespace. This is done with the `AMBASSADOR_ID` setting. In the `ambassador Module`, set the `ambassador_id`, e.g., ```yaml --- @@ -126,7 +126,7 @@ spec: ... ``` -Then, assign each $productName$ pod a unique `AMBASSADOR_ID` with the environment variable as part of your deployment: +Then, assign each Emissary pod a unique `AMBASSADOR_ID` with the environment variable as part of your deployment: ```yaml env: @@ -134,9 +134,9 @@ env: value: ambassador-1 ``` -With $productName$, if you set `AMBASSADOR_ID`, you will need to set it in the deployment container. +With Emissary, if you set `AMBASSADOR_ID`, you will need to set it in the deployment container. -$productName$ will then only use YAML objects that include an appropriate `ambassador_id` attribute. For example, if $productName$ is given the ID `ambassador-1` as above, only the first two YAML objects below will be used: +Emissary will then only use YAML objects that include an appropriate `ambassador_id` attribute. For example, if Emissary is given the ID `ambassador-1` as above, only the first two YAML objects below will be used: ```yaml --- @@ -176,15 +176,15 @@ spec: service: demo4 ``` -`ambassador_id` is always a list, and may (as shown in `mapping-used-2` above) include multiple IDs to allow a given object in the configuration for multiple $productName$ instances. In this case, `mapping-used-2` will be included in the configuration for `ambassador-1` and also for `ambassador-2`. +`ambassador_id` is always a list, and may (as shown in `mapping-used-2` above) include multiple IDs to allow a given object in the configuration for multiple Emissary instances. In this case, `mapping-used-2` will be included in the configuration for `ambassador-1` and also for `ambassador-2`. -**Note well that _any_ $productName$ configuration resource can have an `ambassador_id` included** so, for example, it is _fully supported_ to use `ambassador_id` to qualify the `ambassador Module`, `TLSContext`, and `AuthService` objects. You will need to set `ambassador_id` in all resources you want to use for $productName$. +**Note well that _any_ Emissary configuration resource can have an `ambassador_id` included** so, for example, it is _fully supported_ to use `ambassador_id` to qualify the `ambassador Module`, `TLSContext`, and `AuthService` objects. You will need to set `ambassador_id` in all resources you want to use for Emissary. -If no `AMBASSADOR_ID` is assigned to an $productName$, it will use the ID `default`. If no `ambassador_id` is present in a YAML object, it will also use the ID `default`. +If no `AMBASSADOR_ID` is assigned to an Emissary, it will use the ID `default`. If no `ambassador_id` is present in a YAML object, it will also use the ID `default`. ## `AMBASSADOR_ENVOY_BASE_ID` -$productName$ supports running side-by-side with other envoy-based projects in a single pod. An example of this is running with an `istio` sidecar. This is done with the `AMBASSADOR_ENVOY_BASE_ID` environment variable as part of your deployment: +Emissary supports running side-by-side with other envoy-based projects in a single pod. An example of this is running with an `istio` sidecar. This is done with the `AMBASSADOR_ENVOY_BASE_ID` environment variable as part of your deployment: ```yaml env: @@ -196,55 +196,55 @@ If no `AMBASSADOR_ENVOY_BASE_ID` is provided then it will use the ID `0`. For mo ## `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. +By default, Emissary 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. ## `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. +If `AMBASSADOR_UPDATE_MAPPING_STATUS` is set to the string `true`, Emissary will update the `status` of every `Mapping` CRD that it accepts for its configuration. This has no effect on the proper functioning of Emissary 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. ## `AMBASSADOR_LEGACY_MODE` -Setting `AMBASSADOR_LEGACY_MODE` to `true` will result in $productName$ disabling certain features +Setting `AMBASSADOR_LEGACY_MODE` to `true` will result in Emissary disabling certain features and reverting to older codepaths which may be better preserve certain older behaviors. Legacy mode currently has the following effects: -- $productName$ will switch back to the $productName$ 1.6 input-resource validator (which can significantly -increase configuration latency for $productName$ installations with many resources). -- $productName$ will use the shell boot sequence that was the default up through 1.9.1, rather than the Golang boot sequence that became the default in 1.10.0. +- Emissary will switch back to the Emissary 1.6 input-resource validator (which can significantly +increase configuration latency for Emissary installations with many resources). +- Emissary will use the shell boot sequence that was the default up through 1.9.1, rather than the Golang boot sequence that became the default in 1.10.0. - `AMBASSADOR_FAST_RECONFIGURE` (see below) is not supported in legacy mode. ## `AMBASSADOR_FAST_RECONFIGURE` -Setting `AMBASSADOR_FAST_RECONFIGURE` to "true" enables incremental reconfiguration. When enabled, $productName$ will track deltas from one configuration to the next and recalculate only what is necessary to follow the change. When disabled (the default), $productName$ will recompute the entire configuration at every change. +Setting `AMBASSADOR_FAST_RECONFIGURE` to "true" enables incremental reconfiguration. When enabled, Emissary will track deltas from one configuration to the next and recalculate only what is necessary to follow the change. When disabled (the default), Emissary will recompute the entire configuration at every change. **`AMBASSADOR_FAST_RECONFIGURE` is not supported when `AMBASSADOR_LEGACY_MODE` is active.** ## `AMBASSADOR_ENVOY_API_VERSION` -By default, $productName$ will configure Envoy using the Envoy V3 API. Setting `AMBASSADOR_ENVOY_API_VERSION` to `V2` tells Ambassador to use the Envoy V2 API instead. Since the Envoy V2 API is deprecated in the upstream Envoy project, we strongly recommend using V3 and, as always, providing feedback and bug reports in the $productName$ GitHub repo! +By default, Emissary will configure Envoy using the Envoy V3 API. Setting `AMBASSADOR_ENVOY_API_VERSION` to `V2` tells Ambassador to use the Envoy V2 API instead. Since the Envoy V2 API is deprecated in the upstream Envoy project, we strongly recommend using V3 and, as always, providing feedback and bug reports in the Emissary GitHub repo! Support for the Envoy V2 API and the `AMBASSADOR_ENVOY_API_VERSION` environment variable will -be removed in $productName$ 2.2.0. +be removed in Emissary 2.2.0. ## Configuration from the filesystem -If desired, $productName$ can be configured from YAML files in the directory `$AMBASSADOR_CONFIG_BASE_DIR/ambassador-config` (by default, `/ambassador/ambassador-config`, which is empty in the images built by Datawire). You could volume mount an external configuration directory here, for example, or use a custom Dockerfile to build configuration directly into a Docker image. +If desired, Emissary can be configured from YAML files in the directory `$AMBASSADOR_CONFIG_BASE_DIR/ambassador-config` (by default, `/ambassador/ambassador-config`, which is empty in the images built by Datawire). You could volume mount an external configuration directory here, for example, or use a custom Dockerfile to build configuration directly into a Docker image. -Note well that while $productName$ will read its initial configuration from this directory, configuration loaded from Kubernetes annotations will _replace_ this initial configuration. If this is not what you want, you will need to set the environment variable `AMBASSADOR_NO_KUBEWATCH` so that $productName$ will not try to update its configuration from Kubernetes resources. +Note well that while Emissary will read its initial configuration from this directory, configuration loaded from Kubernetes annotations will _replace_ this initial configuration. If this is not what you want, you will need to set the environment variable `AMBASSADOR_NO_KUBEWATCH` so that Emissary will not try to update its configuration from Kubernetes resources. -Also note that the YAML files in the configuration directory must contain the $productName$ resources, not Kubernetes resources with annotations. +Also note that the YAML files in the configuration directory must contain the Emissary resources, not Kubernetes resources with annotations. ## Log levels and debugging -The $OSSproductName$ and $AESproductName$ support more verbose debugging levels. If using $OSSproductName$, the [diagnostics](../diagnostics) service has a button to enable debug logging. Be aware that if you're running $productName$ on multiple pods, the debug log levels are not enabled for all pods -- they are configured on a per-pod basis. +The Emissary and Ambassador Edge Stack support more verbose debugging levels. If using Emissary, the [diagnostics](../diagnostics) service has a button to enable debug logging. Be aware that if you're running Emissary on multiple pods, the debug log levels are not enabled for all pods -- they are configured on a per-pod basis. -If using $AESproductName$, you can 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`. +If using Ambassador Edge Stack, you can 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 format -By default, $productName$ writes its own logs in a plain text format. To produce logs as JSON instead, set the `AMBASSADOR_JSON_LOGGING` environment variable: +By default, Emissary writes its own logs in a plain text format. To produce logs as JSON instead, set the `AMBASSADOR_JSON_LOGGING` environment variable: ```yaml env: @@ -254,17 +254,17 @@ env: ## Port assignments -$productName$ uses some TCP ports in the range 8000-8499 internally, as well as port 8877. Third-party software integrating with $productName$ should not use ports in this range on the $productName$ pod. +Emissary uses some TCP ports in the range 8000-8499 internally, as well as port 8877. Third-party software integrating with Emissary should not use ports in this range on the Emissary pod. -## $productName$ update checks (Scout) +## Emissary update checks (Scout) -$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 $productName$ will run regardless of the status of Scout (i.e., our uptime has zero impact on your uptime.) +Emissary integrates Scout, a service that periodically checks with Datawire servers to advise of available updates. Scout also sends anonymized usage data and the Emissary version. This information is important to us as we prioritize test coverage, bug fixes, and feature development. Note that Emissary will run regardless of the status of Scout (i.e., our uptime has zero impact on your uptime.) -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. +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 Emissary deployment. -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. +Each Emissary installation generates a unique cluster ID based on the UID of its Kubernetes namespace and its Emissary ID: the resulting cluster ID is a UUID which cannot be used to reveal the namespace name nor Emissary ID itself. Emissary 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 Emissary 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. -Unless disabled, $productName$ will also report the following anonymized information back to Datawire: +Unless disabled, Emissary will also report the following anonymized information back to Datawire: | Attribute | Type | Description | | :------------------------ | :---- | :------------------------ | @@ -280,17 +280,17 @@ Unless disabled, $productName$ will also report the following anonymized informa | `custom_ambassador_id` | bool | has the `ambassador_id` been changed from 'default'? | | `custom_listener_port` | bool | has the listener port been changed from 80/443? | | `diagnostics` | bool | is the diagnostics service enabled? | -| `endpoint_grpc_count` | int | count of endpoints to which $productName$ will originate GRPC | -| `endpoint_http_count` | int | count of endpoints to which $productName$ will originate HTTP or HTTPS | +| `endpoint_grpc_count` | int | count of endpoints to which Emissary will originate GRPC | +| `endpoint_http_count` | int | count of endpoints to which Emissary will originate HTTP or HTTPS | | `endpoint_routing` | bool | is endpoint routing enabled? | | `endpoint_routing_envoy_rh_count` | int | count of endpoints being routed using Envoy `ring_hash` | | `endpoint_routing_envoy_maglev_count` | int | count of endpoints being routed using Envoy `maglev` | | `endpoint_routing_envoy_lr_count` | int | count of endpoints being routed using Envoy `least_request` | | `endpoint_routing_envoy_rr_count` | int | count of endpoints being routed using Envoy `round_robin` | | `endpoint_routing_kube_count` | int | count of endpoints being routed using Kubernetes | -| `endpoint_tls_count` | int | count of endpoints to which $productName$ will originate TLS | +| `endpoint_tls_count` | int | count of endpoints to which Emissary will originate TLS | | `extauth` | bool | is extauth enabled? | -| `extauth_allow_body` | bool | will $productName$ send the body to extauth? | +| `extauth_allow_body` | bool | will Emissary send the body to extauth? | | `extauth_host_count` | int | count of extauth hosts in use | | `extauth_proto` | str | extauth protocol in use ('http', 'grpc', or `null` if not active) | | `group_canary_count` | int | count of Mapping groups that include more than one Mapping | @@ -313,7 +313,7 @@ Unless disabled, $productName$ will also report the following anonymized informa | `k8s_ingress_count` | int | count of Ingress resources in use | | `listener_count` | int | count of active listeners (1 unless `redirect_cleartext_from` or TCP Mappings are in use) | | `liveness_probe` | bool | are liveness probes enabled? | -| `managed_by` | string | tool that manages the $productName$ deployment, if any (e.g. helm, edgectl, etc.) | +| `managed_by` | string | tool that manages the Emissary deployment, if any (e.g. helm, edgectl, etc.) | | `mapping_count` | int | count of Mapping resources in use | | `ratelimit` | bool | is rate limiting in use? | | `ratelimit_custom_domain` | bool | has the rate limiting domain been changed from 'ambassador'? | @@ -336,10 +336,10 @@ Unless disabled, $productName$ will also report the following anonymized informa | `tracing` | bool | is tracing in use? | | `tracing_driver` | str | tracing driver in use ('zipkin', 'lightstep', 'datadog', or `null` if not active) | | `use_proxy_proto` | bool | is the `PROXY` protocol in use? | -| `use_remote_address` | bool | is $productName$ honoring remote addresses? | -| `x_forwarded_proto_redirect` | bool | is $productName$ redirecting based on `X-Forwarded-Proto`? | +| `use_remote_address` | bool | is Emissary honoring remote addresses? | +| `x_forwarded_proto_redirect` | bool | is Emissary redirecting based on `X-Forwarded-Proto`? | | `xff_num_trusted_hops` | int | what is the count of trusted hops for `X-Forwarded-For`? | -The `request_*` counts are always incremental: they contain only information about the last `request_elapsed` seconds. Additionally, they only provide a lower bound -- notably, if an $productName$ pod crashes or exits, no effort is made to ship out a final update, so it's very easy for counts to never be reported. +The `request_*` counts are always incremental: they contain only information about the last `request_elapsed` seconds. Additionally, they only provide a lower bound -- notably, if an Emissary pod crashes or exits, no effort is made to ship out a final update, so it's very easy for counts to never be reported. To completely disable feature reporting, set the environment variable `AMBASSADOR_DISABLE_FEATURES` to any non-empty value. diff --git a/content/en/docs/2.5/topics/running/scaling.md b/content/en/docs/2.5/topics/running/scaling.md index 1406e30f..9296e962 100644 --- a/content/en/docs/2.5/topics/running/scaling.md +++ b/content/en/docs/2.5/topics/running/scaling.md @@ -1,11 +1,13 @@ -# Performance and scaling $productName$ +--- +title: Performance and scaling +--- Scaling any cloud native application is inherently domain specific, however the content here reflects common issues, tips, and tricks that come up frequently. ## Performance dimensions -The performance of $productName$'s control plane can be characterized along a number of +The performance of Emissary's control plane can be characterized along a number of different dimensions: - The number of `TLSContext` resources. @@ -19,30 +21,30 @@ find yourself in need of some of the content in this section. ## Mysterious pod restarts (aka pushing the edge of the envelope) Whether your application is growing organically or whether you are deliberately scale testing, it's -helpful to recognize how $productName$ behaves as it reaches the edge of its performance +helpful to recognize how Emissary behaves as it reaches the edge of its performance envelope along any of these dimensions. -As $productName$ approaches the edge of its performance envelope, it will often manifest as +As Emissary approaches the edge of its performance envelope, it will often manifest as mysterious pod restarts triggered by Kubernetes. This does not always mean there is a problem, it could just mean you need to tune some of the resource limits set in your deployment. When it comes -to scaling, Kubernetes will generally kill an $productName$ pod for one of two reasons: exceeding +to scaling, Kubernetes will generally kill an Emissary pod for one of two reasons: exceeding memory limits or failed liveness/readiness probes. See the [Memory Limits](#memory-limits), [Liveness Probes](#liveness-probes), and [Readiness Probes](#readiness-probes) sections for more on how to cope with these situations. ## Memory limits -$productName$ can grow in memory usage and be killed by Kubernetes if it exceeds the limits +Emissary can grow in memory usage and be killed by Kubernetes if it exceeds the limits defined in its pod spec. When this happens it is confusing and difficult to catch because the only indication that this has occurred is the pod transitioning momentarily into the `OOMKilled` state. The only way to actually observe this is if you are lucky enough to be running the following -command (or have similar monitoring configured) when $productName$ gets `OOMKilled`: +command (or have similar monitoring configured) when Emissary gets `OOMKilled`: ``` kubectl get pods -n ambassador -w ``` -In order to take the luck out of the equation, $productName$ will periodically log its +In order to take the luck out of the equation, Emissary will periodically log its memory usage so you can see in the logs if memory limits might be a problem and require adjustment: ``` @@ -54,56 +56,56 @@ memory usage so you can see in the logs if memory limits might be a problem and PID 48, 0.08Gi: envoy -c /ambassador/bootstrap-ads.json --base-id 0 --drain-time-s 600 -l error ``` -In general you should try to keep $productName$'s memory usage below 50% of the pod's limit. This may -seem like a generous safety margin, but when reconfiguration occurs, $productName$ requires additional -memory to avoid disrupting active connections. At each reconfiguration, $productName$ keeps around the +In general you should try to keep Emissary's memory usage below 50% of the pod's limit. This may +seem like a generous safety margin, but when reconfiguration occurs, Emissary requires additional +memory to avoid disrupting active connections. At each reconfiguration, Emissary keeps around the old version for the duration of the configured drain time. See [AMBASSADOR_DRAIN_TIME](#ambassador_drain_time) for more details on how to tune this behavior. -$productName$'s exact memory usage depends on (among other things) how many `Host` and +Emissary's exact memory usage depends on (among other things) how many `Host` and `Mapping` resources are defined in your cluster. If this number has grown over time, you may need to increase the memory limit defined in your deployment. ## Liveness probes -$productName$ defines the `/ambassador/v0/check_alive` endpoint on port `8877` for use with Kubernetes +Emissary defines the `/ambassador/v0/check_alive` endpoint on port `8877` for use with Kubernetes liveness probes. See the Kubernetes documentation for more details on [HTTP liveness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-a-liveness-http-request). -Kubernetes will restart the $productName$ pod if it fails to get a 200 result from the endpoint. If +Kubernetes will restart the Emissary pod if it fails to get a 200 result from the endpoint. If this happens it won't necessarily show up in an easily recognizable way in the pod logs. You can look for Kubernetes events to see if this is happening. Use `kubectl describe pod -n ambassador` or `kubectl get events -n ambassador` or equivalent. -The purpose of liveness probes is to rescue an $productName$ instance that is wedged, however if -liveness probes are too sensitive they can take out $productName$ instances that are functioning -normally. This is more prone to happen as the number of $productName$ inputs increase. The -`timeoutSeconds` and `failureThreshold` fields of the $productName$ deployment's liveness Probe +The purpose of liveness probes is to rescue an Emissary instance that is wedged, however if +liveness probes are too sensitive they can take out Emissary instances that are functioning +normally. This is more prone to happen as the number of Emissary inputs increase. The +`timeoutSeconds` and `failureThreshold` fields of the Emissary deployment's liveness Probe determines how tolerant Kubernetes is with its probes. If you observe pod restarts along with `Unhealthy` events, try tuning these fields upwards from their default values. See the Kubernetes documentation for more details on [tuning probes](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#probe-v1-core). -Note that whatever changes you make to $productName$'s liveness probes should most likely be made to +Note that whatever changes you make to Emissary's liveness probes should most likely be made to its readiness probes also. ## Readiness probes -$productName$ defines the `/ambassador/v0/check_ready` endpoint on port `8877` for use with Kubernetes +Emissary defines the `/ambassador/v0/check_ready` endpoint on port `8877` for use with Kubernetes readiness probes. See the Kubernetes documentation for more details on [readiness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-readiness-probes). Kubernetes uses readiness checks to prevent traffic from going to pods that are not ready to handle -requests. The only time $productName$ cannot usefully handle requests is during initial startup when it +requests. The only time Emissary cannot usefully handle requests is during initial startup when it has not yet loaded all the routing information from Kubernetes and/or consul. During this bootstrap -period there is no guarantee $productName$ would know where to send a given request. The `check_ready` +period there is no guarantee Emissary would know where to send a given request. The `check_ready` endpoint will only return 200 when all routing information has been loaded. After the initial bootstrap period it behaves identically to the `check_alive` endpoint. -Generally $productName$'s readiness probes should be configured with the same settings as its liveness +Generally Emissary's readiness probes should be configured with the same settings as its liveness probes. ## `AMBASSADOR_FAST_RECONFIGURE` and `AMBASSADOR_LEGACY_MODE` flags `AMBASSADOR_FAST_RECONFIGURE` is a feature flag that enables a higher performance implementation of -the code $productName$ uses to validate and generate envoy configuration. It will eventually be enabled +the code Emissary uses to validate and generate envoy configuration. It will eventually be enabled by default, but if you are experiencing performance problems you should try setting `AMBASSADOR_FAST_RECONFIGURE` to `true` to see if this helps. @@ -111,9 +113,9 @@ by default, but if you are experiencing performance problems you should try sett ## `AMBASSADOR_DRAIN_TIME` -The `AMBASSADOR_DRAIN_TIME` variable controls how much of a grace period $productName$ provides active +The `AMBASSADOR_DRAIN_TIME` variable controls how much of a grace period Emissary 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 +can impact memory usage because Emissary needs to keep around old versions of its configuration for the duration of the drain time. ## Unconstrained Mappings with many hosts @@ -124,9 +126,9 @@ unconstrained `Mapping`s. An unconstrained `Mapping` is one that is not restrict it is the appropriate thing to do, however if you do not intend to do this, then you can end up with many more routes than you had intended and this can adversely impact performance. -## Inspecting $productName$ performance +## Inspecting Emissary performance -$productName$ internally tracks a number of key performance indicators. You can inspect these via the +Emissary internally tracks a number of key performance indicators. You can inspect these via the debug endpoint at `localhost:8877/debug`. Note that the `AMBASSADOR_FAST_RECONFIGURE` flag needs to be set to `"true"` for this endpoint to be present: @@ -154,7 +156,7 @@ $ kubectl exec -n ambassador -it ${POD} curl localhost:8877/debug # This timer tells us how long we spend reconciling changes to consul inputs. "reconcileConsul": "2, 50.104µs/55.499µs/60.894µs", - # This timer tells us how long we spend reconciling secrets related changes to $productName$ + # This timer tells us how long we spend reconciling secrets related changes to Emissary # inputs. "reconcileSecrets": "2, 18.704µs/20.786µs/22.868µs" }, @@ -176,7 +178,7 @@ $ kubectl exec -n ambassador -it ${POD} curl localhost:8877/debug ## Running profiles -$productName$ exposes endpoints at `localhost:8877/debug/pprof` to run Golang profiles to aid in live debugging. The endpoints are equivalent to those found in the [http/pprof](https://pkg.go.dev/net/http/pprof) package. `/debug/pprof/` returns an HTML page listing the available profiles. +Emissary exposes endpoints at `localhost:8877/debug/pprof` to run Golang profiles to aid in live debugging. The endpoints are equivalent to those found in the [http/pprof](https://pkg.go.dev/net/http/pprof) package. `/debug/pprof/` returns an HTML page listing the available profiles. The following are the different types of profiles you can run: diff --git a/content/en/docs/2.5/topics/running/services/_index.md b/content/en/docs/2.5/topics/running/services/_index.md new file mode 100644 index 00000000..e2f6d1b7 --- /dev/null +++ b/content/en/docs/2.5/topics/running/services/_index.md @@ -0,0 +1,14 @@ +--- +title: Services +weight: -30 +--- + +You may need an API Gateway to enforce policies specific to your organization. Emissary supports custom policies through external service plugins. The policy logic specific to your organization is implemented in the external service, and Emissary is configured to send RPC requests to your service. + +Currently, Emissary supports plugins for authentication, +access logging, rate limiting, and tracing. + +* [AuthService](auth-service) Plugin +* [LogService](log-service) Plugin +* [RateLimitService](rate-limit-service) Plugin +* [TracingService](tracing-service) Plugin diff --git a/content/en/docs/2.5/topics/running/services/auth-service.md b/content/en/docs/2.5/topics/running/services/auth-service.md index a56b15f3..96eca03b 100644 --- a/content/en/docs/2.5/topics/running/services/auth-service.md +++ b/content/en/docs/2.5/topics/running/services/auth-service.md @@ -1,34 +1,34 @@ -import Alert from '@material-ui/lab/Alert'; - -# Authentication service +--- +title: Authentication service +--- -$productName$ provides a highly flexible mechanism for authentication, +Emissary provides a highly flexible mechanism for authentication, via the `AuthService` resource. An `AuthService` configures -$productName$ to use an external service to check authentication and +Emissary to use an external service to check authentication and authorization for incoming requests. Each incoming request is authenticated before routing to its destination. All requests are validated by the `AuthService` (unless the `Mapping` applied to the request sets `bypass_auth`). It is not possible to combine multiple `AuthServices`. While it is possible to create -multiple `AuthService` resources, $productName$ load-balances between +multiple `AuthService` resources, Emissary load-balances between them in a round-robin fashion. This is useful for canarying an `AuthService` change, but is not useful for deploying multiple distinct `AuthServices`. In order to combine multiple external services (either having multiple services apply to the same request, or selecting between different services for the different requests), -instead of using an `AuthService`, use an [$AESproductName$ `External` +instead of using an `AuthService`, use an [Ambassador Edge Stack `External` `Filter`](/docs/edge-stack/latest/topics/using/filters/). -Because of the limitations described above, **$AESproductName$ does +Because of the limitations described above, **Ambassador Edge Stack does not support `AuthService` resources, and you should instead use an [`External` `Filter`](/docs/edge-stack/latest/topics/using/filters/external),** which is mostly a drop-in replacement for an `AuthService`. The -`External` `Filter` relies on the $AESproductName$ `AuthService`. -Make sure the $AESproductName$ `AuthService` is deployed before +`External` `Filter` relies on the Ambassador Edge Stack `AuthService`. +Make sure the Ambassador Edge Stack `AuthService` is deployed before configuring `External` `Filters`. @@ -120,7 +120,7 @@ being used. ## Configuring public `Mappings` An `AuthService` can be disabled for a `Mapping` by setting -`bypass_auth` to `true`. This will tell $productName$ to allow all +`bypass_auth` to `true`. This will tell Emissary to allow all requests for that `Mapping` through without interacting with the external auth service. @@ -130,7 +130,7 @@ external auth service. > **Note:** The following information is only applicable to `AuthServices` using `proto: grpc` -As of $productName$ version 2.3, the `v2` transport protocol is deprecated and any AuthServices making use +As of Emissary version 2.3, the `v2` transport protocol is deprecated and any AuthServices making use of it should migrate to `v3` before support for `v2` is removed in a future release. The following imports simply need to be updated to migrate an AuthService diff --git a/content/en/docs/2.5/topics/running/services/ext_authz.md b/content/en/docs/2.5/topics/running/services/ext_authz.md index 26e91ce5..c3fc68e3 100644 --- a/content/en/docs/2.5/topics/running/services/ext_authz.md +++ b/content/en/docs/2.5/topics/running/services/ext_authz.md @@ -1,4 +1,6 @@ -# ExtAuth protocol +--- +title: ExtAuth protocol +--- By design, the ExtAuth protocol used by [the AuthService](../auth-service) and by [External Filters](/docs/edge-stack/latest/topics/using/filters/external) is highly flexible. The authentication service is the first external service invoked on an incoming request (e.g., it runs before the rate limit filter). Because the logic of authentication is encapsulated in an external service, you can use this to support a wide variety of use cases. For example: @@ -11,7 +13,7 @@ For each request, the ExtAuth service may either: 1. return a direct HTTP *response*, intended to be sent back to the requesting HTTP client (normally *denying* the request from being forwarded to the upstream backend service) or 2. return a modification to make to the HTTP *request* before sending it to the upstream backend service (normally *allowing* the request to be forwarded to the upstream backend service with modifications). -The ExtAuth service receives information about every request through $productName$ and must indicate whether the request is to be allowed or not. If not, the ExtAuth service provides the HTTP response which is to be handed back to the client. A potential control flow for Authentication is shown in the image below. +The ExtAuth service receives information about every request through Emissary and must indicate whether the request is to be allowed or not. If not, the ExtAuth service provides the HTTP response which is to be handed back to the client. A potential control flow for Authentication is shown in the image below. Giving the ExtAuth service the ability to control the response allows many different types of auth mechanisms, for example: @@ -32,7 +34,7 @@ External services for `proto: http` are often easier to implement, but have seve - The list of headers that the ExtAuth service would like to set or modify must be known ahead of time, in order to set `allow_authorization_headers`. Setting headers that are not known ahead of time requires instead using `proto: grpc`. - When returning a direct HTTP response, the HTTP status code cannot be 200 or in the 5XX range. Intercepting with a 200 or 5XX response requires instead using `proto: grpc`. -#### The request From $productName$ to the ExtAuth service +#### The request From Emissary to the ExtAuth service For every incoming request, a similar request is made to the ExtAuth service that mimics the: - HTTP request method @@ -57,7 +59,7 @@ Content-Length: 27 { "greeting": "hello world!", "spiders": "OMG no" } ``` -The request $productName$ will make of the auth service is: +The request Emissary will make of the auth service is: ``` PUT /path/to/service HTTP/1.1 @@ -68,16 +70,16 @@ Content-Type: application/json Content-Length: 0 ``` -#### The response returned from the ExtAuth service to $productName$ +#### The response returned from the ExtAuth service to Emissary - - If the HTTP response returned from the ExtAuth service to $productName$ has an HTTP status code of 200, then the request is allowed through to the upstream backend service. **Only** 200 indicates this; other 2XX status codes will prevent the request from being allowed through. + - If the HTTP response returned from the ExtAuth service to Emissary has an HTTP status code of 200, then the request is allowed through to the upstream backend service. **Only** 200 indicates this; other 2XX status codes will prevent the request from being allowed through. The 200 response should not contain anything in the body, but may contain arbitrary headers. Any header present in the ExtAuth service' response that is also either listed in the `allow_authorization_headers` attribute of the AuthService resource or in the fixed list of headers that are always included will be copied from the ExtAuth service's response into the request going to the upstream backend service. This allows the ExtAuth service to inject tokens or other information into the request, or to modify headers coming from the client. The big limitation here is that the list of headers to be set must be known ahead of time, in order to set `allow_request_headers`. Setting headers that are not known ahead of time requires instead using `proto: grpc`. - - If $productName$ cannot reach the ExtAuth service at all, if the ExtAuth service does not return a valid HTTP response, or if the HTTP response has an HTTP status code in the 5XX range, then the communication with the ExtAuth service is considered to have failed, and the `status_on_error` or `failure_mode_allow` behavior is triggered. + - If Emissary cannot reach the ExtAuth service at all, if the ExtAuth service does not return a valid HTTP response, or if the HTTP response has an HTTP status code in the 5XX range, then the communication with the ExtAuth service is considered to have failed, and the `status_on_error` or `failure_mode_allow` behavior is triggered. - - Any HTTP status code other than 200 or 5XX from the ExtAuth service tells $productName$ to **not** allow the request to continue to the upstream backend service, but that the ExtAuth service is instead intercepting the request. The entire HTTP response from the ExtAuth service--including the status code, the headers, and the body--is handed back to the client verbatim. This gives the ExtAuth service **complete** control over the entire response presented to the client. + - Any HTTP status code other than 200 or 5XX from the ExtAuth service tells Emissary to **not** allow the request to continue to the upstream backend service, but that the ExtAuth service is instead intercepting the request. The entire HTTP response from the ExtAuth service--including the status code, the headers, and the body--is handed back to the client verbatim. This gives the ExtAuth service **complete** control over the entire response presented to the client. The big limitation here is that you cannot directly return a 200 or 5XX response. Intercepting with a 200 of 5XX response requires instead using `proto: grpc`. diff --git a/content/en/docs/2.5/topics/running/services/index.md b/content/en/docs/2.5/topics/running/services/index.md deleted file mode 100644 index 1646aa5a..00000000 --- a/content/en/docs/2.5/topics/running/services/index.md +++ /dev/null @@ -1,11 +0,0 @@ -# Available plugins - -You may need an API Gateway to enforce policies specific to your organization. $productName$ supports custom policies through external service plugins. The policy logic specific to your organization is implemented in the external service, and $productName$ is configured to send RPC requests to your service. - -Currently, $productName$ supports plugins for authentication, -access logging, rate limiting, and tracing. - -* [AuthService](auth-service) Plugin -* [LogService](log-service) Plugin -* [RateLimitService](rate-limit-service) Plugin -* [TracingService](tracing-service) Plugin diff --git a/content/en/docs/2.5/topics/running/services/log-service.md b/content/en/docs/2.5/topics/running/services/log-service.md index 914585c3..cef962c6 100644 --- a/content/en/docs/2.5/topics/running/services/log-service.md +++ b/content/en/docs/2.5/topics/running/services/log-service.md @@ -1,12 +1,14 @@ -# Log service +--- +title: Log Service +--- -By default, $productName$ puts the access logs on stdout; such +By default, Emissary puts the access logs on stdout; such that the can be read using `kubectl logs`. The format of those logs, and the local destination of them, can be configured using the [`envoy_log_` settings in the `ambassador Module`](../../ambassador). However, the -options there only allow for logging local to $productName$'s Pod. By -configuring a `LogService`, you can configure $productName$ to +options there only allow for logging local to Emissary's Pod. By +configuring a `LogService`, you can configure Emissary to report its access logs to a remote service, in addition to the usual `ambassador Module` configured logging. @@ -22,7 +24,7 @@ kind: LogService metadata: name: example-log-service spec: - # Common to all $productName$ resources + # Common to all Emissary resources ambassador_id: []string # optional; default is ["default"] # LogService specific @@ -97,7 +99,7 @@ spec: > **Note:** The following information is only applicable to `AuthServices` using `proto: grpc` -As of $productName$ version 2.3, the `v2` transport protocol is deprecated and any AuthServices making use +As of Emissary version 2.3, the `v2` transport protocol is deprecated and any AuthServices making use of it should migrate to `v3` before support for `v2` is removed in a future release. The following imports simply need to be updated to migrate an AuthService diff --git a/content/en/docs/2.5/topics/running/services/rate-limit-service.md b/content/en/docs/2.5/topics/running/services/rate-limit-service.md index b45fc704..0ecb72ed 100644 --- a/content/en/docs/2.5/topics/running/services/rate-limit-service.md +++ b/content/en/docs/2.5/topics/running/services/rate-limit-service.md @@ -1,14 +1,16 @@ -# Rate limit service +--- +title: Rate limit service +--- Rate limiting is a powerful technique to improve the [availability and resilience of your services](https://blog.getambassador.io/rate-limiting-a-useful-tool-with-distributed-systems-6be2b1a4f5f4). -In $productName$, each request can have one or more _labels_. These labels are +In Emissary, each request can have one or more _labels_. These labels are exposed to a third-party service via a gRPC API. The third-party service can then rate limit requests based on the request labels. -**Note that `RateLimitService` is only applicable to $OSSproductName$, -and not $AESproductName$, as $AESproductName$ includes a +**Note that `RateLimitService` is only applicable to Emissary, +and not Ambassador Edge Stack, as Ambassador Edge Stack includes a built-in rate limit service.** ## Request labels @@ -19,7 +21,7 @@ for how to configure the labels that are attached to a request. ## Domains -In $productName$, each engineer (or team) can be assigned its own _domain_. A +In Emissary, each engineer (or team) can be assigned its own _domain_. A domain is a separate namespace for labels. By creating individual domains, each team can assign their own labels to a given request, and independently set the rate limits based on their own labels. @@ -30,15 +32,15 @@ for how to labels under different domains. ## External rate limit service -In order for $productName$ to rate limit, you need to implement a +In order for Emissary to rate limit, you need to implement a gRPC `RateLimitService`, as defined in [Envoy's `v2/rls.proto`] interface. If you do not have the time or resources to implement your own rate -limit service, $AESproductName$ integrates a high-performance rate +limit service, Ambassador Edge Stack integrates a high-performance rate limiting service. [envoy's `v2/rls.proto`]: https://github.com/emissary-ingress/emissary/tree/master/api/envoy/service/ratelimit/v2/rls.proto -$productName$ generates a gRPC request to the external rate limit +Emissary generates a gRPC request to the external rate limit service and provides a list of labels on which the rate limit service can base its decision to accept or reject the request: @@ -52,7 +54,7 @@ its decision to accept or reject the request: ] ``` -If $productName$ cannot contact the rate limit service, it will +If Emissary cannot contact the rate limit service, it will allow the request to be processed as if there were no rate limit service configuration. @@ -60,9 +62,9 @@ It is the external rate limit service's responsibility to determine whether rate limiting should take place, depending on custom business logic. The rate limit service must simply respond to the request with an `OK` or `OVER_LIMIT` code: -- If Envoy receives an `OK` response from the rate limit service, then $productName$ allows the client request to resume being processed by +- If Envoy receives an `OK` response from the rate limit service, then Emissary allows the client request to resume being processed by the normal flow. -- If Envoy receives an `OVER_LIMIT` response, then $productName$ +- If Envoy receives an `OVER_LIMIT` response, then Emissary will return an HTTP 429 response to the client and will end the transaction flow, preventing the request from reaching the backing service. @@ -72,7 +74,7 @@ the rate limit service since the `AuthService` is invoked before the ## Configuring the rate limit service -A `RateLimitService` manifest configures $productName$ to use an +A `RateLimitService` manifest configures Emissary to use an external service to check and enforce rate limits for incoming requests: ```yaml @@ -87,30 +89,30 @@ spec: ``` - `service` gives the URL of the rate limit service. If using a Kubernetes service, this should be the [namespace-qualified DNS name](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#namespaces-of-services) of that service. -- `protocol_version` (optional) gRPC service name used to communicate with the `RateLimitService`. Allowed values are `v2` which will use the `envoy.service.ratelimit.v2.RateLimitService`, and `v3` which will use the `envoy.service.ratelimit.v3.RateLimitService` service name. Note that `v3` requires $productName$ to run in Envoy v3 mode by setting the AMBASSADOR_ENVOY_API_VERSION=V3 environment variable. +- `protocol_version` (optional) gRPC service name used to communicate with the `RateLimitService`. Allowed values are `v2` which will use the `envoy.service.ratelimit.v2.RateLimitService`, and `v3` which will use the `envoy.service.ratelimit.v3.RateLimitService` service name. Note that `v3` requires Emissary to run in Envoy v3 mode by setting the AMBASSADOR_ENVOY_API_VERSION=V3 environment variable. You may only use a single `RateLimitService` manifest. ## Rate limit service and TLS -You can tell $productName$ to use TLS to talk to your service by +You can tell Emissary to use TLS to talk to your service by using a `RateLimitService` with an `https://` prefix. However, you may also -provide a `tls` attribute: if `tls` is present and `true`, $productName$ will originate TLS even if the `service` does not have the `https://` +provide a `tls` attribute: if `tls` is present and `true`, Emissary will originate TLS even if the `service` does not have the `https://` prefix. If `tls` is present with a value that is not `true`, the value is assumed to be the name of a defined TLS context, which will determine the certificate presented to the upstream service. ## Example -The [$OSSproductName$ Rate Limiting +The [Emissary Rate Limiting Tutorial](../../../../howtos/rate-limiting-tutorial) has a simple rate limiting example. For a more advanced example, read the [advanced rate limiting tutorial](../../../../../2.0/howtos/advanced-rate-limiting), which uses the rate limit -service that is integrated with $AESproductName$. +service that is integrated with Ambassador Edge Stack. ## Further reading - [Rate limiting: a useful tool with distributed systems](https://blog.getambassador.io/rate-limiting-a-useful-tool-with-distributed-systems-6be2b1a4f5f4) - [Rate limiting for API Gateways](https://blog.getambassador.io/rate-limiting-for-api-gateways-892310a2da02) -- [Implementing a Java Rate Limiting Service for $productName$](https://blog.getambassador.io/implementing-a-java-rate-limiting-service-for-the-ambassador-api-gateway-e09d542455da) -- [Designing a Rate Limit Service for $productName$](https://blog.getambassador.io/designing-a-rate-limiting-service-for-ambassador-f460e9fabedb) +- [Implementing a Java Rate Limiting Service for Emissary](https://blog.getambassador.io/implementing-a-java-rate-limiting-service-for-the-ambassador-api-gateway-e09d542455da) +- [Designing a Rate Limit Service for Emissary](https://blog.getambassador.io/designing-a-rate-limiting-service-for-ambassador-f460e9fabedb) diff --git a/content/en/docs/2.5/topics/running/services/tracing-service.md b/content/en/docs/2.5/topics/running/services/tracing-service.md index 35e9f196..c8dd0f4a 100644 --- a/content/en/docs/2.5/topics/running/services/tracing-service.md +++ b/content/en/docs/2.5/topics/running/services/tracing-service.md @@ -1,10 +1,12 @@ -# Tracing service +--- +title: Tracing service +--- Applications that consist of multiple services can be difficult to debug, as a single request can span multiple services. Distributed tracing tells the story of your request as it is processed through your system. Distributed tracing is a powerful tool to debug and analyze your system in addition to request logging and metrics. -When enabled, the `TracingService` will instruct $productName$ to initiate a trace on requests by generating and populating an `x-request-id` HTTP header. Services can make use of this `x-request-id` header in logging and forward it in downstream requests for tracing. $productName$ also integrates with external trace visualization services, including [LightStep](https://lightstep.com/) and Zipkin-compatible APIs such as [Zipkin](https://zipkin.io/) and [Jaeger](https://github.com/jaegertracing/) to allow you to store and visualize traces. You can read further on [Envoy's Tracing capabilities](https://www.envoyproxy.io/docs/envoy/v1.10.0/intro/arch_overview/tracing). +When enabled, the `TracingService` will instruct Emissary to initiate a trace on requests by generating and populating an `x-request-id` HTTP header. Services can make use of this `x-request-id` header in logging and forward it in downstream requests for tracing. Emissary also integrates with external trace visualization services, including [LightStep](https://lightstep.com/) and Zipkin-compatible APIs such as [Zipkin](https://zipkin.io/) and [Jaeger](https://github.com/jaegertracing/) to allow you to store and visualize traces. You can read further on [Envoy's Tracing capabilities](https://www.envoyproxy.io/docs/envoy/v1.10.0/intro/arch_overview/tracing). -A `TracingService` manifest configures $productName$ to use an external trace visualization service: +A `TracingService` manifest configures Emissary to use an external trace visualization service: ```yaml --- @@ -62,7 +64,7 @@ Please note that you must use the HTTP/2 pseudo-header names. For example: - `service_name` the name of the service which is attached to the traces. The default value is `ambassador`. -You may only use a single `TracingService` manifest per $productName$ deployment. Ensure [ambassador_id](../../running#ambassador_id) is set correctly in the `TracingService` manifest. +You may only use a single `TracingService` manifest per Emissary deployment. Ensure [ambassador_id](../../running#ambassador_id) is set correctly in the `TracingService` manifest. ## Example diff --git a/content/en/docs/2.5/topics/running/statistics/8877-metrics-grafana.json b/content/en/docs/2.5/topics/running/statistics/8877-metrics-grafana.json deleted file mode 100644 index b2b19b37..00000000 --- a/content/en/docs/2.5/topics/running/statistics/8877-metrics-grafana.json +++ /dev/null @@ -1,943 +0,0 @@ -{ - "annotations": { - "list": [ - { - "builtIn": 1, - "datasource": "Prometheus", - "enable": true, - "hide": true, - "iconColor": "rgba(0, 211, 255, 1)", - "name": "Annotations & Alerts", - "type": "dashboard" - } - ] - }, - "description": "Ambassador dashboard for Prometheus", - "editable": true, - "gnetId": 4698, - "graphTooltip": 0, - "id": 1, - "iteration": 1595611060519, - "links": [], - "panels": [ - { - "collapsed": false, - "datasource": null, - "gridPos": { - "h": 1, - "w": 24, - "x": 0, - "y": 0 - }, - "id": 34, - "panels": [], - "title": "Ambassador - Control Plane", - "type": "row" - }, - { - "cacheTimeout": null, - "colorBackground": false, - "colorValue": false, - "colors": [ - "#299c46", - "rgba(237, 129, 40, 0.89)", - "#d44a3a" - ], - "datasource": null, - "format": "none", - "gauge": { - "maxValue": 100, - "minValue": 0, - "show": false, - "thresholdLabels": false, - "thresholdMarkers": true - }, - "gridPos": { - "h": 5, - "w": 5, - "x": 0, - "y": 1 - }, - "id": 36, - "interval": "", - "links": [], - "mappingType": 1, - "mappingTypes": [ - { - "name": "value to text", - "value": 1 - }, - { - "name": "range to text", - "value": 2 - } - ], - "maxDataPoints": 100, - "maxPerRow": 3, - "nullPointMode": "connected", - "nullText": null, - "options": {}, - "postfix": "", - "postfixFontSize": "50%", - "prefix": "", - "prefixFontSize": "50%", - "rangeMaps": [ - { - "from": "null", - "text": "N/A", - "to": "null" - } - ], - "repeat": null, - "repeatDirection": "h", - "sparkline": { - "fillColor": "rgba(31, 118, 189, 0.18)", - "full": false, - "lineColor": "rgb(31, 120, 193)", - "show": false, - "ymax": null, - "ymin": null - }, - "tableColumn": "", - "targets": [ - { - "expr": "ambassador_diagnostics_info{namespace=~\"$namespace\"}", - "format": "time_series", - "hide": false, - "instant": true, - "intervalFactor": 1, - "legendFormat": "{{version}}", - "refId": "A" - } - ], - "thresholds": "", - "timeFrom": null, - "timeShift": null, - "title": "Version", - "type": "singlestat", - "valueFontSize": "80%", - "valueMaps": [], - "valueName": "name" - }, - { - "cacheTimeout": null, - "datasource": null, - "gridPos": { - "h": 5, - "w": 19, - "x": 5, - "y": 1 - }, - "id": 42, - "links": [], - "options": { - "displayMode": "lcd", - "fieldOptions": { - "calcs": [ - "lastNotNull" - ], - "defaults": { - "mappings": [], - "max": 2.5, - "min": 0, - "nullValueMode": "connected", - "thresholds": [ - { - "color": "green", - "value": null - }, - { - "color": "#EAB839", - "value": 1 - }, - { - "color": "red", - "value": 2 - } - ], - "title": "", - "unit": "s" - }, - "override": {}, - "values": false - }, - "orientation": "vertical" - }, - "pluginVersion": "6.4.3", - "repeat": "pod", - "repeatDirection": "v", - "scopedVars": { - "pod": { - "selected": false, - "text": "ambassador-x", - "value": "ambassador-x" - } - }, - "targets": [ - { - "expr": "ambassador_reconfiguration_time_seconds{namespace=~\"$namespace\", pod=~\"$pod\"}", - "instant": false, - "legendFormat": "Reconfiguration", - "refId": "C" - }, - { - "expr": "ambassador_fetcher_time_seconds{namespace=~\"$namespace\", pod=~\"$pod\"}", - "instant": false, - "legendFormat": "Fetcher", - "refId": "E" - }, - { - "expr": "ambassador_aconf_time_seconds{namespace=~\"$namespace\", pod=~\"$pod\"}", - "instant": false, - "legendFormat": "AConf", - "refId": "A" - }, - { - "expr": "ambassador_ir_time_seconds{namespace=~\"$namespace\", pod=~\"$pod\"}", - "instant": false, - "legendFormat": "IR", - "refId": "F" - }, - { - "expr": "ambassador_econf_time_seconds{namespace=~\"$namespace\", pod=~\"$pod\"}", - "instant": false, - "legendFormat": "EConf", - "refId": "B" - }, - { - "expr": "ambassador_diagnostics_time_seconds{namespace=~\"$namespace\", pod=~\"$pod\"}", - "instant": false, - "legendFormat": "Diagnostics", - "refId": "D" - } - ], - "timeFrom": null, - "timeShift": null, - "title": "Last control plane operation time ($pod)", - "type": "bargauge" - }, - { - "collapsed": true, - "datasource": null, - "gridPos": { - "h": 1, - "w": 24, - "x": 0, - "y": 6 - }, - "id": 38, - "panels": [ - { - "aliasColors": {}, - "bars": false, - "dashLength": 10, - "dashes": false, - "datasource": null, - "fill": 1, - "fillGradient": 0, - "gridPos": { - "h": 7, - "w": 24, - "x": 0, - "y": 2 - }, - "id": 40, - "legend": { - "avg": false, - "current": false, - "max": false, - "min": false, - "show": true, - "total": false, - "values": false - }, - "lines": true, - "linewidth": 1, - "nullPointMode": "null", - "options": { - "dataLinks": [] - }, - "percentage": false, - "pointradius": 2, - "points": false, - "renderer": "flot", - "seriesOverrides": [], - "spaceLength": 10, - "stack": false, - "steppedLine": false, - "targets": [ - { - "expr": " ambassador_edge_stack_go_memstats_alloc_bytes{namespace=~\"$namespace\", pod=~\"$pod\"}", - "legendFormat": "{{pod}}", - "refId": "A" - } - ], - "thresholds": [], - "timeFrom": null, - "timeRegions": [], - "timeShift": null, - "title": "amb-sidecar memory usage", - "tooltip": { - "shared": true, - "sort": 0, - "value_type": "individual" - }, - "type": "graph", - "xaxis": { - "buckets": null, - "mode": "time", - "name": null, - "show": true, - "values": [] - }, - "yaxes": [ - { - "format": "decbytes", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": true - }, - { - "format": "none", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": false - } - ], - "yaxis": { - "align": false, - "alignLevel": null - } - } - ], - "title": "Ambassador", - "type": "row" - }, - { - "collapsed": false, - "datasource": null, - "gridPos": { - "h": 1, - "w": 24, - "x": 0, - "y": 7 - }, - "id": 22, - "panels": [], - "repeat": null, - "title": "Ambassador - Envoy Data Plane", - "type": "row" - }, - { - "aliasColors": {}, - "bars": false, - "dashLength": 10, - "dashes": false, - "datasource": null, - "fill": 1, - "fillGradient": 0, - "gridPos": { - "h": 8, - "w": 24, - "x": 0, - "y": 8 - }, - "id": 30, - "legend": { - "avg": false, - "current": false, - "max": false, - "min": false, - "show": true, - "total": false, - "values": false - }, - "lines": true, - "linewidth": 1, - "links": [], - "nullPointMode": "null", - "options": { - "dataLinks": [] - }, - "percentage": false, - "pointradius": 2, - "points": false, - "renderer": "flot", - "seriesOverrides": [], - "spaceLength": 10, - "stack": false, - "steppedLine": false, - "targets": [ - { - "expr": "sum(increase(envoy_http_downstream_rq_xx{envoy_response_code_class=\"2\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "2xx", - "refId": "A" - }, - { - "expr": "sum(increase(envoy_http_downstream_rq_xx{envoy_response_code_class=\"3\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "3xx", - "refId": "B" - }, - { - "expr": "sum(increase(envoy_http_downstream_rq_xx{envoy_response_code_class=\"4\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "4xx", - "refId": "C" - }, - { - "expr": "sum(increase(envoy_http_downstream_rq_xx{envoy_response_code_class=\"5\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "5xx", - "refId": "D" - } - ], - "thresholds": [], - "timeFrom": null, - "timeRegions": [], - "timeShift": null, - "title": "Ambassador Response Codes", - "tooltip": { - "shared": true, - "sort": 0, - "value_type": "individual" - }, - "type": "graph", - "xaxis": { - "buckets": null, - "mode": "time", - "name": null, - "show": true, - "values": [] - }, - "yaxes": [ - { - "format": "short", - "label": "RPM", - "logBase": 1, - "max": null, - "min": null, - "show": true - }, - { - "format": "short", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": true - } - ], - "yaxis": { - "align": false, - "alignLevel": null - } - }, - { - "aliasColors": {}, - "bars": false, - "dashLength": 10, - "dashes": false, - "datasource": null, - "fill": 1, - "fillGradient": 0, - "gridPos": { - "h": 8, - "w": 24, - "x": 0, - "y": 16 - }, - "id": 20, - "legend": { - "avg": false, - "current": false, - "max": false, - "min": false, - "show": true, - "total": false, - "values": false - }, - "lines": true, - "linewidth": 1, - "links": [], - "nullPointMode": "null", - "options": { - "dataLinks": [] - }, - "percentage": false, - "pointradius": 2, - "points": false, - "renderer": "flot", - "seriesOverrides": [], - "spaceLength": 10, - "stack": false, - "steppedLine": false, - "targets": [ - { - "expr": "sum(increase(envoy_cluster_upstream_rq_xx{envoy_response_code_class=\"2\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "2xx", - "refId": "A" - }, - { - "expr": "sum(increase(envoy_cluster_upstream_rq_xx{envoy_response_code_class=\"3\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "3xx", - "refId": "B" - }, - { - "expr": "sum(increase(envoy_cluster_upstream_rq_xx{envoy_response_code_class=\"4\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "4xx", - "refId": "C" - }, - { - "expr": "sum(increase(envoy_cluster_upstream_rq_xx{envoy_response_code_class=\"5\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "5xx", - "refId": "D" - } - ], - "thresholds": [], - "timeFrom": null, - "timeRegions": [], - "timeShift": null, - "title": "API Response Codes", - "tooltip": { - "shared": true, - "sort": 0, - "value_type": "individual" - }, - "type": "graph", - "xaxis": { - "buckets": null, - "mode": "time", - "name": null, - "show": true, - "values": [] - }, - "yaxes": [ - { - "format": "short", - "label": "RPM", - "logBase": 1, - "max": null, - "min": null, - "show": true - }, - { - "format": "short", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": true - } - ], - "yaxis": { - "align": false, - "alignLevel": null - } - }, - { - "aliasColors": {}, - "bars": false, - "dashLength": 10, - "dashes": false, - "datasource": null, - "fill": 1, - "fillGradient": 0, - "gridPos": { - "h": 8, - "w": 24, - "x": 0, - "y": 24 - }, - "id": 26, - "legend": { - "avg": false, - "current": false, - "max": false, - "min": false, - "show": true, - "total": false, - "values": false - }, - "lines": true, - "linewidth": 1, - "links": [], - "nullPointMode": "null", - "options": { - "dataLinks": [] - }, - "percentage": false, - "pointradius": 2, - "points": false, - "renderer": "flot", - "seriesOverrides": [], - "spaceLength": 10, - "stack": false, - "steppedLine": false, - "targets": [ - { - "expr": "histogram_quantile(0.95, sum(rate(envoy_http_downstream_cx_length_ms_bucket[5m])) by (le))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "95 percentile", - "refId": "A" - }, - { - "expr": "histogram_quantile(0.9, sum(rate(envoy_http_downstream_cx_length_ms_bucket[5m])) by (le))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "90th percentile", - "refId": "B" - }, - { - "expr": "histogram_quantile(0.5, sum(rate(envoy_http_downstream_cx_length_ms_bucket[5m])) by (le))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "50th percentile", - "refId": "C" - } - ], - "thresholds": [], - "timeFrom": null, - "timeRegions": [], - "timeShift": null, - "title": "Downstream Connections Length", - "tooltip": { - "shared": true, - "sort": 0, - "value_type": "individual" - }, - "type": "graph", - "xaxis": { - "buckets": null, - "mode": "time", - "name": null, - "show": true, - "values": [] - }, - "yaxes": [ - { - "format": "short", - "label": "Milliseconds", - "logBase": 1, - "max": null, - "min": null, - "show": true - }, - { - "format": "short", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": true - } - ], - "yaxis": { - "align": false, - "alignLevel": null - } - }, - { - "aliasColors": {}, - "bars": false, - "dashLength": 10, - "dashes": false, - "datasource": null, - "fill": 1, - "fillGradient": 0, - "gridPos": { - "h": 8, - "w": 18, - "x": 0, - "y": 32 - }, - "id": 28, - "legend": { - "avg": false, - "current": false, - "max": false, - "min": false, - "show": true, - "total": false, - "values": false - }, - "lines": true, - "linewidth": 1, - "links": [], - "nullPointMode": "null", - "options": { - "dataLinks": [] - }, - "percentage": false, - "pointradius": 2, - "points": false, - "renderer": "flot", - "seriesOverrides": [], - "spaceLength": 10, - "stack": false, - "steppedLine": false, - "targets": [ - { - "expr": "sum(increase(envoy_http_downstream_cx_http1_active[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "HTTP/1", - "refId": "A" - }, - { - "expr": "sum(increase(envoy_http_downstream_cx_http2_active_active[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "HTTP/2", - "refId": "B" - }, - { - "expr": "sum(increase(envoy_http_downstream_cx_upgrades_active[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "Websocket", - "refId": "C" - } - ], - "thresholds": [], - "timeFrom": null, - "timeRegions": [], - "timeShift": null, - "title": "Active Connections", - "tooltip": { - "shared": true, - "sort": 0, - "value_type": "individual" - }, - "type": "graph", - "xaxis": { - "buckets": null, - "mode": "time", - "name": null, - "show": true, - "values": [] - }, - "yaxes": [ - { - "format": "short", - "label": "RPM", - "logBase": 1, - "max": null, - "min": null, - "show": true - }, - { - "format": "short", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": true - } - ], - "yaxis": { - "align": false, - "alignLevel": null - } - }, - { - "cacheTimeout": null, - "colorBackground": false, - "colorValue": false, - "colors": [ - "#299c46", - "rgba(237, 129, 40, 0.89)", - "#d44a3a" - ], - "datasource": null, - "format": "none", - "gauge": { - "maxValue": 100, - "minValue": 0, - "show": false, - "thresholdLabels": false, - "thresholdMarkers": true - }, - "gridPos": { - "h": 8, - "w": 6, - "x": 18, - "y": 32 - }, - "id": 32, - "interval": null, - "links": [], - "mappingType": 1, - "mappingTypes": [ - { - "name": "value to text", - "value": 1 - }, - { - "name": "range to text", - "value": 2 - } - ], - "maxDataPoints": 100, - "nullPointMode": "connected", - "nullText": null, - "options": {}, - "postfix": "", - "postfixFontSize": "50%", - "prefix": "", - "prefixFontSize": "50%", - "rangeMaps": [ - { - "from": "null", - "text": "N/A", - "to": "null" - } - ], - "sparkline": { - "fillColor": "rgba(31, 118, 189, 0.18)", - "full": false, - "lineColor": "rgb(31, 120, 193)", - "show": false - }, - "tableColumn": "", - "targets": [ - { - "expr": "avg(envoy_cluster_manager_active_clusters)", - "format": "time_series", - "intervalFactor": 1, - "refId": "A" - } - ], - "thresholds": "", - "timeFrom": null, - "timeShift": null, - "title": "Registered Services", - "type": "singlestat", - "valueFontSize": "80%", - "valueMaps": [ - { - "op": "=", - "text": "N/A", - "value": "null" - } - ], - "valueName": "avg" - } - ], - "refresh": "5s", - "schemaVersion": 20, - "style": "dark", - "tags": [ - "ambassador" - ], - "templating": { - "list": [ - { - "allValue": null, - "current": { - "text": "All", - "value": [ - "$__all" - ] - }, - "datasource": "Prometheus", - "definition": "label_values(ambassador_diagnostics_info, namespace)", - "hide": 0, - "includeAll": true, - "label": "Namespace", - "multi": true, - "name": "namespace", - "options": [], - "query": "label_values(ambassador_diagnostics_info, namespace)", - "refresh": 1, - "regex": "", - "skipUrlSync": false, - "sort": 5, - "tagValuesQuery": "", - "tags": [], - "tagsQuery": "", - "type": "query", - "useTags": false - }, - { - "allValue": null, - "current": { - "tags": [], - "text": "All", - "value": [ - "$__all" - ] - }, - "datasource": "Prometheus", - "definition": "label_values(ambassador_diagnostics_info{namespace=\"$namespace\"}, pod)", - "hide": 0, - "includeAll": true, - "label": "Pod", - "multi": true, - "name": "pod", - "options": [], - "query": "label_values(ambassador_diagnostics_info{namespace=\"$namespace\"}, pod)", - "refresh": 1, - "regex": "", - "skipUrlSync": false, - "sort": 5, - "tagValuesQuery": "", - "tags": [], - "tagsQuery": "", - "type": "query", - "useTags": false - } - ] - }, - "time": { - "from": "now-15m", - "to": "now" - }, - "timepicker": { - "refresh_intervals": [ - "5s", - "10s", - "30s", - "1m", - "5m", - "15m", - "30m", - "1h", - "2h", - "1d" - ], - "time_options": [ - "5m", - "15m", - "1h", - "6h", - "12h", - "24h", - "2d", - "7d", - "30d" - ] - }, - "timezone": "", - "title": "Ambassador", - "uid": "AJieHz4Mz", - "version": 16 -} diff --git a/content/en/docs/2.5/topics/running/statistics/8877-metrics.md b/content/en/docs/2.5/topics/running/statistics/8877-metrics.md index c6c64dd9..b8ea0655 100644 --- a/content/en/docs/2.5/topics/running/statistics/8877-metrics.md +++ b/content/en/docs/2.5/topics/running/statistics/8877-metrics.md @@ -1,9 +1,11 @@ -# The metrics endpoint +--- +title: The metrics endpoint +--- > For an overview of other options for gathering statistics on -> $productName$, see the [Statistics and Monitoring](../) overview. +> Emissary, see the [Statistics and Monitoring](../) overview. -Each $productName$ pod exposes statistics and metrics for that pod at +Each Emissary pod exposes statistics and metrics for that pod at `http://{POD}:8877/metrics`. The response is in the text-based Prometheus [exposition format][]. @@ -26,7 +28,7 @@ make the file self-documenting as to what specific statistics mean. - `envoy_*`: See the [Envoy documentation][`GET /stats/prometheus`]. - `ambassador_*` (new in 1.7.0): - - `ambassador_edge_stack_*` (not present in $OSSproductName$): + - `ambassador_edge_stack_*` (not present in Emissary): - `ambassador_edge_stack_go_*`: See [`promethus.NewGoCollector()`][]. - `ambassador_edge_stack_promhttp_*` See [`promhttp.Handler()`][]. - `ambassador_edge_stack_process_*`: See [`promethus.NewProcessCollector()`][].. @@ -37,7 +39,7 @@ make the file self-documenting as to what specific statistics mean. diagnostics errors and notices that would be shown in the diagnostics UI or the Edge Policy Console. - `ambassador_diagnostics_info`: [Info][`prometheus_client.Info`] - about the $productName$ install; all information is presented in + about the Emissary install; all information is presented in labels; the value of the Gauge is always "1". - `ambassador_process_*`: See [`prometheus_client.ProcessCollector`][]. @@ -66,7 +68,7 @@ that displays information collected by Prometheus from the ![Screenshot of a Grafana dashboard that displays just information from Envoy](../../../../images/grafana.png) -[Alex Gervais][] has written a template [$productName$ dashboard for +[Alex Gervais][] has written a template [Emissary dashboard for Grafana][] that displays information collected by Prometheus either from the `:8877/metrics` endpoint, or from [Envoy over StatsD][envoy-statsd-prometheus]. Because it is designed to work with @@ -75,5 +77,5 @@ statistics; because of this, we recommend using the other sample dashboard above. [Alex Gervais]: https://twitter.com/alex_gervais -[$productName$ dashboard for Grafana]: https://grafana.com/dashboards/4698 +[Emissary dashboard for Grafana]: https://grafana.com/dashboards/4698 [envoy-statsd-prometheus]: ../envoy-statsd#using-prometheus-statsd-exporter-as-the-statsd-sink diff --git a/content/en/docs/3.1/topics/running/statistics/index.md b/content/en/docs/2.5/topics/running/statistics/_index.md similarity index 81% rename from content/en/docs/3.1/topics/running/statistics/index.md rename to content/en/docs/2.5/topics/running/statistics/_index.md index 04033002..05eb2818 100644 --- a/content/en/docs/3.1/topics/running/statistics/index.md +++ b/content/en/docs/2.5/topics/running/statistics/_index.md @@ -1,12 +1,15 @@ -# Statistics and monitoring +--- +title: Statistics and monitoring +weight: -20 +--- -$productName$ collects many statistics internally, and makes it easy to +Emissary collects many statistics internally, and makes it easy to direct this information to a statistics and monitoring tool of your choice. As an example, for a given service `usersvc`, here are some interesting statistics to investigate: - `envoy.cluster.usersvc.upstream_rq_total` is the total - number of requests that `usersvc` has received via $productName$. The rate of change of this value is one basic measure of + number of requests that `usersvc` has received via Emissary. The rate of change of this value is one basic measure of service utilization, i.e. requests per second. - `envoy.cluster.usersvc.upstream_rq_2xx` is the total number of requests to which `usersvc` responded with an HTTP response @@ -15,7 +18,7 @@ interesting statistics to investigate: service. There are corresponding `4xx` and `5xx` counters that can help clarify the nature of unsuccessful requests. - `envoy.cluster.usersvc.upstream_rq_time` is a StatsD timer - that tracks the latency in milliseconds of `usersvc` from $productName$'s perspective. StatsD timers include information about + that tracks the latency in milliseconds of `usersvc` from Emissary's perspective. StatsD timers include information about means, standard deviations, and decile values. ## Overriding Statistics Names @@ -30,7 +33,7 @@ underscores: - `service: http://foo:8080` will use `http___foo_8080` - `service: foo.othernamespace` will use `foo_othernamespace` -The last example is worth special mention: a resource in a different namespace than the one in which $productName$ is running will automatically be qualified with the namespace of the resource itself. So, for example, if $productName$ is running in the `ambassador` namespace, and this `Mapping` is present in the `default` namespace: +The last example is worth special mention: a resource in a different namespace than the one in which Emissary is running will automatically be qualified with the namespace of the resource itself. So, for example, if Emissary is running in the `ambassador` namespace, and this `Mapping` is present in the `default` namespace: ```yaml apiVersion: getambassador.io/v3alpha1 @@ -47,14 +50,14 @@ then the `service` will be qualified to `default-service.default`, so the `stats ## Monitoring Statistics -There are several ways to get different statistics out of $productName$: +There are several ways to get different statistics out of Emissary: - [The `:8877/metrics` endpoint](./8877-metrics) can be polled for aggregated statistics (in a Prometheus-compatible format). This is our recommended method. -- $productName$ can push [Envoy statistics](./envoy-statsd) over the +- Emissary can push [Envoy statistics](./envoy-statsd) over the StatsD or DogStatsD protocol. -- $productName$ can push [RateLimiting +- Emissary can push [RateLimiting statistics](../environment) over the StatsD protocol. ## The Four Golden Signals diff --git a/content/en/docs/2.5/topics/running/statistics/envoy-statsd.md b/content/en/docs/2.5/topics/running/statistics/envoy-statsd.md index 42480a73..da38a3f7 100644 --- a/content/en/docs/2.5/topics/running/statistics/envoy-statsd.md +++ b/content/en/docs/2.5/topics/running/statistics/envoy-statsd.md @@ -1,20 +1,20 @@ -import Alert from '@material-ui/lab/Alert'; - -# Envoy statistics with StatsD +--- +title: Envoy statistics with StatsD +--- > For an overview of other options for gathering statistics on -> $productName$, see the [Statistics and Monitoring](../) overview. +> Emissary, see the [Statistics and Monitoring](../) overview. -At the core of $productName$ is [Envoy Proxy], which has built-in +At the core of Emissary is [Envoy Proxy], which has built-in support for exporting a multitude of statistics about its own operations to StatsD (or to the modified DogStatsD used by Datadog). [Envoy Proxy]: https://www.envoyproxy.io -If enabled, then $productName$ has Envoy expose this information via the +If enabled, then Emissary has Envoy expose this 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: +variable `STATSD_ENABLED=true` in Emissary's deployment YAML: ```diff spec: @@ -27,9 +27,9 @@ variable `STATSD_ENABLED=true` in $productName$'s deployment YAML: fieldRef: ``` -When this variable is set, $productName$ by default sends statistics to a +When this variable is set, Emissary 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 +port of the StatsD protocol). You may instead tell Emissary 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. @@ -66,7 +66,7 @@ This sets up Graphite access at `http://localhost:8080/`. ## Using Prometheus StatsD Exporter as the StatsD sink - $productName$ $version$ has an endpoint that has exposes statistics in + Emissary $version$ has an endpoint that has exposes statistics in a format that Prometheus understands natively. If you're using Prometheus, we recommend configuring Prometheus to talk to  the :8877/metrics endpoint  @@ -89,7 +89,7 @@ To finally get the statistics to Prometheus, you then configure a Prometheus target to read from `statsd-sink` on port 9102. You could instead also add the `statsd-sink` service and Prometheus StatsD -Exporter as a sidecar on the $productName$ pod. If you do this, make +Exporter as a sidecar on the Emissary pod. If you do this, make sure to set `STATSD_HOST=localhost` so that UDP packets are routed to the sidecar. @@ -99,7 +99,7 @@ It may be desirable to change how metrics produced by the `statsd-sink` are named, labeled and grouped when they finally make it to Prometheus. -For example, by default, each service that $productName$ serves will +For example, by default, each service that Emissary serves will create a new metric using its name. For the service called `usersvc` you will see this metric `envoy.cluster.usersvc_cluster.upstream_rq_total`. This may lead to @@ -107,7 +107,7 @@ problems if you are trying to create a single aggregate that is the sum of all similar metrics from different services. In this case, it is common to differentiate the metrics for an individual service with a `label`. This can be done by configuring a Prometheus StatsD -Exporter "mapping" (not to be confused with an [$productName$ +Exporter "mapping" (not to be confused with an [Emissary `Mapping`][Mappings]). See [Metric Mapping and Configuration] in the Prometheus StatsD Exporter documentation to learn how to modify its mappings. @@ -159,11 +159,11 @@ data: If you don't already have a Prometheus setup, the [Prometheus Operator] is a powerful way to create and deploy Prometheus instances. Use the following YAML to quickly configure the Prometheus -Operator with $productName$: +Operator with Emissary: - [`statsd-sink.yaml`] Creates the Prometheus Stats Exporter deployment and `statsd-sink` service that receives the statistics - from $productName$ and translates them to Prometheus metrics. It also + from Emissary and translates them to Prometheus metrics. It also creates a `ServiceMonitor` resource that tells the Prometheus Operator to configure Prometheus to fetch those metrics from the StatsD Exporter. @@ -176,8 +176,8 @@ Operator with $productName$: [`prometheus.yaml`]: https://github.com/emissary-ingress/emissary/blob/master/deployments/statsd-sink/prometheus/prometheus.yaml Make sure that the `ServiceMonitor` is in the same namespace as -$productName$. A walk-through of the basics of configuring the -Prometheus Operator with $productName$ is available +Emissary. A walk-through of the basics of configuring the +Prometheus Operator with Emissary is available [here](http://www.datawire.io/faster/ambassador-prometheus/). Ensure `STATSD_ENABLED` is set to `"true"` and apply the YAML with @@ -201,22 +201,22 @@ kubectl port-forward prometheus-prometheus-0 9090 ![Screenshot of a Grafana dashboard that displays just information from Envoy](../../../../images/grafana.png) If you're using Grafana, [Alex Gervais] has written a template -[$productName$ dashboard for Grafana] that works with either the +[Emissary dashboard for Grafana] that works with either the metrics exposed by the Prometheus StatsD Exporter, or by [the `:8877/metrics` endpoint]. [Alex Gervais]: https://twitter.com/alex_gervais -[$productName$ dashboard for Grafana]: https://grafana.com/dashboards/4698 +[Emissary dashboard for Grafana]: https://grafana.com/dashboards/4698 ## Using Datadog DogStatsD as the StatsD sink If you are a user of the [Datadog] monitoring system, pulling in the -Envoy statistics from $productName$ is very easy. +Envoy statistics from Emissary is very easy. [Datadog]: https://www.datadoghq.com/ Because the DogStatsD protocol is slightly different than the normal -StatsD protocol, in addition to setting $productName$'s +StatsD protocol, in addition to setting Emissary's `STATSD_ENABLED=true` environment variable, you also need to set the `DOGSTATSD=true` environment variable: @@ -245,10 +245,10 @@ kubectl apply -f statsd-sink/datadog/dd-statsd-sink.yaml ``` This sets up the `statsd-sink` service and a deployment of the -DogStatsD agent that forwards the $productName$ statistics to your +DogStatsD agent that forwards the Emissary statistics to your Datadog account. -Additionally, $productName$ supports setting the `dd.internal.entity_id` +Additionally, Emissary 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). diff --git a/content/en/docs/2.5/topics/running/statistics/index.md b/content/en/docs/2.5/topics/running/statistics/index.md deleted file mode 100644 index 04033002..00000000 --- a/content/en/docs/2.5/topics/running/statistics/index.md +++ /dev/null @@ -1,79 +0,0 @@ -# Statistics and monitoring - -$productName$ collects many statistics internally, and makes it easy to -direct this information to a statistics and monitoring tool of your -choice. As an example, for a given service `usersvc`, here are some -interesting statistics to investigate: - -- `envoy.cluster.usersvc.upstream_rq_total` is the total - number of requests that `usersvc` has received via $productName$. The rate of change of this value is one basic measure of - service utilization, i.e. requests per second. -- `envoy.cluster.usersvc.upstream_rq_2xx` is the total number - of requests to which `usersvc` responded with an HTTP response - indicating success. This value divided by the prior one, taken on - an rolling window basis, represents the recent success rate of the - service. There are corresponding `4xx` and `5xx` counters that can - help clarify the nature of unsuccessful requests. -- `envoy.cluster.usersvc.upstream_rq_time` is a StatsD timer - that tracks the latency in milliseconds of `usersvc` from $productName$'s perspective. StatsD timers include information about - means, standard deviations, and decile values. - -## Overriding Statistics Names - -The optional `stats_name` element of every CRD that references a service (`Mapping`, `TCPMapping`, -`AuthService`, `LogService`, `RateLimitService`, and `TracingService`) can override the name under which cluster statistics -are logged (`usersvc` above). If not set, the default is the `service` value, with non-alphanumeric characters replaced by -underscores: - -- `service: foo` will just use `foo` -- `service: foo:8080` will use `foo_8080` -- `service: http://foo:8080` will use `http___foo_8080` -- `service: foo.othernamespace` will use `foo_othernamespace` - -The last example is worth special mention: a resource in a different namespace than the one in which $productName$ is running will automatically be qualified with the namespace of the resource itself. So, for example, if $productName$ is running in the `ambassador` namespace, and this `Mapping` is present in the `default` namespace: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: default-mapping - namespace: default -spec: - prefix: /default/ - service: default-service -``` - -then the `service` will be qualified to `default-service.default`, so the `stats_name` will be `default_service_default` rather than simply `default_service`. To change this behavior, set `stats_name` explicitly. - -## Monitoring Statistics - -There are several ways to get different statistics out of $productName$: - -- [The `:8877/metrics` endpoint](./8877-metrics) can be polled for - aggregated statistics (in a Prometheus-compatible format). This is - our recommended method. -- $productName$ can push [Envoy statistics](./envoy-statsd) over the - StatsD or DogStatsD protocol. -- $productName$ can push [RateLimiting - statistics](../environment) over the StatsD protocol. - -## The Four Golden Signals - -The [Four Golden Signals](https://sre.google/sre-book/monitoring-distributed-systems/) are four generally-accepted metrics -that are important to monitor for good information about service health: - -### Latency - -The time it takes to service a request. `cluster.$name.upstream_rq_time` is a histogram of time taken by individual requests, which can be an effective latency metric. - -### Traffic - -The amount of demand being placed on your system. `cluster.$name.upstream_rq_active` is a gauge that shows the number of active outstanding requests, which can be a good proxy for traffic. - -### Errors - -The number of failing requests. Some errors (e.g. a request succeeds, but gives the wrong answer) can only be detected by application-specific monitoring; however, many errors can be spotted simply by looking at the HTTP status code of requests. `cluster.$name.upstream_rq_5xx` is a counter of HTTP `5xx` responses, so monitoring it over time can show error rates. (Likewise, `cluster.$name.upstream_rq_4xx` exists.) - -### Saturation - -The hardest metric to measure, saturation describes how much of the total capability of the system to respond to requests is being used. Fully measuring saturation often requires application-specific monitoring, but looking at the 99th percentile of latency over a short window - perhaps a a minute - can often give an early indication of saturation problems. diff --git a/content/en/docs/2.5/topics/running/tls/index.md b/content/en/docs/2.5/topics/running/tls/_index.md similarity index 87% rename from content/en/docs/2.5/topics/running/tls/index.md rename to content/en/docs/2.5/topics/running/tls/_index.md index 850fb5c0..6874d3a7 100644 --- a/content/en/docs/2.5/topics/running/tls/index.md +++ b/content/en/docs/2.5/topics/running/tls/_index.md @@ -1,19 +1,20 @@ -import Alert from '@material-ui/lab/Alert'; - -# Transport Layer Security (TLS) +--- +title: Transport Layer Security (TLS) +weight: -10 +--- -$productName$'s robust TLS support exposes configuration options +Emissary's robust TLS support exposes configuration options for many different TLS use cases, using the [`Host`](#host) and [`TLSContext`](#host-and-tlscontext) resources in concert. ## Certificates and Secrets Properly-functioning TLS requires the use of [TLS certificates] to prove that the -various systems communicating are who they say they are. At minimum, $productName$ +various systems communicating are who they say they are. At minimum, Emissary must have a server certificate that identifies it to clients; when [mTLS] or [client certificate authentication] are in use, additional certificates are needed. -You supply certificates to $productName$ in Kubernetes [TLS Secrets]. These Secrets +You supply certificates to Emissary in Kubernetes [TLS Secrets]. These Secrets _must_ contain valid X.509 certificates with valid PKCS1, PKCS8, or Elliptic Curve private keys. If a Secret does not contain a valid certificate, an error message will be logged, for example: @@ -24,7 +25,7 @@ tls-broken-cert.default.1 2 errors:; 1. K8sSecret secret tls-broken-cert.defaul If you set the `AMBASSADOR_FORCE_SECRET_VALIDATION` environment variable, the invalid Secret will be rejected, and a `Host` or `TLSContext` resource attempting to use an invalid -certificate will be disabled entirely. **Note** that in $productName$ $version$, this +certificate will be disabled entirely. **Note** that in Emissary $version$, this includes disabling cleartext communication for such a `Host`. [TLS Certificates]: https://protonmail.com/blog/tls-ssl-certificate/ @@ -34,15 +35,15 @@ includes disabling cleartext communication for such a `Host`. ## `Host` -A `Host` represents a domain in $productName$ and defines how the domain manages TLS. For more information on the Host resource, see [The Host CRD reference documentation](../host-crd). +A `Host` represents a domain in Emissary and defines how the domain manages TLS. For more information on the Host resource, see [The Host CRD reference documentation](../host-crd). -**If no `Host`s are present**, $productName$ synthesizes a `Host` that +**If no `Host`s are present**, Emissary synthesizes a `Host` that allows only cleartext routing. You will need to explictly define `Host`s to enable TLS termination. The examples below do not define a requestPolicy; however, most real-world - usage of $productName$ will require defining the requestPolicy.
+ usage of Emissary will require defining the requestPolicy.

For more information, please refer to the Host documentation. @@ -53,7 +54,7 @@ The `Host` can read a certificate from a Kubernetes Secret and use that certific to terminate TLS on a domain. The following example shows the certificate contained in the Kubernetes Secret named -`host-secret` configured to have $productName$ terminate TLS on the `host.example.com` +`host-secret` configured to have Emissary terminate TLS on the `host.example.com` domain: ```yaml @@ -94,7 +95,7 @@ spec: The Kubernetes Secret named by 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 + certificate, Emissary will reject the Secret and completely disable the `Host`; see [**Certificates and Secrets**](#certificates-and-secrets) above. @@ -124,7 +125,7 @@ spec: The Kubernetes Secret named by 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 + certificate, Emissary will reject the Secret and completely disable the `Host`; see [**Certificates and Secrets**](#certificates-and-secrets) above. @@ -200,7 +201,7 @@ spec: The `Host` and the `TLSContext` must name the same Kubernetes Secret; if not, - $productName$ will disable TLS for the `Host`. + Emissary will disable TLS for the `Host`. @@ -208,7 +209,7 @@ spec: The Kubernetes Secret named by 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 + certificate, Emissary will reject the Secret and completely disable the `Host`; see [**Certificates and Secrets**](#certificates-and-secrets) above. @@ -226,7 +227,7 @@ See [`TLSContext`](#tlscontext) below to read more on the description of these f This implicit TLSContext linkage is deprecated and will be removed - in a future version of $productName$; it is not recommended for new + in a future version of Emissary; it is not recommended for new configurations. Any other TLS configuration in the Host will override this implict TLSContext link. @@ -258,7 +259,7 @@ spec: The `Host` and the `TLSContext` must name the same Kubernetes Secret; if not, - $productName$ will disable TLS for the `Host`. + Emissary will disable TLS for the `Host`. @@ -266,7 +267,7 @@ spec: The Kubernetes Secret named by 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 + certificate, Emissary will reject the Secret and completely disable the `Host`; see [**Certificates and Secrets**](#certificates-and-secrets) above. @@ -282,7 +283,7 @@ Full reference for all options available to the `TLSContext` can be found [below ## TLSContext -The `TLSContext` is used to configure advanced TLS options in $productName$. +The `TLSContext` is used to configure advanced TLS options in Emissary. Remember, a `TLSContext` must always be paired with a `Host`. A full schema of the `TLSContext` can be found below with descriptions of the @@ -308,7 +309,7 @@ spec: # sni: None # 'secret' defines a Kubernetes Secret that contains the TLS certificate we - # use for origination or termination. If not specified, $productName$ will look + # use for origination or termination. If not specified, Emissary will look # at the value of cert_chain_file and private_key_file. # type: string # @@ -320,7 +321,7 @@ spec: # # ca_secret: None - # Tells $productName$ whether to interpret a "." in the secret name as a "." or + # Tells Emissary whether to interpret a "." in the secret name as a "." or # a namespace identifier. # type: boolean # @@ -347,7 +348,7 @@ spec: # v1.2, or v1.3. It defaults to v1.3. # max_tls_version: v1.3 - # Tells $productName$ to load TLS certificates from a file in its container. + # Tells Emissary to load TLS certificates from a file in its container. # type: string # # cert_chain_file: None @@ -359,7 +360,7 @@ spec: `secret` and (if used) `ca_secret` must specify Kubernetes Secrets containing valid TLS certificates. If `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and either Secret contains - an invalid certificate, $productName$ will reject the Secret, which will also completely + an invalid certificate, Emissary will reject the Secret, which will also completely disable any `Host` using the `TLSContext`; see [**Certificates and Secrets**](#certificates-and-secrets) above. @@ -393,12 +394,12 @@ If you leave off http/1.1, only HTTP2 connections will be supported. ### TLS parameters The `min_tls_version` setting configures the minimum TLS protocol version that -$productName$ will use to establish a secure connection. When a client +Emissary will use to establish a secure connection. When a client using a lower version attempts to connect to the server, the handshake will result in the following error: `tls: protocol version not supported`. The `max_tls_version` setting configures the maximum TLS protocol version that -$productName$ will use to establish a secure connection. When a client +Emissary will use to establish a secure connection. When a client using a higher version attempts to connect to the server, the handshake will result in the following error: `tls: server selected unsupported protocol version`. @@ -456,7 +457,7 @@ spec: The `crl_secret` field allows you to reference a Kubernetes Secret that contains a certificate revocation list. -If specified, $productName$ will verify that the presented peer certificate has not been revoked by this CRL even if they are otherwise valid. This provides a way to reject certificates before they expire or if they become compromised. +If specified, Emissary will verify that the presented peer certificate has not been revoked by this CRL even if they are otherwise valid. This provides a way to reject certificates before they expire or if they become compromised. The `crl_secret` field takes a PEM-formatted [Certificate Revocation List](https://en.wikipedia.org/wiki/Certificate_revocation_list) in a `crl.pem` entry. Note that if a CRL is provided for any certificate authority in a trust chain, a CRL must be provided for all certificate authorities in that chain. Failure to do so will result in verification failure for both revoked and unrevoked certificates from that chain. diff --git a/content/en/docs/2.5/topics/running/tls/cleartext-redirection.md b/content/en/docs/2.5/topics/running/tls/cleartext-redirection.md index 7144b1a3..d3fd6e38 100644 --- a/content/en/docs/2.5/topics/running/tls/cleartext-redirection.md +++ b/content/en/docs/2.5/topics/running/tls/cleartext-redirection.md @@ -1,9 +1,9 @@ -import Alert from '@material-ui/lab/Alert'; - -# Cleartext support +--- +title: Cleartext support +--- While most modern web applications choose to encrypt all traffic, there remain -cases where supporting cleartext communications is important. $productName$ supports +cases where supporting cleartext communications is important. Emissary supports both forcing [automatic redirection to HTTPS](#http-https-redirection) and [serving cleartext](#cleartext-routing) traffic on a `Host`. @@ -11,7 +11,7 @@ both forcing [automatic redirection to HTTPS](#http-https-redirection) and The 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. + treatment of handling cleartext and HTTPS, see Configuring Emissary Communications. ## Cleartext Routing @@ -33,7 +33,7 @@ This allows routing for either HTTP and HTTPS, or _only_ HTTP, depending on `tls The 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. + treatment of handling cleartext and HTTPS, see Configuring Emissary Communications. ## HTTP->HTTPS redirection @@ -42,7 +42,7 @@ Most websites that force HTTPS will also automatically redirect any requests that come into it over HTTP: ``` -Client $productName$ +Client Emissary | | | http:///api | | --------------------------> | @@ -55,7 +55,7 @@ Client $productName$ | | ``` -In $productName$, this is configured by setting the `insecure.action` in a `Host` to `Redirect`. +In Emissary, this is configured by setting the `insecure.action` in a `Host` to `Redirect`. ```yaml requestPolicy: @@ -63,7 +63,7 @@ requestPolicy: action: Redirect ``` -$productName$ determines which requests are secure and which are insecure using the +Emissary determines which requests are secure and which are insecure using the `securityModel` of the [`Listener`] that accepts the request. [`Listener`]: ../../listener @@ -72,5 +72,5 @@ $productName$ determines which requests are secure and which are insecure using The 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. + treatment of handling cleartext and HTTPS, see Configuring Emissary Communications. diff --git a/content/en/docs/2.5/topics/running/tls/mtls.md b/content/en/docs/2.5/topics/running/tls/mtls.md index 1b039cf8..f79769c8 100644 --- a/content/en/docs/2.5/topics/running/tls/mtls.md +++ b/content/en/docs/2.5/topics/running/tls/mtls.md @@ -1,6 +1,6 @@ -import Alert from '@material-ui/lab/Alert'; - -# Mutual TLS (mTLS) +--- +title: Mutual TLS (mTLS) +--- Many organizations have security concerns that require all network traffic throughout their cluster be encrypted. With traditional architectures, @@ -13,15 +13,15 @@ provide a certificate and key that the other trusts before establishing a connection. This action of both the client and server providing and validating certificates is referred to as mutual TLS. -## mTLS with $productName$ +## mTLS with Emissary -Since $productName$ is a reverse proxy acting as the entry point to your cluster, -$productName$ is acting as the client as it proxies requests to services upstream. +Since Emissary is a reverse proxy acting as the entry point to your cluster, +Emissary is acting as the client as it proxies requests to services upstream. -It is trivial to configure $productName$ to simply originate TLS connections as +It is trivial to configure Emissary to simply originate TLS connections as the client to upstream services by setting `service: https://{{UPSTREAM_SERVICE}}` in the `Mapping` configuration. -However, in order to do mTLS with services upstream, $productName$ must also +However, in order to do mTLS with services upstream, Emissary must also have certificates to authenticate itself with the service. To do this, we can use the `TLSContext` object to get certificates from a @@ -46,12 +46,12 @@ requests upstream. The Kubernetes Secret must contain a valid TLS certificate. If the environment variable `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and the Secret contains an invalid - certificate, $productName$ will reject the Secret and completely disable the `Host`; + certificate, Emissary will reject the Secret and completely disable the `Host`; see [**Certificates and Secrets**](../#certificates-and-secrets) in the TLS overview. -After loading the certificates, we can tell $productName$ when to use them by +After loading the certificates, we can tell Emissary when to use them by setting the `tls` parameter in a `Mapping`: ```yaml @@ -66,7 +66,7 @@ spec: tls: upstream-context ``` -Now, when $productName$ proxies a request to `upstream-service`, it will provide +Now, when Emissary proxies a request to `upstream-service`, it will provide the certificates in the `upstream-certs` secret for authentication when encrypting traffic. @@ -79,9 +79,9 @@ very big challenge. For this reason, many organizations rely on a service mesh for their service-to-service authentication and encryption. -$productName$ integrates with multiple service meshes and makes it easy to +Emissary integrates with multiple service meshes and makes it easy to configure mTLS to upstream services for all of them. Click the links below to -see how to configure $productName$ to do mTLS with any of these service meshes: +see how to configure Emissary to do mTLS with any of these service meshes: - [Consul Connect](../../../../howtos/consul/) diff --git a/content/en/docs/2.5/topics/running/tls/origination.md b/content/en/docs/2.5/topics/running/tls/origination.md index b15dd5f8..1cfa4849 100644 --- a/content/en/docs/2.5/topics/running/tls/origination.md +++ b/content/en/docs/2.5/topics/running/tls/origination.md @@ -1,12 +1,12 @@ -import Alert from '@material-ui/lab/Alert'; - -# TLS origination +--- +title: TLS Origination +--- -Sometimes you may want traffic from $productName$ to your services to be encrypted. For the cases where terminating TLS at the ingress is not enough, $productName$ can be configured to originate TLS connections to your upstream services. +Sometimes you may want traffic from Emissary to your services to be encrypted. For the cases where terminating TLS at the ingress is not enough, Emissary can be configured to originate TLS connections to your upstream services. ## Basic configuration -Telling $productName$ to talk to your services over HTTPS is easily configured in the `Mapping` definition by setting `https://` in the `service` field. +Telling Emissary to talk to your services over HTTPS is easily configured in the `Mapping` definition by setting `https://` in the `service` field. ```yaml --- @@ -23,7 +23,7 @@ spec: ## Advanced configuration using a `TLSContext` If your upstream services require more than basic HTTPS support (for example, providing a client certificate or -setting the minimum TLS version support) you must create a `TLSContext` for $productName$ to use when +setting the minimum TLS version support) you must create a `TLSContext` for Emissary to use when originating TLS. For example: ```yaml @@ -42,12 +42,12 @@ spec: The Kubernetes Secret named by `secret` must contain a valid TLS certificate. If the environment variable `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and the Secret contains - an invalid certificate, $productName$ will reject the `TLSContext` and prevent its use; + an invalid certificate, Emissary will reject the `TLSContext` and prevent its use; see [**Certificates and Secrets**](../#certificates-and-secrets) in the TLS overview. -Configure $productName$ to use this `TLSContext` for connections to upstream services by setting the `tls` attribute of a `Mapping`: +Configure Emissary to use this `TLSContext` for connections to upstream services by setting the `tls` attribute of a `Mapping`: ```yaml --- @@ -62,13 +62,13 @@ spec: tls: tls-context ``` -The `example-service` service must now support TLS v1.3 for $productName$ to connect. +The `example-service` service must now support TLS v1.3 for Emissary to connect. The Kubernetes Secret named by `secret` must contain a valid TLS certificate. If the environment variable `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and the Secret contains - an invalid certificate, $productName$ will reject the `TLSContext` and prevent its use; + an invalid certificate, Emissary will reject the `TLSContext` and prevent its use; see [**Certificates and Secrets**](../#certificates-and-secrets) in the TLS overview. diff --git a/content/en/docs/2.5/topics/running/tls/sni.md b/content/en/docs/2.5/topics/running/tls/sni.md index 92e4992f..f32a0c6d 100644 --- a/content/en/docs/2.5/topics/running/tls/sni.md +++ b/content/en/docs/2.5/topics/running/tls/sni.md @@ -1,18 +1,20 @@ -# Server Name Indication (SNI) +--- +title: Server Name Indication (SNI) +--- -$productName$ supports serving multiple `Host`s behind a single IP address, each +Emissary supports serving multiple `Host`s behind a single IP address, each with their own certificate. This is as easy to do as creating a `Host` for each domain or subdomain you -want $productName$ to serve, getting a certificate for each, and telling -$productName$ which `Host` the route should be created for. +want Emissary to serve, getting a certificate for each, and telling +Emissary which `Host` the route should be created for. The example below configures two `Host`s and assigns routes to them. ## Configuring a `Host` The `Host` resources lets you separate configuration for each distinct domain -and subdomain you plan on serving behind $productName$. +and subdomain you plan on serving behind Emissary. Let's start by creating a simple `Host` and providing our own certificate in the `host-cert` secret. @@ -30,7 +32,7 @@ spec: ``` Now let's create a second `Host` for a different domain we want to serve behind -$productName$. This second `Host` uses $AESproductName$'s automatic TLS +Emissary. This second `Host` uses Ambassador Edge Stack's automatic TLS to get a certificate from Let's Encrypt. ```yaml @@ -53,7 +55,7 @@ We now have two `Host`s with two different certificates. ## Configuring routes -Now that we have two domains behind $productName$, we can create routes for either +Now that we have two domains behind Emissary, we can create routes for either or both of them. We do this by setting the `hostname` attribute of a `Mapping` to the domain the diff --git a/content/en/docs/3.0/topics/using/index.md b/content/en/docs/2.5/topics/using/_index.md similarity index 77% rename from content/en/docs/3.0/topics/using/index.md rename to content/en/docs/2.5/topics/using/_index.md index a996249e..ed73199b 100644 --- a/content/en/docs/3.0/topics/using/index.md +++ b/content/en/docs/2.5/topics/using/_index.md @@ -1,6 +1,9 @@ -# Using $productName$ +--- +title: "Using" +description: "This section of the documentation provides instructions on using Emissary" +--- -Application development teams use $productName$ to manage edge policies associated with a specific service. This section of the documentation covers core $productName$ elements that are typically used by the application development team. +Application development teams use Emissary to manage edge policies associated with a specific service. This section of the documentation covers core Emissary elements that are typically used by the application development team. * [Introduction to Mappings](intro-mappings) The `Mapping` resource is the core resource used by every application development team. * Mapping Configuration: diff --git a/content/en/docs/2.5/topics/using/authservice.md b/content/en/docs/2.5/topics/using/authservice.md index cfe3598b..b0a733f0 100644 --- a/content/en/docs/2.5/topics/using/authservice.md +++ b/content/en/docs/2.5/topics/using/authservice.md @@ -1,10 +1,12 @@ -# AuthService settings +--- +title: AuthService settings +--- A Mapping can pass these settings along to an [AuthService](../../running/services/auth-service). This is helpful to allow these specific configurations to apply only to certain Mappings and not globally. ## Bypass authentication -An AuthService can be disabled for a specific Mapping with the `bypass_auth` attribute. This will tell $productName$ to allow all requests for that Mapping through without interacting with the external auth service. This could be helpful, for example, for a public API. +An AuthService can be disabled for a specific Mapping with the `bypass_auth` attribute. This will tell Emissary to allow all requests for that Mapping through without interacting with the external auth service. This could be helpful, for example, for a public API. ```yaml bypass_auth: true diff --git a/content/en/docs/2.5/topics/using/rate-limits/index.md b/content/en/docs/2.5/topics/using/basic-rate-limiting.md similarity index 83% rename from content/en/docs/2.5/topics/using/rate-limits/index.md rename to content/en/docs/2.5/topics/using/basic-rate-limiting.md index 1230c34a..6afd3bbc 100644 --- a/content/en/docs/2.5/topics/using/rate-limits/index.md +++ b/content/en/docs/2.5/topics/using/basic-rate-limiting.md @@ -1,13 +1,13 @@ -import Alert from '@material-ui/lab/Alert'; +--- +title: Basic rate limiting +--- -# Basic rate limiting +Rate limiting in Emissary is composed of two parts: -Rate limiting in $productName$ is composed of two parts: - -* The [`RateLimitService`](../../running/services/rate-limit-service) resource tells $productName$ what external service +* The [`RateLimitService`](../../running/services/rate-limit-service) resource tells Emissary what external service to use for rate limiting. - If $productName$ cannot contact the rate limit service, it will allow the request to be processed as if there were no rate limit service configuration. + If Emissary cannot contact the rate limit service, it will allow the request to be processed as if there were no rate limit service configuration. * _Labels_ that get attached to requests. A label is basic metadata that is used by the `RateLimitService` to decide which limits to apply to @@ -34,7 +34,7 @@ labels: - ... ``` -The names of domains and groups are not interpreted by $productName$ in any way: +The names of domains and groups are not interpreted by Emissary in any way: they are solely there to help configuration authors remember the different groupings. Note that **at present, rate limiting supports just one domain**: the name of the domain must be configured in the [`RateLimitService`](../../running/services/rate-limit-service). @@ -71,7 +71,7 @@ There are two ways of setting labels on a request: ``` 2. You can set global labels in the [`ambassador` `Module`](../../running/ambassador). - These labels will apply to _every_ request that goes through $productName$. + These labels will apply to _every_ request that goes through Emissary. ```yaml --- @@ -103,9 +103,9 @@ group is a list rather than a map: - the order of labels matters. > Note: The terminology used by the Envoy documentation differs from -> the terminology used by $productName$: +> the terminology used by Emissary: > -> | $productName$ | Envoy | +> | Emissary | Envoy | > |-----------------|-------------------| > | label group | descriptor | > | label | descriptor entry | @@ -113,14 +113,14 @@ group is a list rather than a map: The `Mapping`s' listing of the groups of specifiers have names for the groups; the group names are useful for humans dealing with the YAML, -but are ignored by $productName$, all $productName$ cares about are the +but are ignored by Emissary, all Emissary cares about are the *contents* of the groupings of label specifiers. -There are 5 types of label specifiers in $productName$: +There are 5 types of label specifiers in Emissary: 1. `source_cluster` @@ -159,7 +159,7 @@ There are 5 types of label specifiers in $productName$: Sets the label `remote_address=«IP address of the client»"`. The IP address of the client will be taken from the `X-Forwarded-For` header, to correctly manage - situations with L7 proxies. This requires that $productName$ be correctly + situations with L7 proxies. This requires that Emissary be correctly [configured to communicate](../../../howtos/configure-communications). The syntax of this label currently _requires_ `remote_address: {}`. @@ -191,10 +191,10 @@ There are 5 types of label specifiers in $productName$: This is determined by your `RateLimitService` implementation. See the [Basic Rate Limiting tutorial](../../../howtos/rate-limiting-tutorial) for an -example `RateLimitService` implementation for $productName$. +example `RateLimitService` implementation for Emissary. If you'd rather not write your own `RateLimitService` implementation, -$AESproductName$ provides a `RateLimitService` implementation that is +Ambassador Edge Stack provides a `RateLimitService` implementation that is configured by a `RateLimit` custom resource. See the -[$AESproductName$ RateLimit Reference](/docs/edge-stack/latest/topics/using/rate-limits/rate-limits/) +[Ambassador Edge Stack RateLimit Reference](/docs/edge-stack/latest/topics/using/rate-limits/rate-limits/) for more information. diff --git a/content/en/docs/2.5/topics/using/canary.md b/content/en/docs/2.5/topics/using/canary.md index f99de1a3..b8b44d7f 100644 --- a/content/en/docs/2.5/topics/using/canary.md +++ b/content/en/docs/2.5/topics/using/canary.md @@ -1,4 +1,6 @@ -# Canary releases +--- +title: Canary releases +--- Canary releasing is a deployment pattern where a small percentage of traffic is diverted to an early ("canary") release of a particular service. This technique lets you test a release on a small subset of users, mitigating the impact of any given bug. Canary releasing also allows you to quickly roll back to a known good version in the event of an unexpected error. Detailed monitoring of core service metrics is an essential part of canary releasing, as monitoring enables the rapid detection of problems in the canary release. @@ -6,15 +8,15 @@ Canary releasing is a deployment pattern where a small percentage of traffic is Kubernetes supports a basic canary release workflow using its core objects. In this workflow, a service owner can create a Kubernetes [service](https://kubernetes.io/docs/concepts/services-networking/service/). This service can then be pointed to multiple [deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/). Each deployment can be a different version. By specifying the number of `replicas` in a given deployment, you can control how much traffic goes between different versions. For example, you could set `replicas: 3` for `v1`, and `replicas: 1` for `v2`, to ensure that 25% of traffic goes to `v2`. This approach works but is fairly coarse-grained unless you have lots of replicas. Moreover, auto-scaling doesn't work well with this strategy. -## Canary releases in $productName$ +## Canary releases in Emissary -$productName$ supports fine-grained canary releases. $productName$ uses a weighted round-robin scheme to route traffic between multiple services. Full metrics are collected for all services, making it easy to compare the relative performance of the canary and production. +Emissary supports fine-grained canary releases. Emissary uses a weighted round-robin scheme to route traffic between multiple services. Full metrics are collected for all services, making it easy to compare the relative performance of the canary and production. ### The weight attribute -The `weight` attribute specifies how much traffic for a given resource will be routed using a given mapping. Its value is an integer percentage between 0 and 100. $productName$ will balance weights to make sure that, for every resource, the mappings for that resource will have weights adding to 100%. (In the simplest case, a single mapping is guaranteed to receive 100% of the traffic no matter whether it's assigned a `weight` or not.) +The `weight` attribute specifies how much traffic for a given resource will be routed using a given mapping. Its value is an integer percentage between 0 and 100. Emissary will balance weights to make sure that, for every resource, the mappings for that resource will have weights adding to 100%. (In the simplest case, a single mapping is guaranteed to receive 100% of the traffic no matter whether it's assigned a `weight` or not.) -Specifying a weight only makes sense if you have multiple mappings for the same resource, and typically you would _not_ assign a weight to the "default" mapping (the mapping expected to handle most traffic): letting $productName$ assign that mapping all the traffic not otherwise spoken for tends to make life easier when updating weights. +Specifying a weight only makes sense if you have multiple mappings for the same resource, and typically you would _not_ assign a weight to the "default" mapping (the mapping expected to handle most traffic): letting Emissary assign that mapping all the traffic not otherwise spoken for tends to make life easier when updating weights. Here's an example, which might appear during a canary deployment: @@ -38,4 +40,4 @@ spec: weight: 10 ``` -In this case, the quote-backend2 will receive 10% of the requests for `/backend/`, and $productName$ will assign the remaining 90% to the quote-backend. +In this case, the quote-backend2 will receive 10% of the requests for `/backend/`, and Emissary will assign the remaining 90% to the quote-backend. diff --git a/content/en/docs/2.5/topics/using/circuit-breakers.md b/content/en/docs/2.5/topics/using/circuit-breakers.md index 97b40f57..275e00a2 100644 --- a/content/en/docs/2.5/topics/using/circuit-breakers.md +++ b/content/en/docs/2.5/topics/using/circuit-breakers.md @@ -1,11 +1,13 @@ -# Circuit breakers +--- +title: Circuit breakers +--- -Circuit breakers are a powerful technique to improve resilience. By preventing additional connections or requests to an overloaded service, circuit breakers limit the ["blast radius"](https://www.ibm.com/garage/method/practices/manage/practice_limited_blast_radius/) of an overloaded service. By design, $productName$ circuit breakers are distributed, i.e., different $productName$ instances do not coordinate circuit breaker information. +Circuit breakers are a powerful technique to improve resilience. By preventing additional connections or requests to an overloaded service, circuit breakers limit the ["blast radius"](https://www.ibm.com/garage/method/practices/manage/practice_limited_blast_radius/) of an overloaded service. By design, Emissary circuit breakers are distributed, i.e., different Emissary instances do not coordinate circuit breaker information. ## Circuit breaker configuration A default circuit breaking configuration can be set for all -$productName$ resources in the [`ambassador +Emissary resources in the [`ambassador Module`](../../running/ambassador), or set to a different value on a per-resource basis for [`Mappings`](../mappings), [`TCPMappings`](../tcpmappings/), and @@ -25,13 +27,13 @@ circuit_breakers: |Key|Default value|Description| |---|---|---| |`priority`|`default`|Specifies the priority to which the circuit breaker settings apply to; it can be set to either `default` or `high`.| -|`max_connections`|`1024`|Specifies the maximum number of connections that $productName$ will make to the services. In practice, this is more applicable to HTTP/1.1 than HTTP/2.| +|`max_connections`|`1024`|Specifies the maximum number of connections that Emissary will make to the services. In practice, this is more applicable to HTTP/1.1 than HTTP/2.| |`max_pending_requests`|`1024`|Specifies the maximum number of requests that will be queued while waiting for a connection. In practice, this is more applicable to HTTP/1.1 than HTTP/2.| |`max_requests`|`1024`|Specifies the maximum number of parallel outstanding requests to an upstream service. In practice, this is more applicable to HTTP/2 than HTTP/1.1.| |`max_retries`|`3`|Specifies the maximum number of parallel retries allowed to an upstream service.| The `max_*` fields can be reduced to shrink the "blast radius," or -increased to enable $productName$ to handle a larger number of +increased to enable Emissary to handle a larger number of concurrent requests. ## Examples diff --git a/content/en/docs/2.5/topics/using/cors.md b/content/en/docs/2.5/topics/using/cors.md index 315e4694..1e4c0743 100644 --- a/content/en/docs/2.5/topics/using/cors.md +++ b/content/en/docs/2.5/topics/using/cors.md @@ -1,14 +1,16 @@ -# Cross-Origin Resource Sharing (CORS) +--- +title: Cross-Origin Resource Sharing (CORS) +--- Cross-Origin resource sharing lets users request resources (e.g., images, fonts, videos) from domains outside the original domain. -CORS configuration can be set for all $productName$ mappings in the [`ambassador Module`](../../running/ambassador), or set per [`Mapping`](../mappings). +CORS configuration can be set for all Emissary mappings in the [`ambassador Module`](../../running/ambassador), or set per [`Mapping`](../mappings). -When the CORS attribute is set at either the `Mapping` or `Module` level, $productName$ will intercept the pre-flight `OPTIONS` request and respond with the appropriate CORS headers. This means you will not need to implement any logic in your upstreams to handle these CORS `OPTIONS` requests. +When the CORS attribute is set at either the `Mapping` or `Module` level, Emissary will intercept the pre-flight `OPTIONS` request and respond with the appropriate CORS headers. This means you will not need to implement any logic in your upstreams to handle these CORS `OPTIONS` requests. The flow of the request will look similar to the following: ``` -Client $productName$ Upstream +Client Emissary Upstream | OPTIONS | | | —————————————————> | | | CORS_RESP | | @@ -133,12 +135,12 @@ class SecurityConfig extends WebSecurityConfigurerAdapter { } ``` -This is okay since CORS is being handled by $productName$ after authentication. +This is okay since CORS is being handled by Emissary after authentication. The flow of this request will look similar to the following: ``` -Client $productName$ Auth Upstream +Client Emissary Auth Upstream | OPTIONS | | | | —————————————————> | ————————————> | | | | CORS_ACCEPT_* | | diff --git a/content/en/docs/2.5/topics/using/defaults.md b/content/en/docs/2.5/topics/using/defaults.md index 673a08be..4157bc71 100644 --- a/content/en/docs/2.5/topics/using/defaults.md +++ b/content/en/docs/2.5/topics/using/defaults.md @@ -1,6 +1,6 @@ -# Using `ambassador` `Module` defaults - -## The defaults element +--- +title: ambassador module defaults +--- If present, the `ambassador Module` can define a set of defaults that will automatically be applied to certain resources: diff --git a/content/en/docs/2.5/topics/using/gateway-api.md b/content/en/docs/2.5/topics/using/gateway-api.md index 5e92cd0d..2ee72327 100644 --- a/content/en/docs/2.5/topics/using/gateway-api.md +++ b/content/en/docs/2.5/topics/using/gateway-api.md @@ -1,8 +1,8 @@ -# Gateway API +--- +title: Gateway API +--- -## Using the Gateway API - -$productName$ now supports a limited subset of the new `v1alpha1` [Gateway API](https://gateway-api.sigs.k8s.io/). +Emissary now supports a limited subset of the new `v1alpha1` [Gateway API](https://gateway-api.sigs.k8s.io/). Note that the Gateway API is not supported when `AMBASSADOR_LEGACY_MODE` is set. Support is currently limited to the following fields, however this will expand in future releases: diff --git a/content/en/docs/2.5/topics/using/headers/_index.md b/content/en/docs/2.5/topics/using/headers/_index.md new file mode 100644 index 00000000..57127082 --- /dev/null +++ b/content/en/docs/2.5/topics/using/headers/_index.md @@ -0,0 +1,4 @@ +--- +title: Headers +weight: -10 +--- diff --git a/content/en/docs/2.5/topics/using/headers/add_request_headers.md b/content/en/docs/2.5/topics/using/headers/add_request_headers.md index c6ad4956..a9911079 100644 --- a/content/en/docs/2.5/topics/using/headers/add_request_headers.md +++ b/content/en/docs/2.5/topics/using/headers/add_request_headers.md @@ -1,6 +1,8 @@ -# Add request headers +--- +title: Add request headers +--- -$productName$ can add a dictionary of HTTP headers that can be added to each request that is passed to a service. +Emissary can add a dictionary of HTTP headers that can be added to each request that is passed to a service. ## The `add_request_headers` attribute diff --git a/content/en/docs/2.5/topics/using/headers/add_response_headers.md b/content/en/docs/2.5/topics/using/headers/add_response_headers.md index 236ace61..9bf02050 100644 --- a/content/en/docs/2.5/topics/using/headers/add_response_headers.md +++ b/content/en/docs/2.5/topics/using/headers/add_response_headers.md @@ -1,6 +1,8 @@ -# Add response headers +--- +title: Add response headers +--- -$productName$ can add a dictionary of HTTP headers that can be added to each response that is returned to the client. +Emissary can add a dictionary of HTTP headers that can be added to each response that is returned to the client. ## The `add_response_headers` attribute diff --git a/content/en/docs/2.5/topics/using/headers/headers.md b/content/en/docs/2.5/topics/using/headers/headers.md index 126653b0..1c0a5489 100644 --- a/content/en/docs/2.5/topics/using/headers/headers.md +++ b/content/en/docs/2.5/topics/using/headers/headers.md @@ -1,12 +1,12 @@ -import Alert from '@material-ui/lab/Alert'; - -# Header-based routing +--- +title: Header-based routing +--- -$productName$ can route to target services based on HTTP headers with the `headers` and `regex_headers` specifications. Multiple mappings with different annotations can be applied to construct more complex routing rules. +Emissary can route to target services based on HTTP headers with the `headers` and `regex_headers` specifications. Multiple mappings with different annotations can be applied to construct more complex routing rules. ## The `headers` annotation -The `headers` attribute is a dictionary of `header`: `value` pairs. $productName$ will only allow requests that match the specified `header`: `value` pairs to reach the target service. +The `headers` attribute is a dictionary of `header`: `value` pairs. Emissary will only allow requests that match the specified `header`: `value` pairs to reach the target service. ### Example diff --git a/content/en/docs/2.5/topics/using/headers/host.md b/content/en/docs/2.5/topics/using/headers/host.md index 5a8dd02c..ba07fea7 100644 --- a/content/en/docs/2.5/topics/using/headers/host.md +++ b/content/en/docs/2.5/topics/using/headers/host.md @@ -1,6 +1,8 @@ -# Host headers +--- +title: Host headers +--- -$productName$ supports several different methods for managing the HTTP `Host` header. +Emissary supports several different methods for managing the HTTP `Host` header. ## Using `host` and `host_regex` @@ -48,9 +50,9 @@ Note that enclosing regular expressions in quotes can be important to prevent ba ## Using `host_rewrite` -By default, the `Host` header is not altered when talking to the service -- whatever `Host` header the client gave to $productName$ will be presented to the service. For many microservices, this will be fine, but if you use $productName$ to route to services that use the `Host` header for routing, it's likely to fail (legacy monoliths are particularly susceptible to this, as well as external services). You can use `host_rewrite` to force the `Host` header to whatever value that such target services need. +By default, the `Host` header is not altered when talking to the service -- whatever `Host` header the client gave to Emissary will be presented to the service. For many microservices, this will be fine, but if you use Emissary to route to services that use the `Host` header for routing, it's likely to fail (legacy monoliths are particularly susceptible to this, as well as external services). You can use `host_rewrite` to force the `Host` header to whatever value that such target services need. -An example: the default $productName$ configuration includes the following mapping for `httpbin.org`: +An example: the default Emissary configuration includes the following mapping for `httpbin.org`: ```yaml --- diff --git a/content/en/docs/2.5/topics/using/headers/remove_request_headers.md b/content/en/docs/2.5/topics/using/headers/remove_request_headers.md index 62603756..b5fae6fa 100644 --- a/content/en/docs/2.5/topics/using/headers/remove_request_headers.md +++ b/content/en/docs/2.5/topics/using/headers/remove_request_headers.md @@ -1,6 +1,8 @@ -# Remove request headers +--- +title: Remove request headers +--- -$productName$ can remove a list of HTTP headers that would be sent to the upstream from the request. +Emissary can remove a list of HTTP headers that would be sent to the upstream from the request. ## The `remove_request_headers` attribute diff --git a/content/en/docs/2.5/topics/using/headers/remove_response_headers.md b/content/en/docs/2.5/topics/using/headers/remove_response_headers.md index 16b18569..abe9e45a 100644 --- a/content/en/docs/2.5/topics/using/headers/remove_response_headers.md +++ b/content/en/docs/2.5/topics/using/headers/remove_response_headers.md @@ -1,6 +1,8 @@ -# Remove response headers +--- +title: Remove response headers +--- -$productName$ can remove a list of HTTP headers that would be sent to the client in the response (e.g. default `x-envoy-upstream-service-time`). +Emissary can remove a list of HTTP headers that would be sent to the client in the response (e.g. default `x-envoy-upstream-service-time`). ## The `remove_response_headers` attribute diff --git a/content/en/docs/2.5/topics/using/index.md b/content/en/docs/2.5/topics/using/index.md deleted file mode 100644 index a996249e..00000000 --- a/content/en/docs/2.5/topics/using/index.md +++ /dev/null @@ -1,32 +0,0 @@ -# Using $productName$ - -Application development teams use $productName$ to manage edge policies associated with a specific service. This section of the documentation covers core $productName$ elements that are typically used by the application development team. - -* [Introduction to Mappings](intro-mappings) The `Mapping` resource is the core resource used by every application development team. -* Mapping Configuration: - * [Automatic Retries](retries) - * [Canary Releases](canary) - * [Circuit Breakers](circuit-breakers) - * [Cross Origin Resource Sharing](cors) - * HTTP Headers - * [Header-based Routing](headers/headers) - * [Host Header](headers/host) - * [Adding Request Headers](headers/add_request_headers) - * [Adding Response Headers](headers/add_response_headers) - * [Removing Request Headers](headers/remove_request_headers) - * [Remove Response Headers](headers/remove_response_headers) - * [Query Parameter Based Routing](query_parameters) - * [Keepalive](keepalive) - * Protocols - * [TCP](tcpmappings) - * gRPC, HTTP/1.0, gRPC-Web, WebSockets - * [RegEx-based Routing](prefix_regex) - * [Redirects](redirects) - * [Rewrites](rewrites) - * [Timeouts](timeouts) - * [Traffic Shadowing](shadowing) -* [Advanced Mapping Configuration](mappings) -* Rate Limiting - * [Introduction to Rate Limits](rate-limits/) -* [Developer Portal](../../tutorials/dev-portal-tutorial) -* [Gateway API](gateway-api) diff --git a/content/en/docs/2.5/topics/using/intro-mappings.md b/content/en/docs/2.5/topics/using/intro-mappings.md index 51656052..38dff272 100644 --- a/content/en/docs/2.5/topics/using/intro-mappings.md +++ b/content/en/docs/2.5/topics/using/intro-mappings.md @@ -1,12 +1,12 @@ -import Alert from '@material-ui/lab/Alert'; - -# Introduction to the Mapping resource +--- +title: Introduction to the Mapping Resource +--- -$productName$ is designed around a [declarative, self-service management model](../../concepts/gitops-continuous-delivery). The core resource used to support application development teams who need to manage the edge with $productName$ is the `Mapping` resource. +Emissary is designed around a [declarative, self-service management model](../../concepts/gitops-continuous-delivery). The core resource used to support application development teams who need to manage the edge with Emissary is the `Mapping` resource. Remember that Listener and Host resources are -  required for a functioning $productName$ installation that can route traffic!
+  required for a functioning Emissary installation that can route traffic!
Learn more about Listener.
Learn more about Host. @@ -19,7 +19,7 @@ At its core a `Mapping` resource maps a `resource` to a `service`: | :------------------------ | :------------------------ | | `name` | is a string identifying the `Mapping` (e.g. in diagnostics) | | [`prefix`](#resources) | is the URL prefix identifying your [resource](#resources) | -| [`service`](#services) | is the name of the [service](#services) handling the resource; must include the namespace (e.g. `myservice.othernamespace`) if the service is in a different namespace than $productName$ | +| [`service`](#services) | is the name of the [service](#services) handling the resource; must include the namespace (e.g. `myservice.othernamespace`) if the service is in a different namespace than Emissary | These resources are defined as Kubernetes Custom Resource Definitions. Here's a simple example that maps all requests to `/httpbin/` to the `httpbin.org` web service: @@ -36,7 +36,7 @@ spec: ## Applying a Mapping resource -A `Mapping` resource can be managed using the same workflow as any other Kubernetes resources (e.g., `service`, `deployment`). For example, if the above `Mapping` is saved into a file called `httpbin-mapping.yaml`, the following command will apply the configuration directly to $productName$: +A `Mapping` resource can be managed using the same workflow as any other Kubernetes resources (e.g., `service`, `deployment`). For example, if the above `Mapping` is saved into a file called `httpbin-mapping.yaml`, the following command will apply the configuration directly to Emissary: ``` kubectl apply -f httpbin-mapping.yaml @@ -73,7 +73,7 @@ More detail on each of the available annotations are discussed in subsequent sec ## Resources -To $productName$, a `resource` is a group of one or more URLs that all share a common prefix in the URL path. For example: +To Emissary, a `resource` is a group of one or more URLs that all share a common prefix in the URL path. For example: ``` https://ambassador.example.com/resource1/foo @@ -91,11 +91,11 @@ https://ambassador.example.com/resource3/baz/zing https://ambassador.example.com/resource4/baz/zung ``` -share only the prefix `/` -- you _could_ tell $productName$ to treat them as a single resource, but it's probably not terribly useful. +share only the prefix `/` -- you _could_ tell Emissary to treat them as a single resource, but it's probably not terribly useful. -Note that the length of the prefix doesn't matter: if you want to use prefixes like `/v1/this/is/my/very/long/resource/name/`, go right ahead, $productName$ can handle it. +Note that the length of the prefix doesn't matter: if you want to use prefixes like `/v1/this/is/my/very/long/resource/name/`, go right ahead, Emissary can handle it. -Also note that $productName$ does not actually require the prefix to start and end with `/` -- however, in practice, it's a good idea. Specifying a prefix of +Also note that Emissary does not actually require the prefix to start and end with `/` -- however, in practice, it's a good idea. Specifying a prefix of ``` /man @@ -114,7 +114,7 @@ which is probably not what was intended. ## Services -$productName$ routes traffic to a `service`. A `service` is defined as: +Emissary routes traffic to a `service`. A `service` is defined as: ``` [scheme://]service[.namespace][:port] @@ -124,25 +124,25 @@ Where everything except for the `service` is optional. - `scheme` can be either `http` or `https`; if not present, the default is `http`. - `service` is the name of a service (typically the service name in Kubernetes or Consul); it is not allowed to contain the `.` character. -- `namespace` is the namespace in which the service is running. Starting with $productName$ 1.0.0, if not supplied, it defaults to the namespace in which the Mapping resource is defined. The default behavior can be configured using the [`ambassador` Module](../../running/ambassador). When using a Consul resolver, `namespace` is not allowed. +- `namespace` is the namespace in which the service is running. Starting with Emissary 1.0.0, if not supplied, it defaults to the namespace in which the Mapping resource is defined. The default behavior can be configured using the [`ambassador` Module](../../running/ambassador). When using a Consul resolver, `namespace` is not allowed. - `port` is the port to which a request should be sent. If not specified, it defaults to `80` when the scheme is `http` or `443` when the scheme is `https`. Note that the [resolver](../../running/resolvers) may return a port in which case the `port` setting is ignored. Note that while using `service.namespace.svc.cluster.local` may work for Kubernetes resolvers, the preferred syntax is `service.namespace`. ## Best practices for configuration -$productName$'s configuration is assembled from multiple YAML blocks which are managed by independent application teams. This implies: +Emissary's configuration is assembled from multiple YAML blocks which are managed by independent application teams. This implies: -- $productName$'s configuration should be under version control. +- Emissary's configuration should be under version control. - While you can always read back the $productName$'s configuration from Kubernetes or its diagnostic service, the $productName$ will not do versioning for you. + While you can always read back the Emissary's configuration from Kubernetes or its diagnostic service, the Emissary will not do versioning for you. -- Be aware that the $productName$ tries to not start with a broken configuration, but it's not perfect. +- Be aware that the Emissary tries to not start with a broken configuration, but it's not perfect. - Gross errors will result in $productName$ refusing to start, in which case `kubectl logs` will be helpful. However, it's always possible to e.g. map a resource to the wrong service, or use the wrong `rewrite` rules. $productName$ can't detect that on its own, although its diagnostic pages can help you figure it out. + Gross errors will result in Emissary refusing to start, in which case `kubectl logs` will be helpful. However, it's always possible to e.g. map a resource to the wrong service, or use the wrong `rewrite` rules. Emissary can't detect that on its own, although its diagnostic pages can help you figure it out. - Be careful of mapping collisions. - If two different developers try to map `/user/` to something, this can lead to unexpected behavior. $productName$'s canary-deployment logic means that it's more likely that traffic will be split between them than that it will throw an error -- again, the diagnostic service can help you here. + If two different developers try to map `/user/` to something, this can lead to unexpected behavior. Emissary's canary-deployment logic means that it's more likely that traffic will be split between them than that it will throw an error -- again, the diagnostic service can help you here. **Note:** Unless specified, mapping attributes cannot be applied to any other resource type. diff --git a/content/en/docs/2.5/topics/using/keepalive.md b/content/en/docs/2.5/topics/using/keepalive.md index d75e96ba..015d7258 100644 --- a/content/en/docs/2.5/topics/using/keepalive.md +++ b/content/en/docs/2.5/topics/using/keepalive.md @@ -1,10 +1,12 @@ -# Keepalive +--- +title: Keepalive +--- Keepalive option indicates whether `SO_KEEPALIVE` on the socket should be enabled. ## Keepalive configuration -Keepalive configuration can be set for all $productName$ mappings in the [`ambassador Module`](../../running/ambassador) or set per [`Mapping`](../mappings). +Keepalive configuration can be set for all Emissary mappings in the [`ambassador Module`](../../running/ambassador) or set per [`Mapping`](../mappings). The `keepalive` attribute configures keepalive. The following fields are supported: diff --git a/content/en/docs/2.5/topics/using/mappings.md b/content/en/docs/2.5/topics/using/mappings.md index f930fc62..17d34abc 100644 --- a/content/en/docs/2.5/topics/using/mappings.md +++ b/content/en/docs/2.5/topics/using/mappings.md @@ -1,8 +1,10 @@ -# Advanced Mapping configuration +--- +title: Advanced Mapping configuration +--- -$productName$ is designed so that the author of a given Kubernetes service can easily and flexibly configure how traffic gets routed to the service. The core abstraction used to support service authors is a mapping, which maps a target backend service to a given host or prefix. For Layer 7 protocols such as HTTP, gRPC, or WebSockets, the `Mapping` resource is used. For TCP, the `TCPMapping` resource is used. +Emissary is designed so that the author of a given Kubernetes service can easily and flexibly configure how traffic gets routed to the service. The core abstraction used to support service authors is a mapping, which maps a target backend service to a given host or prefix. For Layer 7 protocols such as HTTP, gRPC, or WebSockets, the `Mapping` resource is used. For TCP, the `TCPMapping` resource is used. -$productName$ _must_ have one or more mappings defined to provide access to any services at all. The name of the mapping must be unique. +Emissary _must_ have one or more mappings defined to provide access to any services at all. The name of the mapping must be unique. ## System-wide defaults for Mappings @@ -12,13 +14,13 @@ the `httpmapping` default class. ## Mapping evaluation order -$productName$ sorts mappings such that those that are more highly constrained are evaluated before those less highly constrained. The prefix length, the request method, constraint headers, and query parameters are all taken into account. +Emissary sorts mappings such that those that are more highly constrained are evaluated before those less highly constrained. The prefix length, the request method, constraint headers, and query parameters are all taken into account. -If absolutely necessary, you can manually set a `precedence` on the mapping (see below). In general, you should not need to use this feature unless you're using the `regex_headers` or `host_regex` matching features. If there's any question about how $productName$ is ordering rules, the diagnostic service is a good first place to look: the order in which mappings appear in the diagnostic service is the order in which they are evaluated. +If absolutely necessary, you can manually set a `precedence` on the mapping (see below). In general, you should not need to use this feature unless you're using the `regex_headers` or `host_regex` matching features. If there's any question about how Emissary is ordering rules, the diagnostic service is a good first place to look: the order in which mappings appear in the diagnostic service is the order in which they are evaluated. ## Optional fallback Mapping -$productName$ will respond with a `404 Not Found` to any request for which no mapping exists. If desired, you can define a fallback "catch-all" mapping so all unmatched requests will be sent to an upstream service. +Emissary will respond with a `404 Not Found` to any request for which no mapping exists. If desired, you can define a fallback "catch-all" mapping so all unmatched requests will be sent to an upstream service. For example, defining a mapping with only a `/` prefix will catch all requests previously unhandled and forward them to an external service: @@ -35,15 +37,15 @@ spec: ### Using `precedence` -$productName$ sorts mappings such that those that are more highly constrained are evaluated before those less highly constrained. The prefix length, the request method, and the constraint headers are all taken into account. These mechanisms, however, may not be sufficient to guarantee the correct ordering when regular expressions or highly complex constraints are in play. +Emissary sorts mappings such that those that are more highly constrained are evaluated before those less highly constrained. The prefix length, the request method, and the constraint headers are all taken into account. These mechanisms, however, may not be sufficient to guarantee the correct ordering when regular expressions or highly complex constraints are in play. For those situations, a `Mapping` can explicitly specify the `precedence`. A `Mapping` with no `precedence` is assumed to have a `precedence` of 0; the higher the `precedence` value, the earlier the `Mapping` is attempted. -If multiple `Mapping`s have the same `precedence`, $productName$'s normal sorting determines the ordering within the `precedence`; however, there is no way that $productName$ can ever sort a `Mapping` with a lower `precedence` ahead of one at a higher `precedence`. +If multiple `Mapping`s have the same `precedence`, Emissary's normal sorting determines the ordering within the `precedence`; however, there is no way that Emissary can ever sort a `Mapping` with a lower `precedence` ahead of one at a higher `precedence`. ### Using `tls` -To originate TLS, use a `service` with an `https://` prefix. By itself, this will cause $productName$ to originate TLS without presenting a client certificate to the upstream service: +To originate TLS, use a `service` with an `https://` prefix. By itself, this will cause Emissary to originate TLS without presenting a client certificate to the upstream service: ```yaml --- @@ -70,7 +72,7 @@ spec: tls: upstream-cert-context ``` -(If `tls` is present, $productName$ will originate TLS even if the `service` does not have an `https://` prefix.) +(If `tls` is present, Emissary will originate TLS even if the `service` does not have an `https://` prefix.) ### Using `cluster_tag` @@ -93,29 +95,29 @@ If `dns_type` is not given, `strict_dns` is the default, as this is the most con ## Namespaces and Mappings -If `AMBASSADOR_NAMESPACE` is correctly set, $productName$ can map to services in other namespaces by taking advantage of Kubernetes DNS: +If `AMBASSADOR_NAMESPACE` is correctly set, Emissary can map to services in other namespaces by taking advantage of Kubernetes DNS: -- `service: servicename` will route to a service in the same namespace as $productName$, and +- `service: servicename` will route to a service in the same namespace as Emissary, and - `service: servicename.namespace` will route to a service in a different namespace. ### Linkerd interoperability (`add_linkerd_headers`) When using Linkerd, requests going to an upstream service need to include the `l5d-dst-override` header to ensure that Linkerd will route them correctly. Setting `add_linkerd_headers` does this automatically, based on the `service` attribute in the `Mapping`. -If `add_linkerd_headers` is not specified for a given `Mapping`, the default is taken from the `ambassador`[Module](../../running/ambassador). The overall default is `false`: you must explicitly enable `add_linkerd_headers` for $productName$ to add the header for you (although you can always add it yourself with `add_request_headers`, of course). +If `add_linkerd_headers` is not specified for a given `Mapping`, the default is taken from the `ambassador`[Module](../../running/ambassador). The overall default is `false`: you must explicitly enable `add_linkerd_headers` for Emissary to add the header for you (although you can always add it yourself with `add_request_headers`, of course). ### "Upgrading" to non-HTTP protocols (`allow_upgrade`) HTTP has [a mechanism][upgrade-mechanism] where the client can say `Connection: upgrade` / `Upgrade: PROTOCOL` to switch ("upgrade") from the current HTTP version to a different one, or even a different -protocol entirely. $productName$ itself understands and can handle the +protocol entirely. Emissary itself understands and can handle the different HTTP versions, but for other protocols you need to tell -$productName$ to get out of the way, and let the client speak that +Emissary to get out of the way, and let the client speak that protocol directly with your upstream service. You can do this by setting the `allow_upgrade` field to a case-insensitive list of -protocol names $productName$ will allow switching to from HTTP. After -the upgrade, $productName$ does not interpret the traffic, and behaves +protocol names Emissary will allow switching to from HTTP. After +the upgrade, Emissary does not interpret the traffic, and behaves similarly to how it does for `TCPMapping`s. [upgrade-mechanism]: https://tools.ietf.org/html/rfc7230#section-6.7 @@ -134,7 +136,7 @@ allow_upgrade: The Kubernetes apiserver itself uses this "upgrade" mechanism to perform HTTP authentication before switching to SPDY for endpoint used -by `kubectl exec`; if you wanted to use $productName$ to expose the +by `kubectl exec`; if you wanted to use Emissary to expose the Kubernetes apiserver such that `kubectl exec` functions, you would write diff --git a/content/en/docs/2.5/topics/using/method.md b/content/en/docs/2.5/topics/using/method.md index 94185dcd..43b36e68 100644 --- a/content/en/docs/2.5/topics/using/method.md +++ b/content/en/docs/2.5/topics/using/method.md @@ -1,6 +1,8 @@ -# Method-based routing +--- +title: Method-based routing +--- -$productName$ supports routing based on the HTTP method and regular expression. +Emissary supports routing based on the HTTP method and regular expression. ## Using `method` diff --git a/content/en/docs/2.5/topics/using/prefix_regex.md b/content/en/docs/2.5/topics/using/prefix_regex.md index 04a6e4b8..e7b29c55 100644 --- a/content/en/docs/2.5/topics/using/prefix_regex.md +++ b/content/en/docs/2.5/topics/using/prefix_regex.md @@ -1,8 +1,10 @@ -# Prefix regex +--- +title: Prefix regex +--- ## Using `prefix` and `prefix_regex` -When the `prefix_regex` attribute is set to `true`, $productName$ configures a [regex route](https://www.envoyproxy.io/docs/envoy/v1.5.0/api-v1/route_config/route#route) instead of a prefix route in Envoy. **This means the entire path must match the regex specified, not only the prefix.** +When the `prefix_regex` attribute is set to `true`, Emissary configures a [regex route](https://www.envoyproxy.io/docs/envoy/v1.5.0/api-v1/route_config/route#route) instead of a prefix route in Envoy. **This means the entire path must match the regex specified, not only the prefix.** ## Example with a version in the URL diff --git a/content/en/docs/2.5/topics/using/query-parameters.md b/content/en/docs/2.5/topics/using/query-parameters.md index 6b880fd4..04fcf24a 100644 --- a/content/en/docs/2.5/topics/using/query-parameters.md +++ b/content/en/docs/2.5/topics/using/query-parameters.md @@ -1,10 +1,12 @@ -# Query parameter-based routing +--- +title: Query parameter-based routing +--- -$productName$ can route to target services based on HTTP query parameters with the `query_parameters` and `regex_query_parameters` specifications. Multiple mappings with different annotations can be applied to construct more complex routing rules. +Emissary can route to target services based on HTTP query parameters with the `query_parameters` and `regex_query_parameters` specifications. Multiple mappings with different annotations can be applied to construct more complex routing rules. ## The `query_parameters` annotation -The `query_parameters` attribute is a dictionary of `query_parameter`: `value` pairs. $productName$ will only allow requests that match the specified `query_parameter`: `value` pairs to reach the target service. +The `query_parameters` attribute is a dictionary of `query_parameter`: `value` pairs. Emissary will only allow requests that match the specified `query_parameter`: `value` pairs to reach the target service. You can also set the `value` of a query parameter to `true` to test for the existence of a query parameter. diff --git a/content/en/docs/2.5/topics/using/redirects.md b/content/en/docs/2.5/topics/using/redirects.md index f55c467d..dadc41b9 100644 --- a/content/en/docs/2.5/topics/using/redirects.md +++ b/content/en/docs/2.5/topics/using/redirects.md @@ -1,6 +1,8 @@ -# Redirects +--- +title: Redirects +--- -$productName$ can perform 3xx redirects on `Mapping`s to a different host, with various options to redirect the path and to return a different 3xx response code instead of the default 301. +Emissary can perform 3xx redirects on `Mapping`s to a different host, with various options to redirect the path and to return a different 3xx response code instead of the default 301. ## Schema @@ -34,7 +36,7 @@ spec: Using this `Mapping`, a request to `http://$AMBASSADOR_URL/redirect/` will be redirected to `http://httpbin.org/redirect/`. -> As always with $productName$, the trailing `/` on any URL with a +> As always with Emissary, the trailing `/` on any URL with a `Mapping` is required! ### Path redirect @@ -80,7 +82,7 @@ Now, a request to `http://$AMBASSADOR_URL/redirect/path/` will be redirected to ### Regex redirect `regex_redirect` matches a regular expression to replace instead of a fixed prefix. -[See more information about using regex with $productName$](../rewrites/#regex_rewrite). +[See more information about using regex with Emissary](../rewrites/#regex_rewrite). ```yaml apiVersion: getambassador.io/v3alpha1 @@ -100,7 +102,7 @@ A request to `http://$AMBASSADOR_URL/foo/12345/list` will be redirected to ### Redirect response code -To change the HTTP response code return by $productName$, set `redirect_reponse_code`. If this is not set, 301 is returned by default. Valid values include 301, 302, 303, 307, and 308. This +To change the HTTP response code return by Emissary, set `redirect_reponse_code`. If this is not set, 301 is returned by default. Valid values include 301, 302, 303, 307, and 308. This can be used with any type of redirect. ```yaml @@ -139,4 +141,4 @@ spec: use_remote_address: false ``` -Note: Setting `x_forwarded_proto_redirect: true` will impact all your $productName$ mappings. Every HTTP request to $productName$ will only be allowed to pass if it has an `X-FORWARDED-PROTO: https` header. +Note: Setting `x_forwarded_proto_redirect: true` will impact all your Emissary mappings. Every HTTP request to Emissary will only be allowed to pass if it has an `X-FORWARDED-PROTO: https` header. diff --git a/content/en/docs/2.5/topics/using/retries.md b/content/en/docs/2.5/topics/using/retries.md index d018ab59..5a417d99 100644 --- a/content/en/docs/2.5/topics/using/retries.md +++ b/content/en/docs/2.5/topics/using/retries.md @@ -1,8 +1,10 @@ -# Automatic retries +--- +title: Automatic retries +--- -Sometimes requests fail. When these requests fail for transient issues, $productName$ can automatically retry the request. +Sometimes requests fail. When these requests fail for transient issues, Emissary can automatically retry the request. -Retry policy can be set for all $productName$ mappings in the [`ambassador Module`](../../running/ambassador), or set per [`Mapping`](../mappings). Generally speaking, you should set `retry_policy` on a per mapping basis. Global retries can easily result in unexpected cascade failures. +Retry policy can be set for all Emissary mappings in the [`ambassador Module`](../../running/ambassador), or set per [`Mapping`](../mappings). Generally speaking, you should set `retry_policy` on a per mapping basis. Global retries can easily result in unexpected cascade failures. > Note that when setting `retry_policy`, adjusting `max_retries` in the [circuit breaker](https://www.getambassador.io/docs/edge-stack/pre-release/topics/using/circuit-breakers/) configuration should also be considered in order to account for all desired retries. @@ -19,7 +21,7 @@ retry_policy: ### `retry_on` -(Required) Specifies the condition under which $productName$ retries a failed request. +(Required) Specifies the condition under which Emissary retries a failed request. | Value | Description | | --- | --- | @@ -28,7 +30,7 @@ retry_policy: |`connect-failure`| Retries on a connection failure to the upstream service (included in `5xx`) |`retriable-4xx`| Retries on a retriable 4xx response (currently only 409) |`refused-stream`| Retires if the upstream service sends a REFUSED_STREAM error (included in `5xx`) -|`retriable-status-codes`| Retries based on status codes set in the `x-envoy-retriable-status-codes` header. If that header isn't set, $productName$ will not retry the request. +|`retriable-status-codes`| Retries based on status codes set in the `x-envoy-retriable-status-codes` header. If that header isn't set, Emissary will not retry the request. For more details on each of these values, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/v1.9.0/configuration/http_filters/router_filter#x-envoy-retry-on). diff --git a/content/en/docs/2.5/topics/using/rewrites.md b/content/en/docs/2.5/topics/using/rewrites.md index 44d0a961..0c7060cd 100644 --- a/content/en/docs/2.5/topics/using/rewrites.md +++ b/content/en/docs/2.5/topics/using/rewrites.md @@ -1,10 +1,12 @@ -# Rewrites +--- +title: Rewrites +--- -Once $productName$ uses a prefix to identify the service to which a given request should be passed, it can rewrite the URL before handing it off to the service. +Once Emissary uses a prefix to identify the service to which a given request should be passed, it can rewrite the URL before handing it off to the service. There are two approaches for rewriting: `rewrite` for simpler scenarios and `regex_rewrite` for more advanced rewriting. -**Please note that** only one of these two can be configured for a mapping **at the same time**. As a result $productName$ ignores `rewrite` when `regex_rewrite` is provided. +**Please note that** only one of these two can be configured for a mapping **at the same time**. As a result Emissary ignores `rewrite` when `regex_rewrite` is provided. ## `rewrite` @@ -53,7 +55,7 @@ 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: +To prevent Emissary 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: ""` diff --git a/content/en/docs/2.5/topics/using/shadowing.md b/content/en/docs/2.5/topics/using/shadowing.md index 0ac00849..8e403969 100644 --- a/content/en/docs/2.5/topics/using/shadowing.md +++ b/content/en/docs/2.5/topics/using/shadowing.md @@ -1,4 +1,6 @@ -# Traffic shadowing +--- +title: 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: @@ -8,17 +10,17 @@ Traffic shadowing is a deployment pattern where production traffic is asynchrono * 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$ +## Shadowing and Emissary -$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. +Emissary lets you easily shadow traffic to a given endpoint. In Emissary, 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. Emissary also prioritizes the production path, i.e., it will return responses from the production service without waiting for any responses from the shadow service. ![Shadowing](../../../images/shadowing.png) ## 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. +In Emissary, 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). +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, Emissary 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. @@ -55,7 +57,7 @@ spec: 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. +The `prefix` is set to be the same as the first mapping, which tells Emissary 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 diff --git a/content/en/docs/2.5/topics/using/tcpmappings.md b/content/en/docs/2.5/topics/using/tcpmappings.md index f246e799..deb98dbc 100644 --- a/content/en/docs/2.5/topics/using/tcpmappings.md +++ b/content/en/docs/2.5/topics/using/tcpmappings.md @@ -1,16 +1,18 @@ -# `TCPMapping` resources +--- +title: 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`. +In addition to managing HTTP, gRPC, and WebSockets at layer 7, Emissary 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_. +An Emissary `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. +A service is exactly the same as in HTTP [`Mappings`](../mappings/) and other Emissary resources. ## TCPMapping configuration -Like all native $productName$ resources, `TCPMappings` have an -`ambassador_id` field to select which $productName$ installations take +Like all native Emissary resources, `TCPMappings` have an +`ambassador_id` field to select which Emissary installations take notice of it: | Attribute | Description | Type | Default value | @@ -19,13 +21,13 @@ notice of it: ### Downstream configuration -The downstream configuration refers to the connection between the end-client and $productName$. +The downstream configuration refers to the connection between the end-client and Emissary. | 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 | +| `port` | Which TCP port number Emissary 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 | +| `address` | Which IP address Emissary 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 @@ -52,15 +54,15 @@ terminated, and the `TCPMapping` will be discarded. 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; +To do this, Emissary needs a TLS certificate and configuration; there are two ways that this can be provided: -First, $productName$ checks for any [`Host` +First, Emissary 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 +Second, if such a `Host` is not found, then Emissary 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. @@ -76,7 +78,7 @@ It is an error if no such `Host` or `TLSContext` is found, then the ### Upstream configuration The upstream configuration refers to the connection between -$productName$ and the service that it is a gateway to. +Emissary and the service that it is a gateway to. | Attribute | Description | Type | Default value | |:-------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------|:--------------------------------------------------------------------------------------------------------| @@ -88,7 +90,7 @@ $productName$ and the service that it is a gateway to. | `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. +If both `enable_ipv4` and `enable_ipv6` are true, Emissary 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 @@ -102,8 +104,8 @@ 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 +Given that `AMBASSADOR_NAMESPACE` is correctly set, Emissary can map to services in other namespaces: +- `service: servicename` will route to a service in the same namespace as Emissary, and - `service: servicename.namespace` will route to a service in a different namespace. #### TLS origination @@ -113,17 +115,17 @@ If the `TCPMapping.spec.service` starts with `https://`, or if the 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 +Emissary 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 +If `TCPMapping.spec.tls` is set, then Emissary 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 `TCPMapping.spec.host` attribute determines whether Emissary will _terminate_ TLS when a client connects to Emissary. +The `TCPMapping.spec.service` and `TCPMapping.spec.tls` attributes work together to determine whether Emissary 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. @@ -133,8 +135,8 @@ See the sections on [TLS termination](#tls-termination) and [TLS origination](#t 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, if both of these are true, thenEmissary simply proxies bytes between the client and the upstream; TLS may or may not be involved, Emissary doesn't care. +You should specify in `service` which port to dial to; if you don't, Emissary will use port 80 because it is not originating TLS. So, for example, @@ -167,8 +169,8 @@ could proxy a CockroachDB connection. 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. +In this case, Emissary 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, Emissary 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. @@ -213,14 +215,14 @@ 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. +In this case, Emissary 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. +In this case, Emissary 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. +In either case, you should specify in `service` which port to dial to; if you don't, Emissary 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. @@ -275,7 +277,7 @@ 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$. +Here, Emissary 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 Emissary. Example: diff --git a/content/en/docs/2.5/topics/using/timeouts.md b/content/en/docs/2.5/topics/using/timeouts.md index ae004102..0e184811 100644 --- a/content/en/docs/2.5/topics/using/timeouts.md +++ b/content/en/docs/2.5/topics/using/timeouts.md @@ -1,6 +1,8 @@ -# Timeouts +--- +title: Timeouts +--- -$productName$ enables you to control timeouts in several different ways. +Emissary enables you to control timeouts in several different ways. ## Request timeout: `timeout_ms` @@ -10,7 +12,7 @@ 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`. +`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, Emissary 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` @@ -24,7 +26,7 @@ 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. +`connect_timeout_ms` sets the connection-level timeout for Emissary to an upstream service at the network layer. This timeout runs until Emissary can verify that a TCP connection has been established, including the TLS handshake. This timeout cannot be disabled. Default: `3000` @@ -34,7 +36,7 @@ Default: `3000` `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 +downstream client to Emissary 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`. diff --git a/content/en/docs/2.5/tutorials/_index.md b/content/en/docs/2.5/tutorials/_index.md new file mode 100644 index 00000000..bc896d9b --- /dev/null +++ b/content/en/docs/2.5/tutorials/_index.md @@ -0,0 +1,4 @@ +--- +title: Tutorials +weight: 40 +--- diff --git a/content/en/docs/2.5/tutorials/dev-portal-tutorial.md b/content/en/docs/2.5/tutorials/dev-portal-tutorial.md deleted file mode 100644 index d3c0d0a8..00000000 --- a/content/en/docs/2.5/tutorials/dev-portal-tutorial.md +++ /dev/null @@ -1,29 +0,0 @@ -# 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:///docs/` to see the -publicly visible Developer Portal. Make sure you include the trailing `/`. -This is a fully customizable portal that you can share with third parties who -need information about your APIs. diff --git a/content/en/docs/2.5/tutorials/getting-started.md b/content/en/docs/2.5/tutorials/getting-started.md index 014e1f7b..8cbd4a87 100644 --- a/content/en/docs/2.5/tutorials/getting-started.md +++ b/content/en/docs/2.5/tutorials/getting-started.md @@ -1,12 +1,8 @@ --- -description: "A simple three step guide to installing $productName$ and quickly get started routing traffic from the edge of your Kubernetes cluster to your services." +title: "Getting Started with Emissary" +description: "Learn how to install Emissary with either Helm or kubectl to get started routing traffic from the edge of your Kubernetes cluster to your services..." --- -import Alert from '@material-ui/lab/Alert'; -import GettingStartedEmissary21Tabs from './gs-tabs' - -# $productName$ quick start -

Contents

@@ -19,7 +15,7 @@ import GettingStartedEmissary21Tabs from './gs-tabs' ## 1. Installation -We'll start by installing $productName$ into your cluster. +We'll start by installing Emissary into your cluster. **We recommend using Helm** but there are other options below to choose from. @@ -27,7 +23,7 @@ We'll start by installing $productName$ into your cluster. ### Connecting your installation to Ambassador Cloud -Now is a great moment to connect your new installation to Ambassador Cloud in order to fully leverage the power of $productName$ and the Developer Control Plane (DCP). +Now is a great moment to connect your new installation to Ambassador Cloud in order to fully leverage the power of Emissary and the Developer Control Plane (DCP). 1. Log in to [Ambassador Cloud](https://app.getambassador.io/cloud/services/) with GitHub, GitLab or Google and select your team account. @@ -39,11 +35,11 @@ Now is a great moment to connect your new installation to Ambassador Cloud in or 5. When the token installation completes, your services will be listed in the DCP. -Success! At this point, you have installed $productName$. Now let's get some traffic flowing to your services. +Success! At this point, you have installed Emissary. Now let's get some traffic flowing to your services. ## 2. Routing traffic from the edge -$productName$ uses Kubernetes Custom Resource Definitions (CRDs) to declaratively define its desired state. The workflow you are going to build uses a simple demo app, a **`Listener` CRD**, and a **`Mapping` CRD**. The `Listener` CRD tells $productName$ what port to listen on, and the `Mapping` CRD tells $productName$ how to route incoming requests by host and URL path from the edge of your cluster to Kubernetes services. +Emissary uses Kubernetes Custom Resource Definitions (CRDs) to declaratively define its desired state. The workflow you are going to build uses a simple demo app, a **`Listener` CRD**, and a **`Mapping` CRD**. The `Listener` CRD tells Emissary what port to listen on, and the `Mapping` CRD tells Emissary how to route incoming requests by host and URL path from the edge of your cluster to Kubernetes services. 1. Start by creating a `Listener` resource for HTTP on port 8080: @@ -80,7 +76,7 @@ $productName$ uses Kubernetes Custom Resource Definitions (CRDs) to declarativel The Service and Deployment are created in your default namespace. You can use 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. +3. Generate the YAML for a `Mapping` to tell Emissary 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](#connecting-your-installation-to-ambassador-cloud). Open your browser to https://app.getambassador.io/cloud/services/quote/details and click on **New Mapping**. @@ -111,14 +107,14 @@ $productName$ uses Kubernetes Custom Resource Definitions (CRDs) to declarativel EOF ``` -4. Store the $productName$ load balancer IP address to a local environment variable. You will use this variable to test access to your service. +4. Store the Emissary load balancer IP address to a local environment variable. You will use this variable to test access to your service. ``` export LB_ENDPOINT=$(kubectl -n $productNamespace$ get svc $productDeploymentName$ \ -o "go-template={{range .status.loadBalancer.ingress}}{{or .ip .hostname}}{{end}}") ``` -5. Test the configuration by accessing the service through the $productName$ load balancer: +5. Test the configuration by accessing the service through the Emissary load balancer: ``` $ curl -i http://$LB_ENDPOINT/backend/ @@ -137,19 +133,19 @@ $productName$ uses Kubernetes Custom Resource Definitions (CRDs) to declarativel } ``` -Victory! You have created your first $productName$ Listener and Mapping, routing a request from your cluster's edge to a service! +Victory! You have created your first Emissary 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$: +Explore some of the popular tutorials on Emissary: -* [Configuring $productName$ communications](../../howtos/configure-communications): configure how $productName$ handles communication with clients +* [Configuring Emissary communications](../../howtos/configure-communications): configure how Emissary 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 +Emissary 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). +To learn more about how Emissary works, read the [Emissary Story](../../about/why-ambassador). diff --git a/content/en/docs/2.5/tutorials/gs-tabs.js b/content/en/docs/2.5/tutorials/gs-tabs.js deleted file mode 100644 index eb392504..00000000 --- a/content/en/docs/2.5/tutorials/gs-tabs.js +++ /dev/null @@ -1,131 +0,0 @@ -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 ( - - ); -} - -TabPanel.propTypes = { - children: PropTypes.node, - index: PropTypes.any.isRequired, - value: PropTypes.any.isRequired, -}; - -function a11yProps(index) { - return { - id: `simple-tab-${index}`, - 'aria-controls': `simple-tabpanel-${index}`, - }; -} - -const useStyles = makeStyles((theme) => ({ - root: { - flexGrow: 1, - backgroundColor: 'transparent', - }, -})); - -export default function GettingStartedEmissary21Tabs(props) { - const version = props.version; - const classes = useStyles(); - const [value, setValue] = React.useState(0); - - const handleChange = (event, newValue) => { - setValue(newValue); - }; - - return ( -
- - - } - label="Helm 3" - {...a11yProps(0)} - style={{ minWidth: '10%', textTransform: 'none' }} - /> - } - label="Kubernetes YAML" - {...a11yProps(1)} - style={{ minWidth: '10%', textTransform: 'none' }} - /> - - - - {/*Helm 3 install instructions*/} - - - {'# Add the Repo:' + - '\n' + - 'helm repo add datawire https://app.getambassador.io' + - '\n' + - 'helm repo update' + - '\n \n' + - '# Create Namespace and Install:' + - '\n' + - 'kubectl create namespace emissary && \\' + - '\n' + - `kubectl apply -f https://app.getambassador.io/yaml/emissary/${version}/emissary-crds.yaml` + - '\n' + - 'kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system' + - '\n' + - 'helm install emissary-ingress --namespace emissary datawire/emissary-ingress && \\' + - '\n' + - 'kubectl -n emissary wait --for condition=available --timeout=90s deploy -lapp.kubernetes.io/instance=emissary-ingress' + - '\n'} - - - - - {/*YAML install instructions*/} - - - {'kubectl create namespace emissary && \\' + - '\n' + - `kubectl apply -f https://app.getambassador.io/yaml/emissary/${version}/emissary-crds.yaml && \\` + - '\n' + - 'kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system' + - '\n' + - `kubectl apply -f https://app.getambassador.io/yaml/emissary/${version}/emissary-emissaryns.yaml && \\` + - '\n' + - 'kubectl -n emissary wait --for condition=available --timeout=90s deploy -lproduct=aes' + - '\n'} - - -
- ); -} diff --git a/content/en/docs/2.5/tutorials/gs-tabs2.js b/content/en/docs/2.5/tutorials/gs-tabs2.js deleted file mode 100644 index bfd95047..00000000 --- a/content/en/docs/2.5/tutorials/gs-tabs2.js +++ /dev/null @@ -1,174 +0,0 @@ -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'; - -function TabPanel(props) { - const { children, value, index, ...other } = props; - - return ( - - ); -} - -TabPanel.propTypes = { - children: PropTypes.node, - index: PropTypes.any.isRequired, - value: PropTypes.any.isRequired, -}; - -function a11yProps(index) { - return { - id: `simple-tab-${index}`, - 'aria-controls': `simple-tabpanel-${index}`, - }; -} - -const useStyles = makeStyles((theme) => ({ - root: { - flexGrow: 1, - backgroundColor: 'transparent', - }, -})); - -export default function SimpleTabs() { - const classes = useStyles(); - const [value, setValue] = React.useState(0); - - const handleChange = (event, newValue) => { - setValue(newValue); - }; - - return ( -
- - - - - - - - - - {/*Helm 3 token install instructions*/} - Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Helm. The slideout contains instructions with a - unique cloud-connect-token that is used to connect your - cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'helm upgrade ambassador --namespace ambassador datawire/ambassador \\' + - '\n' + - ' --set agent.cloudConnectToken=$TOKEN && \\' + - '\n' + - 'kubectl -n ambassador wait --for condition=available --timeout=90s deploy -lproduct=aes'} - - - - - {/*Helm 2 token install instructions*/} - Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Helm. The slideout contains instructions with a - unique cloud-connect-token that is used to connect your - cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'helm upgrade --namespace ambassador ambassador datawire/ambassador \\' + - '\n' + - ' --set crds.create=false --set agent.cloudConnectToken=$TOKEN && \\' + - '\n' + - 'kubectl -n ambassador wait --for condition=available --timeout=90s deploy -lproduct=aes'} - - - - - {/*YAML token install instructions*/} - Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Kubernetes YAML. The slideout contains instructions - with a unique cloud-connect-token that is used to connect - your cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'kubectl create configmap -n ambassador ambassador-agent-cloud-token \\' + - '\n' + - ' --from-literal=CLOUD_CONNECT_TOKEN=$TOKEN'} - - - - - {/*edgectl token install instructions*/} - Connecting $productName$ that was installed via edgectl is - identical to the Kubernetes YAML procedure. -
- Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Kubernetes YAML. The slideout contains instructions - with a unique cloud-connect-token that is used to connect - your cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'kubectl create configmap -n ambassador ambassador-agent-cloud-token \\' + - '\n' + - ' --from-literal=CLOUD_CONNECT_TOKEN=$TOKEN'} - - -
- ); -} diff --git a/content/en/docs/2.5/tutorials/quickstart-demo.md b/content/en/docs/2.5/tutorials/quickstart-demo.md index 70cbce8b..5aab30c7 100644 --- a/content/en/docs/2.5/tutorials/quickstart-demo.md +++ b/content/en/docs/2.5/tutorials/quickstart-demo.md @@ -1,19 +1,22 @@ -# $productName$ Tutorial +--- +title: "Quickstart" +description: "Emissary quick start" +--- -In this article, you will explore some of the key features of $productName$ by walking through an example workflow and exploring the +In this article, you will explore some of the key features of Emissary by walking through an example workflow and exploring the Edge Policy Console. ## Prerequisites -You must have [$productName$ installed](../getting-started/) in your +You must have [Emissary installed](../getting-started/) in your Kubernetes cluster. ## Routing Traffic from the Edge Like any other Kubernetes object, Custom Resource Definitions (CRDs) are used to -declaratively define $productName$’s desired state. The workflow you are going to +declaratively define Emissary’s desired state. The workflow you are going to build uses a sample deployment and the `Mapping` CRD, which is the core resource -that you will use with $productName$ to manage your edge. It enables you to route +that you will use with Emissary to manage your edge. It enables you to route requests by host and URL path from the edge of your cluster to Kubernetes services. 1. Copy the configuration below and save it to a file named `quote.yaml` so that @@ -63,7 +66,7 @@ the `quote` deployment and a service to expose that deployment on port 80. 1. Apply the configuration to the cluster with the command `kubectl apply -f quote.yaml`. 1. Copy the configuration below and save it to a file called `quote-backend.yaml` -so that you can create a `Mapping` on your cluster. This `Mapping` tells $productName$ to route all traffic inbound to the `/backend/` path, on any host that can be used to reach $productName$, to the `quote` service. +so that you can create a `Mapping` on your cluster. This `Mapping` tells Emissary to route all traffic inbound to the `/backend/` path, on any host that can be used to reach Emissary, to the `quote` service. ```yaml --- @@ -81,14 +84,14 @@ so that you can create a `Mapping` on your cluster. This `Mapping` tells $produc 1. Apply the configuration to the cluster with the command `kubectl apply -f quote-backend.yaml` -1. Store the $productName$ `LoadBalancer` address to a local environment variable. +1. Store the Emissary `LoadBalancer` address to a local environment variable. You will use this variable to test accessing your pod. ``` export AMBASSADOR_LB_ENDPOINT=$(kubectl -n ambassador get svc ambassador -o "go-template={{range .status.loadBalancer.ingress}}{{or .ip .hostname}}{{end}}") ``` -1. Test the configuration by accessing the service through the $productName$ load +1. Test the configuration by accessing the service through the Emissary load balancer. ``` @@ -100,7 +103,7 @@ balancer. } ``` -Success, you have created your first $productName$ `Mapping`, routing a +Success, you have created your first Emissary `Mapping`, routing a request from your cluster's edge to a service! Since the `Mapping` you just created controls how requests are routed, @@ -137,7 +140,7 @@ with other tutorials. 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. +document. Emissary 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. @@ -156,21 +159,21 @@ Further explore some of the concepts you learned about in this article: * [`Mapping` resource](../../topics/using/intro-mappings/): routes traffic from the edge of your cluster to a Kubernetes service * [`Host` resource](../../topics/running/host-crd/): sets the hostname by which -$productName$ will be accessed and secured with TLS certificates +Emissary will be accessed and secured with TLS certificates * [Developer Portal](../../tutorials/dev-portal-tutorial/): publishes an API catalog and OpenAPI documentation -$productName$ has a comprehensive range of [features](/features/) to +Emissary has a comprehensive range of [features](/features/) to support the requirements of any edge microservice. -Learn more about [how developers use $productName$](../../topics/using/) to manage +Learn more about [how developers use Emissary](../../topics/using/) to manage edge policies. -Learn more about [how site reliability engineers and operators run $productName$](../../topics/running/) +Learn more about [how site reliability engineers and operators run Emissary](../../topics/running/) in production environments. -To learn how $productName$ works, use cases, best practices, and more, check out -the [Quick Start](../getting-started) or read the [$productName$ Story](../../about/why-ambassador). +To learn how Emissary works, use cases, best practices, and more, check out +the [Quick Start](../getting-started) or read the [Emissary Story](../../about/why-ambassador). -For a custom configuration, you can install $productName$ +For a custom configuration, you can install Emissary [manually](../../topics/install/yaml-install). diff --git a/content/en/docs/2.5/versions.yml b/content/en/docs/2.5/versions.yml deleted file mode 100644 index 7712dfef..00000000 --- a/content/en/docs/2.5/versions.yml +++ /dev/null @@ -1,28 +0,0 @@ -# branch info -branch: release/v2.5 - -# self -version: 2.5.1 -productName: "Emissary-ingress" -productNamePlural: "Emissary-ingresses" -productNamespace: emissary -productDeploymentName: emissary-ingress -productHelmName: emissary-ingress - -# OSS (self) -ossVersion: 2.5.1 -ossDocsVersion: "2.5" -ossChartVersion: 7.6.1 -OSSproductName: "Emissary-ingress" -OSSproductNamePlural: "Emissary-ingresses" - -# AES (not self) -aesVersion: 2.5.1 -aesDocsVersion: "2.5" -aesChartVersion: 7.6.1 -AESproductName: "Ambassador Edge Stack" -AESproductNamePlural: "Ambassador Edge Stacks" - -# other products -qotmVersion: 1.7 -quoteVersion: 0.5.0 diff --git a/content/en/docs/3.0/_index.md b/content/en/docs/3.0/_index.md deleted file mode 100644 index 964bdc1a..00000000 --- a/content/en/docs/3.0/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: v3.0 docs -cascade: - version: v3.0 - versName: &name v3.0 - git_version_tag: v3.0.0 - exclude_search: true -linkTitle: *name -simple_list: true -weight: -300 # Weight for doc version vX.Y should be -XY0 ---- - -These docs cover everything from setting up and running Emissary-ingress to its operation and usage. diff --git a/content/en/docs/3.0/about/aes-emissary-eol.md b/content/en/docs/3.0/about/aes-emissary-eol.md deleted file mode 100644 index 59dfbeed..00000000 --- a/content/en/docs/3.0/about/aes-emissary-eol.md +++ /dev/null @@ -1,56 +0,0 @@ -# Ambassador Edge Stack and Emissary-ingress 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/content/en/docs/3.0/about/alternatives.md b/content/en/docs/3.0/about/alternatives.md deleted file mode 100644 index bafec087..00000000 --- a/content/en/docs/3.0/about/alternatives.md +++ /dev/null @@ -1,19 +0,0 @@ -# $productName$ vs. other software - -Alternatives to $productName$ fall into three basic categories: - -* Hosted API gateways, such as the [Amazon API gateway](https://aws.amazon.com/api-gateway/). -* Traditional API gateways, such as [Kong](https://konghq.org/). -* L7 proxies, such as [Traefik](https://traefik.io/), [NGINX](http://nginx.org/), [HAProxy](http://www.haproxy.org/), or [Envoy](https://www.envoyproxy.io), or Ingress controllers built on these proxies. - -Both hosted API gateways and traditional API gateways are: - -* Not self-service. The management interfaces on traditional API gateways are not designed for developer self-service, and provide limited safety and usability for developers. -* Not Kubernetes-native. They're typically configured using REST APIs, making it challenging to adopt cloud-native patterns such as GitOps and declarative configuration. -* [Designed for API management, rather than designed for microservices](../../topics/concepts/microservices-api-gateways). - -A Layer 7 proxy can be used as an API gateway, but typically requires additional bespoke development to support microservices use cases. In fact, many API gateways package the additional features needed for an API gateway on top of an L7 proxy. $productName$ uses Envoy, while Kong uses NGINX. If you're interested in deploying Envoy directly, we've written an [introductory tutorial](https://www.datawire.io/guide/traffic/getting-started-lyft-envoy-microservices-resilience/). - -## Istio - -[Istio](https://istio.io) is an open-source service mesh, built on Envoy. A service mesh is designed to manage East/West traffic (traffic between servers and your data center), while an API gateway manages North/South traffic (in and out of your data center). Documentation on how to deploy $productName$ with Istio is [here](../../howtos/istio). In general, we've found that North/South traffic is quite different from East/West traffic (i.e., you don't control the client in the North/South use case). diff --git a/content/en/docs/3.0/about/changes-2.x.md b/content/en/docs/3.0/about/changes-2.x.md deleted file mode 100644 index 389cc89b..00000000 --- a/content/en/docs/3.0/about/changes-2.x.md +++ /dev/null @@ -1,238 +0,0 @@ -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. - - - $productName$ 2.X supports only API versions getambassador.io/v2 - and getambassador.io/v3alpha1. If you are using any resources with - older API versions, you will need to upgrade them. - - -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 [structural CRDs](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. - - - Learn more about Listener.
- Learn more about Host. - - -### 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. - - - Learn more about Host. - - -### `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. - - - Learn more about Host.
- Learn more about Mapping. - - -### 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. - - - Learn more about Host. - - -### `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). - - - Learn more about Host.
- Learn more about TLSContext. - - -### `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). - - - Learn more about Mapping. - - -### `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. - - - Learn more about Mapping. - - -## 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). In $productName$ -2.X, you may switch back to Envoy V2 by setting the `AMBASSADOR_ENVOY_API_VERSION` -environment variable to "V2"; in $productName$ 3.X, support for the Envoy V2 API (and -the `AMBASSADOR_ENVOY_API_VERSION` environment variable) will be removed. - -### 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. - - - Learn more about Listener. - - -### `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/content/en/docs/3.0/about/changes-3.y.md b/content/en/docs/3.0/about/changes-3.y.md deleted file mode 100644 index 13efc584..00000000 --- a/content/en/docs/3.0/about/changes-3.y.md +++ /dev/null @@ -1,52 +0,0 @@ -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.0 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 AuthServices 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, -``` - - - Learn more about Envoy Proxy changes. - - -## 2. Envoy V2 Protocol Support Removed - -With the upgrade to Envoy **1.22**, the V2 Envoy Transport Protocol is no longer supported. -$productName$ 3.0 **only** supports [V3 Envoy API](https://www.envoyproxy.io/docs/envoy/latest/api-v3/api). - - -The environment variable AMBASSADOR_ENVOY_API_VERSION has been removed and will no longer have the affect -of changing the transport protocol. - - - -The setting of 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. - diff --git a/content/en/docs/3.0/about/faq.md b/content/en/docs/3.0/about/faq.md deleted file mode 100644 index 513c75c5..00000000 --- a/content/en/docs/3.0/about/faq.md +++ /dev/null @@ -1,79 +0,0 @@ -# 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. -* 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! The core functionality of the $AESproductName$ is free and has no limits whatsoever. If you wish to use one of our additional, proprietary features such as Single Sign-On, you can get a free community license for up to 5 requests per second by registering your connected $AESproductName$ installation in [Ambassador Cloud](https://app.getambassador.io/cloud/). Please contact [sales](/contact-us/) if you need more than 5 RPS. - -For more details on core unlimited features and premium features, see the [editions page](/editions). - -### 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? - -[//]: # (+FIX+ Check for OSS) - -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$? - -[//]: # (+FIX+ Check for OSS) - -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 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/content/en/docs/3.0/about/features-and-benefits.md b/content/en/docs/3.0/about/features-and-benefits.md deleted file mode 100644 index a25d7752..00000000 --- a/content/en/docs/3.0/about/features-and-benefits.md +++ /dev/null @@ -1,43 +0,0 @@ -# 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 - -[//]: # (+FIX+ Forge is no more) - -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 - -[//]: # (+FIX+ we've come to realize that it's better to scale vertically) - -$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 using a custom authentication service. When configured, the $productName$ will check with your external authentication service prior to routing an incoming request. For more information, see the [authentication guide](../../topics/running/services/auth-service). - -## 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/content/en/docs/3.0/about/known-issues.md b/content/en/docs/3.0/about/known-issues.md deleted file mode 100644 index 6b89c65a..00000000 --- a/content/en/docs/3.0/about/known-issues.md +++ /dev/null @@ -1,9 +0,0 @@ -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. diff --git a/content/en/docs/3.0/about/support.md b/content/en/docs/3.0/about/support.md deleted file mode 100644 index 11927f95..00000000 --- a/content/en/docs/3.0/about/support.md +++ /dev/null @@ -1,27 +0,0 @@ -# Need help? - -If you need help deploying $productName$ at your organization, there are several different options available to you. - -## Support tiers - -### $productName$ community support - -When running $OSSproductName$, or $AESproductName$ with free community licenses, [join our Slack channel](http://a8r.io/slack) to talk with other users in the community and get your questions answered. - -If you can’t find an answer there, [contact us](/contact-us) to learn more about the support options available with $AESproductName$ Enterprise. - -### $AESproductName$ Enterprise - -With $AESproductName$ Enterprise, you have access to deployment and production support. To learn more, [contact sales](/contact-us). - -**Deployment and Update Support**: $AESproductName$ can accelerate your migration to Kubernetes, or your upgrade between versions of $AESproductName$. Deployment support helps you with the $AESproductName$ and Kubernetes migration, before you move to production. - -**Production Support**: We offer two types of production support contracts for users deploying the $AESproductName$ in production. We offer both business hour (8am - 5pm EST, M-F) and 24x7 Sev 1 support for the $AESproductName$. 24x7 Sev 1 support includes custom hotfix support for production outages if necessary. - -## File a Github Issue - -If you see a bug you want to fix, see room for documentation improvements, or have something else you want to change, you can [file an issue on github](https://github.com/datawire/ambassador/issues/new). - -## Pricing - -[Contact us](/contact-us) to learn how we can help, and for detailed pricing information. diff --git a/content/en/docs/3.0/about/why-ambassador.md b/content/en/docs/3.0/about/why-ambassador.md deleted file mode 100644 index 0d343983..00000000 --- a/content/en/docs/3.0/about/why-ambassador.md +++ /dev/null @@ -1,54 +0,0 @@ -# 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 an open-source, Kubernetes-native [microservices API gateway](../../topics/concepts/microservices-api-gateways) built on 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/content/en/docs/3.0/community.md b/content/en/docs/3.0/community.md deleted file mode 100644 index 759e4f0e..00000000 --- a/content/en/docs/3.0/community.md +++ /dev/null @@ -1,12 +0,0 @@ -# Community - -## Contributor's guide -Please review our [contributor's guide](https://github.com/emissary-ingress/emissary/blob/master/DEVELOPING.md) -on GitHub to learn how you can help make Emissary-ingress better. - -## Changelog -Our [changelog](https://github.com/emissary-ingress/emissary/blob/master/CHANGELOG.md) -describes new features, bug fixes, and updates to each version of Emissary-ingress. - -## Meetings -Check out our community [meeting schedule](https://github.com/emissary-ingress/emissary/blob/master/MEETING_SCHEDULE.md) for opportunities to interact with Emissary-ingress developers. diff --git a/content/en/docs/3.0/doc-links.yml b/content/en/docs/3.0/doc-links.yml deleted file mode 100644 index 86fe75e8..00000000 --- a/content/en/docs/3.0/doc-links.yml +++ /dev/null @@ -1,277 +0,0 @@ - - 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: $productName$ user guide - items: - - title: Deployment - items: - - title: Deployment architecture - link: /topics/running/ambassador-deployment - - title: The $productName$ container environment - 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: HTTP/3 configuration - items: - - title: HTTP/3 overview - link: /topics/running/http3 - - 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: 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: Kubernetes SSO with OIDC and Keycloak - link: /howtos/auth-kubectl-keycloak - - title: Single Sign-On with Google - link: /howtos/sso/google - - title: Single Sign-On with Keycloak - link: /howtos/sso/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: Kubernetes SSO with OIDC and Keycloak - link: /howtos/auth-kubectl-keycloak - - title: Rate limiting - items: - - title: Rate limiting in $productName$ - link: /howtos/advanced-rate-limiting - - title: Rate limiting on token claims - link: /howtos/token-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: 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: 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 and authentication - items: - - title: Authentication extension - link: /topics/running/aes-extensions/authentication - - 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: Ingress and load balancing - items: - - title: Advanced Mapping configuration - link: /topics/using/mappings - - 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 and routing - 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: 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: Rate limiting - items: - - title: Basic rate limiting - link: /topics/using/rate-limits/ - - title: Rate limiting reference - link: /topics/using/rate-limits/rate-limits - - title: Rate limiting extension - link: /topics/running/aes-extensions/ratelimit - - title: Edge policy management - items: - - title: Gateway API - link: /topics/using/gateway-api - - title: End of Life Policy - link: /about/aes-emissary-eol - - title: Developer Portal - link: /topics/using/dev-portal - - title: Changes in $productName$ 2.X - link: /about/changes-2.x - - title: Changes in $productName$ 3.X - link: /about/changes-3.y - - title: Known issues - link: /about/known-issues - - title: FAQs - link: /about/faq - - title: Community - link: /community - - title: Troubleshooting - link: /topics/running/debugging - - title: Release Notes - link: /release-notes - - title: Licenses - link: licenses - - title: EOL Policy - link: /about/aes-emissary-eol diff --git a/content/en/docs/3.0/features-icons/basic-authentication.svg b/content/en/docs/3.0/features-icons/basic-authentication.svg deleted file mode 100644 index 2bd19edf..00000000 --- a/content/en/docs/3.0/features-icons/basic-authentication.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_897228_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.0/features-icons/canary-release.svg b/content/en/docs/3.0/features-icons/canary-release.svg deleted file mode 100644 index f8de57d9..00000000 --- a/content/en/docs/3.0/features-icons/canary-release.svg +++ /dev/null @@ -1,27 +0,0 @@ - - - - Group 25 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.0/features-icons/cors.svg b/content/en/docs/3.0/features-icons/cors.svg deleted file mode 100644 index e559d924..00000000 --- a/content/en/docs/3.0/features-icons/cors.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_111967_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.0/features-icons/datadog.png b/content/en/docs/3.0/features-icons/datadog.png deleted file mode 100644 index eea05f8c..00000000 Binary files a/content/en/docs/3.0/features-icons/datadog.png and /dev/null differ diff --git a/content/en/docs/3.0/features-icons/datadog.svg b/content/en/docs/3.0/features-icons/datadog.svg deleted file mode 100644 index e46e8118..00000000 --- a/content/en/docs/3.0/features-icons/datadog.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Screen Shot 2018-04-05 at 8.22.25 AM - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.0/features-icons/diagnostics.svg b/content/en/docs/3.0/features-icons/diagnostics.svg deleted file mode 100644 index 940e1bc2..00000000 --- a/content/en/docs/3.0/features-icons/diagnostics.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_196445_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.0/features-icons/distributed-tracing.png b/content/en/docs/3.0/features-icons/distributed-tracing.png deleted file mode 100644 index 6b69e28c..00000000 Binary files a/content/en/docs/3.0/features-icons/distributed-tracing.png and /dev/null differ diff --git a/content/en/docs/3.0/features-icons/grpc.png b/content/en/docs/3.0/features-icons/grpc.png deleted file mode 100644 index b2f5a0d9..00000000 Binary files a/content/en/docs/3.0/features-icons/grpc.png and /dev/null differ diff --git a/content/en/docs/3.0/features-icons/prometheus.svg b/content/en/docs/3.0/features-icons/prometheus.svg deleted file mode 100644 index d5252a66..00000000 --- a/content/en/docs/3.0/features-icons/prometheus.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - prometheus_logo_grey - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.0/features-icons/rate-limiting.svg b/content/en/docs/3.0/features-icons/rate-limiting.svg deleted file mode 100644 index f1b6eacb..00000000 --- a/content/en/docs/3.0/features-icons/rate-limiting.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - Group 10 - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.0/features-icons/regex-routing.svg b/content/en/docs/3.0/features-icons/regex-routing.svg deleted file mode 100644 index 113b53b5..00000000 --- a/content/en/docs/3.0/features-icons/regex-routing.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_699774_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.0/features-icons/request-transformers.svg b/content/en/docs/3.0/features-icons/request-transformers.svg deleted file mode 100644 index 0b13e2dc..00000000 --- a/content/en/docs/3.0/features-icons/request-transformers.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_96239_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.0/features-icons/shadowing.svg b/content/en/docs/3.0/features-icons/shadowing.svg deleted file mode 100644 index 9e85eee1..00000000 --- a/content/en/docs/3.0/features-icons/shadowing.svg +++ /dev/null @@ -1,15 +0,0 @@ - - - - shadow - Created with Sketch. - - - - - - - - - - diff --git a/content/en/docs/3.0/features-icons/statsd.png b/content/en/docs/3.0/features-icons/statsd.png deleted file mode 100644 index 28374438..00000000 Binary files a/content/en/docs/3.0/features-icons/statsd.png and /dev/null differ diff --git a/content/en/docs/3.0/features-icons/statsd.svg b/content/en/docs/3.0/features-icons/statsd.svg deleted file mode 100644 index cabc90db..00000000 --- a/content/en/docs/3.0/features-icons/statsd.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - 88eb31f74479e422e4e9abfc6c2b00ee - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.0/features-icons/third-party-auth.svg b/content/en/docs/3.0/features-icons/third-party-auth.svg deleted file mode 100644 index 5359a24a..00000000 --- a/content/en/docs/3.0/features-icons/third-party-auth.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_511233_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.0/features-icons/timeouts.svg b/content/en/docs/3.0/features-icons/timeouts.svg deleted file mode 100644 index 47f63056..00000000 --- a/content/en/docs/3.0/features-icons/timeouts.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_587034_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.0/features-icons/tls-termination.svg b/content/en/docs/3.0/features-icons/tls-termination.svg deleted file mode 100644 index 6a631a96..00000000 --- a/content/en/docs/3.0/features-icons/tls-termination.svg +++ /dev/null @@ -1,17 +0,0 @@ - - - - noun_63544_cc - Created with Sketch. - - - - - - - - - - - - diff --git a/content/en/docs/3.0/features-icons/url-rewrite.svg b/content/en/docs/3.0/features-icons/url-rewrite.svg deleted file mode 100644 index 023e2e05..00000000 --- a/content/en/docs/3.0/features-icons/url-rewrite.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1295942_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.0/features-icons/websockets.svg b/content/en/docs/3.0/features-icons/websockets.svg deleted file mode 100644 index af17b9c0..00000000 --- a/content/en/docs/3.0/features-icons/websockets.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - noun_50814_cc - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.0/howtos/basic-auth.md b/content/en/docs/3.0/howtos/basic-auth.md deleted file mode 100644 index 70ce27ce..00000000 --- a/content/en/docs/3.0/howtos/basic-auth.md +++ /dev/null @@ -1,191 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Basic authentication (for $productName$) - -[//]: # (+FIX+ link to "authentication and authorization" concept) - - - This guide applies to $OSSproductName$, use of this guide with $AESproductName$ is not supported. $AESproductName$ does authentication using the Filter resource instead of the AuthService resource as described below. - - -$productName$ can authenticate incoming requests before routing them to a backing -service. In this tutorial, we'll configure $productName$ to use an external third -party authentication service. We're assuming also that you are running the -quote application in your cluster as described in the -[$productName$ tutorial](../../tutorials/quickstart-demo/). - -## Before you get started - -This tutorial assumes you have already followed the $productName$ [Installation](../../topics/install/) guide. If you haven't done that already, you should do so now. - -Once complete, you'll have a Kubernetes cluster running $productName$. Let's walk through adding authentication to this setup. - -## 1. Deploy the authentication service - -$productName$ delegates the actual authentication logic to a third party authentication service. We've written a [simple authentication service](https://github.com/datawire/ambassador-auth-service) that: - -- listens for requests on port 3000; -- expects all URLs to begin with `/extauth/`; -- performs HTTP Basic Auth for all URLs starting with `/backend/get-quote/` (other URLs are always permitted); -- accepts only user `username`, password `password`; and -- makes sure that the `x-qotm-session` header is present, generating a new one if needed. - -$productName$ routes _all_ requests through the authentication service: it relies on the auth service to distinguish between requests that need authentication and those that do not. If $productName$ cannot contact the auth service, it will return a 503 for the request; as such, **it is very important to have the auth service running before configuring $productName$ to use it.** - -Here's the YAML we'll start with: - -```yaml ---- -apiVersion: v1 -kind: Service -metadata: - name: example-auth -spec: - type: ClusterIP - selector: - app: example-auth - ports: - - port: 3000 - name: http-example-auth - targetPort: http-api ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: example-auth -spec: - replicas: 1 - strategy: - type: RollingUpdate - selector: - matchLabels: - app: example-auth - template: - metadata: - labels: - app: example-auth - spec: - containers: - - name: example-auth - image: docker.io/datawire/ambassador-auth-service:2.0.0 - imagePullPolicy: Always - ports: - - name: http-api - containerPort: 3000 - resources: - limits: - cpu: "0.1" - memory: 100Mi -``` - -Note that the cluster does not yet contain any $productName$ AuthService definition. This is intentional: we want the service running before we tell $productName$ about it. - -The YAML above is published at getambassador.io, so if you like, you can just do - -``` -kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/demo/demo-auth.yaml -``` - -to spin everything up. (Of course, you can also use a local file, if you prefer.) - -Wait for the pod to be running before continuing. The output of `kubectl get pods` should look something like - -``` -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -example-auth-6c5855b98d-24clp 1/1 Running 0 4m -``` -Note that the `READY` field says `1/1` which means the pod is up and running. - -## 2. Configure $productName$ authentication - -Once the auth service is running, we need to tell $productName$ about it. The easiest way to do that is point it to the `example-auth` service with the following: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: AuthService -metadata: - name: authentication -spec: - auth_service: "example-auth:3000" - path_prefix: "/extauth" - allowed_request_headers: - - "x-qotm-session" - allowed_authorization_headers: - - "x-qotm-session" -``` - -This configuration tells $productName$ about the auth service, notably that it needs the `/extauth` prefix, and that it's OK for it to pass back the `x-qotm-session` header. Note that `path_prefix` and `allowed_*_headers` are optional. - -If the auth service uses a framework like [Gorilla Toolkit](http://www.gorillatoolkit.org) which enforces strict slashes as HTTP path separators, it is possible to end up with an infinite redirect where the auth service's framework redirects any request with non-conformant slashing. This would arise if the above example had `path_prefix: "/extauth/"`, the auth service would see a request for `/extauth//backend/get-quote/` which would then be redirected to `/extauth/backend/get-quote/` rather than actually be handled by the authentication handler. For this reason, remember that the full path of the incoming request including the leading slash, will be appended to `path_prefix` regardless of non-conformant slashing. - -You can apply this file from getambassador.io with - -``` -kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/demo/demo-auth-enable.yaml -``` - -or, again, apply it from a local file if you prefer. - -Note that the cluster does not yet contain any $productName$ AuthService definition. - -## 3. Test authentication - -If we `curl` to a protected URL: - -``` -$ curl -Lv $AMBASSADORURL/backend/get-quote/ -``` - -We get a 401 since we haven't authenticated. - -``` -* TCP_NODELAY set -* Connected to 54.165.128.189 (54.165.128.189) port 32281 (#0) -> GET /backend/get-quote/ HTTP/1.1 -> Host: 54.165.128.189:32281 -> User-Agent: curl/7.63.0 -> Accept: */* -> -< HTTP/1.1 401 Unauthorized -< www-authenticate: Basic realm="Ambassador Realm" -< content-length: 0 -< date: Thu, 23 May 2019 15:24:55 GMT -< server: envoy -< -* Connection #0 to host 54.165.128.189 left intact -``` - -If we authenticate to the service, we will get a quote successfully: - -``` -$ curl -Lv -u username:password $AMBASSADORURL/backend/get-quote/ - -* TCP_NODELAY set -* Connected to 54.165.128.189 (54.165.128.189) port 32281 (#0) -* Server auth using Basic with user 'username' -> GET /backend/get-quote/ HTTP/1.1 -> Host: 54.165.128.189:32281 -> Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= -> User-Agent: curl/7.63.0 -> Accept: */* -> -< HTTP/1.1 200 OK -< content-type: application/json -< date: Thu, 23 May 2019 15:25:06 GMT -< content-length: 172 -< x-envoy-upstream-service-time: 0 -< server: envoy -< -{ - "server": "humble-blueberry-o2v493st", - "quote": "Nihilism gambles with lives, happiness, and even destiny itself!", - "time": "2019-05-23T15:25:06.544417902Z" -* Connection #0 to host 54.165.128.189 left intact -} -``` - -## More - -For more details about configuring authentication, see the [`External` filter](/docs/edge-stack/latest/topics/using/filters/) documentation. diff --git a/content/en/docs/3.0/howtos/cert-manager.md b/content/en/docs/3.0/howtos/cert-manager.md deleted file mode 100644 index 975dd3ff..00000000 --- a/content/en/docs/3.0/howtos/cert-manager.md +++ /dev/null @@ -1,230 +0,0 @@ -# Using cert-manager - -[//]: # (+FIX+ link to "TLS and certificates" concept) - -$AESproductName$ has simple and easy built-in support for automatically [using ACME] with the -`http-01` challenge to create and renew TLS certificates. However, this support is not available -in $OSSproductName$, and it is limited to the ACME `http-01` challenge type. If you're running -$OSSproductName$, or if you require more flexible certificate management (such as using ACME's -`dns-01` challenge, or using a non-ACME certificate source), external certificate management -tools are also supported. - -[using ACME]: ../../topics/running/host-crd/#acme-support - -One such tool is Jetstack's [cert-manager](https://github.com/jetstack/cert-manager), which is a general-purpose tool -for managing certificates in Kubernetes. Cert-manager will automatically create and renew TLS certificates and store -them as Kubernetes secrets for easy use in a cluster. $productName$ will automatically watch for secret -changes and reload certificates upon renewal. - -> **Note:** This document assumes cert-manager v0.15 or greater. This document has been updated to use CRD standards -> specified in v0.15. [Legacy CRD support](https://cert-manager.io/docs/installation/upgrading/upgrading-0.14-0.15/) -> was removed in cert-manager v0.15, see their [upgrading](https://cert-manager.io/docs/installation/upgrading/) -> document for more info. - -## Install cert-manager - -There are many different ways to [install cert-manager](https://cert-manager.io/docs/installation/). For simplicity, we will use Helm. - -1. Create the cert-manager CRDs. - ``` - kubectl apply -f https://github.com/jetstack/cert-manager/releases/latest/download/cert-manager.crds.yaml - ``` - -2. Add the `jetstack` Helm repository. - ``` - helm repo add jetstack https://charts.jetstack.io && helm repo update - ``` - -3. Install cert-manager. - - ``` - kubectl create ns cert-manager - helm install cert-manager --namespace cert-manager jetstack/cert-manager - ``` - -## Issuing certificates - -cert-manager issues certificates from a CA such as [Let's Encrypt](https://letsencrypt.org/). It does this using the ACME protocol which supports various challenge mechanisms for verifying ownership of the domain. - -### Issuer - -An `Issuer` or `ClusterIssuer` identifies which Certificate Authority cert-manager will use to issue a certificate. `Issuer` is a namespaced resource allowing you to use different CAs in each namespace, a `ClusterIssuer` is used to issue certificates in any namespace. Configuration depends on which ACME [challenge](#challenge) you are using. - -### Certificate - -A [Certificate](https://cert-manager.io/docs/concepts/certificate/) is a namespaced resource that references an `Issuer` or `ClusterIssuer` for issuing certificates. `Certificate`s define the DNS name(s) a key and certificate should be issued for, as well as the secret to store those files (e.g. `ambassador-certs`). Configuration depends on which ACME [challenge](#challenge) you are using. - -By duplicating issuers, certificates, and secrets one can support multiple domains with [SNI](../../topics/running/tls/sni). - -## Challenge - -cert-manager supports two kinds of ACME challenges that verify domain ownership in different ways: HTTP-01 and DNS-01. - -### DNS-01 challenge - -The DNS-01 challenge verifies domain ownership by proving you have control over its DNS records. Issuer configuration will depend on your [DNS provider](https://cert-manager.io/docs/configuration/acme/dns01/#supported-dns01-providers). This example uses [AWS Route53](https://cert-manager.io/docs/configuration/acme/dns01/route53/). - -1. Create the IAM policy specified in the cert-manager [AWS Route53](https://cert-manager.io/docs/configuration/acme/dns01/route53/) documentation. - -2. Note the `accessKeyID` and create a `secret` named `prod-route53-credentials-secret` in the cert-manager namespace that has a key value: `secret-access-key` from your AWS IaM credentials. - -3. Create and apply a `ClusterIssuer`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: ClusterIssuer - metadata: - name: letsencrypt-prod - spec: - acme: - email: email@example.com - server: https://acme-v02.api.letsencrypt.org/directory - privateKeySecretRef: - name: letsencrypt-prod - solvers: - - selector: - dnsZones: - - "myzone.route53.com" - dns01: - route53: - region: us-east-1 - accessKeyID: {accessKeyID} - hostedZoneID: {Hosted Zone ID} # optional, allows you to reduce the scope of permissions in Amazon IAM - secretAccessKeySecretRef: - name: prod-route53-credentials-secret - key: secret-access-key - ``` - -4. Create and apply a `Certificate`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: Certificate - metadata: - name: myzone.route53.com - # cert-manager will put the resulting Secret in the same Kubernetes - # namespace as the Certificate. You should create the certificate in - # whichever namespace you want to configure a Host. - spec: - secretName: ambassador-certs - issuerRef: - name: letsencrypt-prod - kind: ClusterIssuer - commonName: myzone.route53.com - dnsNames: - - myzone.route53.com - ``` - -5. Verify the secret is created. - - ``` - $ kubectl get secrets -n ambassador - NAME TYPE DATA AGE - ambassador-certs kubernetes.io/tls 2 1h - ``` - -### HTTP-01 challenge - -The HTTP-01 challenge verifies ownership of the domain by sending a request for a specific file on that domain. cert-manager accomplishes this by sending a request to a temporary pod with the prefix `/.well-known/acme-challenge/`. To perform this challenge: - -1. Create and apply a `ClusterIssuer`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: ClusterIssuer - metadata: - name: letsencrypt-prod - spec: - acme: - email: email@example.com - server: https://acme-v02.api.letsencrypt.org/directory - privateKeySecretRef: - name: letsencrypt-prod - solvers: - - http01: - ingress: - class: nginx - selector: {} - ``` - -2. Create and apply a `Certificate`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: Certificate - metadata: - name: ambassador-certs - # cert-manager will put the resulting Secret in the same Kubernetes - # namespace as the Certificate. You should create the certificate in - # whichever namespace you want to configure a Host. - namespace: ambassador - spec: - secretName: ambassador-certs - issuerRef: - name: letsencrypt-prod - kind: ClusterIssuer - dnsNames: - - example.com - ``` - -3. Apply both the `ClusterIssuer` and `Certificate` - - After applying both of these YAML manifests, you will notice that cert-manager has spun up a temporary pod named `cm-acme-http-solver-xxxx` but no certificate has been issued. Check the cert-manager logs and you will see a log message that looks like this: - - ``` - $ kubectl logs cert-manager-756d6d885d-v7gmg - ... - Preparing certificate default/ambassador-certs with issuer - Calling GetOrder - Calling GetAuthorization - Calling HTTP01ChallengeResponse - Cleaning up old/expired challenges for Certificate default/ambassador-certs - Calling GetChallenge - wrong status code '404' - Looking up Ingresses for selector certmanager.k8s.io/acme-http-domain=161156668,certmanager.k8s.io/acme-http-token=1100680922 - Error preparing issuer for certificate default/ambassador-certs: http-01 self check failed for domain "example.com - ``` - -4. Create a Mapping for the `/.well-known/acme-challenge/` route. - - cert-manager uses an `Ingress` to issue the challenge to `/.well-known/acme-challenge/` that is incompatible with Ambassador. We will need to create a `Mapping` so the cert-manager can reach the temporary pod. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Mapping - metadata: - name: acme-challenge-mapping - spec: - hostname: "*" - prefix: /.well-known/acme-challenge/ - rewrite: "" - service: acme-challenge-service - - --- - apiVersion: v1 - kind: Service - metadata: - name: acme-challenge-service - spec: - ports: - - port: 80 - targetPort: 8089 - selector: - acme.cert-manager.io/http01-solver: "true" - ``` - - Apply the YAML and wait a couple of minutes. cert-manager will retry the challenge and issue the certificate. - -5. Verify the secret is created: - - ``` - $ kubectl get secrets - NAME TYPE DATA AGE - ambassador-certs kubernetes.io/tls 2 1h - ambassador-token-846d5 kubernetes.io/service-account-token 3 2h - ``` diff --git a/content/en/docs/3.0/howtos/client-cert-validation.md b/content/en/docs/3.0/howtos/client-cert-validation.md deleted file mode 100644 index 10fe639d..00000000 --- a/content/en/docs/3.0/howtos/client-cert-validation.md +++ /dev/null @@ -1,110 +0,0 @@ -# Client certificate validation - -[//]: # (+FIX+ link to "TLS and client certs" concept) - -Sometimes, for additional security or authentication purposes, you will want -the server to validate who the client is before establishing an encrypted -connection. - -To support this, $productName$ can be configured to use a provided CA certificate -to validate certificates sent from your clients. This allows for client-side -mTLS where both $productName$ and the client provide and validate each other's -certificates. - -## Prerequisites - -- [openssl](https://www.openssl.org/source/) For creating client certificates -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [$productName$](../../tutorials/getting-started) -- [cURL](https://curl.haxx.se/download.html) - - -## Configuration - -1. Create a certificate and key. - - This can be done with a single command with `openssl`: - - ``` - openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 - ``` - - Enter a passcode for PEM files and fill in the certificate information. - Since this certificate will only be shared between a client and $productName$, - the Common Name must be set to something. Everything else can be left blank. - - **Note:** If using MacOS, - [you must](https://curl.haxx.se/mail/archive-2014-10/0053.html) - add the certificate and key as a PKCS encoded file to your Keychain. To do - this: - - 1. Encode `cert.pem` and `key.pem` created above in PKCS format - - ``` - openssl pkcs12 -inkey key.pem -in cert.pem -export -out certificate.p12 - ``` - - 2. Open "Keychain Access" on your system and select "File"->"Import Items..." - - 3. Navigate to your working directory and select the `certificate.p12` file - we just created above. - -2. Create a secret to hold the client CA certificate. - - ``` - kubectl create secret generic client-cacert --from-file=tls.crt=cert.pem - ``` - -3. Configure $productName$ to use this certificate for client certificate validation. - - First create a `Host` to manage your domain: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Host - metadata: - name: example-host - spec: - hostname: host.example.com - acmeProvider: - email: julian@example.com - ``` - - Then create a `TLSContext` to configure advanced TLS options like client - certificate validation: - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: TLSContext - metadata: - name: example-host-context - spec: - hosts: - - host.example.com - secret: host.example.com - ca_secret: client-cacert - cert_required: false # Optional: Configures $productName$ to reject the request if the client does not provide a certificate. Default: false - ``` - - **Note**: Client certificate validation requires $productName$ be configured to terminate TLS - - $productName$ is now be configured to validate certificates that the client provides. - -4. Test that $productName$ is validating the client certificates with `curl` - - **Linux**: - ``` - curl -v --cert cert.pem --key key.pem https://host.example.com/ - ``` - - **MacOS**: - ``` - curl -v --cert certificate.p12:[password] https://host.example.com/ - ``` - - Looking through the verbose output, you can see we are sending a client - certificate and $productName$ is validating it. - - If you need further proof, simply create a new set of certificates and - try sending the curl with those. You will see $productName$ deny the request. diff --git a/content/en/docs/3.0/howtos/configure-communications.md b/content/en/docs/3.0/howtos/configure-communications.md deleted file mode 100644 index 1ac09d2c..00000000 --- a/content/en/docs/3.0/howtos/configure-communications.md +++ /dev/null @@ -1,763 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -Configuring $productName$ Communications -======================================== - -For $productName$ to do its job of managing network communications for your services, it first needs to know how its own communications should be set up. This is handled by a combination of resources: the `Listener`, the `Host`, and the `TLSContext`. - -- `Listener`: defines where, and how, $productName$ should listen for requests from the network. -- `Host`: defines which hostnames $productName$ should care about, and how to handle different kinds of requests for those hosts. `Host`s can be associated with one or more `Listener`s. -- `TLSContext`: defines whether, and how, $productName$ will manage TLS certificates and options. `TLSContext`s can be associated with one or more `Host`s. - -Once the basic communications setup is in place, $productName$ `Mapping`s and `TCPMapping`s can be associated with `Host`s to actually do routing. - - - Remember that Listener and Host resources are  - required for a functioning $productName$ installation that can route traffic!
- Learn more about Listener.
- Learn more about Host. - - - - Remember than $productName$ does not make sure that a wildcard Host exists! If the - wildcard behavior is needed, a Host with a hostname of "*" - must be defined by the user. - - - - Several different resources work together to configure communications. A working knowledge of all of them - can be very useful:
- Learn more about Listener.
- Learn more about Host.
- Learn more about Mapping.
- Learn more about TCPMapping.
- Learn more about TLSContext. - - -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]: ../../topics/running/tls -[certificates]: ../../topics/running/tls#certificates-and-secrets -[check the logs]: ../../topics/running/debugging#review-logs - -Examples / Cookbook -------------------- - -### Basic HTTP and HTTPS - -A useful configuration is to support either HTTP or HTTPS, in this case on either port 8080 or port 8443. This -tends to make it as easy as possible to communicate with the services behind the $productName$ instance. It uses -two `Listener`s and at least one `Host`. - - -#### `Listener`s: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: http-listener -spec: - port: 8080 - protocol: HTTPS # NOT A TYPO, see below - securityModel: XFP - hostBinding: - namespace: - from: SELF # See below ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: - namespace: - from: SELF # See below -``` - -- Both `Listener`s use `protocol: HTTPS` to allow Envoy to inspect incoming connections, determine - whether or not TLS is in play, and set `X-Forwarded-Proto` appropriately. The `securityModel` then specifies - that `X-Forwarded-Proto` will determine whether requests will be considered secure or insecure. - -- The `hostBinding` shown here will allow any `Host` in the same namespace as the `Listener`s - to be associated with both `Listener`s; in turn, that will allow access to that `Host`'s - `Mapping`s from either port. For greater control, use a `selector` instead. - -- Note that the `Listener`s do not specify anything about TLS certificates. The `Host` - handles that; see below. - - - Learn more about Listener - - -#### `Host` - -This example will assume that we expect to be reachable as `foo.example.com`, and that the `foo.example.com` -certificate is stored in the Kubernetes `Secret` named `foo-secret`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: "foo.example.com" - tlsSecret: - name: foo-secret - requestPolicy: - insecure: - action: Redirect -``` - -- The `tlsSecret` specifies the certificate in use for TLS termination. -- The `requestPolicy` specifies routing HTTPS and redirecting HTTP to HTTPS. -- Since the `Host` does not specify a `selector`, only `Mapping`s with a `hostname` that matches - `foo.example.com` will be associated with this `Host`. -- **Note well** that simply defining a `TLSContext` is not sufficient to terminate TLS: you must define either - a `Host` or an `Ingress`. -- Note that if no `Host` is present, but a TLS secret named `fallback-secret` is available, the system will - currently define a `Host` using `fallback-secret`. **This behavior is subject to change.** - - - Learn more about Host - - -### HTTP-Only - -Another straightforward configuration is to support only HTTP, in this case on port 8080. This uses a single -`Listener` and a single `Host`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: http-listener -spec: - port: 8080 - protocol: HTTP - securityModel: INSECURE - hostBinding: - namespace: - from: SELF # See below ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: "foo.example.com" - requestPolicy: - insecure: - action: Route -``` - -- Here, we listen only on port 8080, and only for HTTP. HTTPS will be rejected. -- Since requests are only allowed using HTTP, we declare all requests `INSECURE` by definition. -- The `Host` specifies routing HTTP, rather than redirecting it. - - - - Learn more about Listener
- Learn more about Host - - -### TLS using ACME ($AESproductName$ only) - -This scenario uses ACME to get certificates for `foo.example.com` and `bar.example.com`. HTTPS traffic to either -host is routed; HTTP traffic to `foo.example.com` will be redirected to HTTPS, but HTTP traffic to `bar.example.com` -will be rejected outright. - -Since this example uses ACME, **it is only supported in $AESproductName$**. - -For demonstration purposes, we show this example listening for HTTPS on port 9999, using `X-Forwarded-Proto`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener-9999 -spec: - port: 9999 - protocol: HTTPS - securityModel: XFP - hostBinding: # Edit as needed - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - acmeProvider: - email: julian@example.com ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - acmeProvider: - email: julian@example.com - requestPolicy: - insecure: - action: Reject -``` - -(`Mapping`s are not shown.) - -- Our `Listener`s will accept HTTPS and HTTP on port 9999, and the protocol used will dictate whether - the requests are secure (HTTPS) or insecure (HTTP). -- `foo-host` defaults to ACME with Let's Encrypt, since `acmeProvider.authority` is not provided. -- `foo-host` defaults to redirecting insecure requests, since the default for `requestPolicy.insecure.action` is `Redirect`. -- `bar-host` uses Let's Encrypt as well, but it will reject insecure requests. - -**If you use ACME for multiple Hosts, add a wildcard Host too.** -This is required to manage a known issue. This issue will be resolved in a future Ambassador Edge Stack release. - - - Learn more about Listener
- Learn more about Host - - -### Multiple TLS Certificates - -This scenario uses TLS without ACME. Each of our two `Host`s uses a distinct TLS certificate. HTTPS -traffic to either`foo.example.com` or `bar.example.com` is routed, but this time `foo.example.com` will redirect -HTTP requests, while `bar.example.com` will route them. - -Since this example does not use ACME, it is supported in $productName$ as well as $AESproductName$. - -For demonstration purposes, we show this example listening for HTTPS on port 4848, using `X-Forwarded-Proto`. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: foo-example-secret -data: - tls.crt: -certificate PEM- - tls.key: -secret key PEM- ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: bar-example-secret -data: - tls.crt: -certificate PEM- - tls.key: -secret key PEM- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener-4848 -spec: - port: 4848 - protocol: HTTPS - securityModel: XFP - hostBinding: # Edit as needed - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - tlsSecret: - name: foo-example-secret ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - tlsSecret: - name: bar-example-secret - requestPolicy: - insecure: - action: Route -``` - -- `foo-host` and `bar-host` simply reference the `tlsSecret` to use for termination. - - If the secret involved contains a wildcard cert, or a cert with multiple SAN, both `Host`s could - reference the same `tlsSecret`. -- `foo-host` relies on the default insecure routing action of `Redirect`. -- `bar-host` must explicitly specify routing HTTP. - - - - Learn more about Listener
- Learn more about Host - - -### Using a `TLSContext` - -If you need to share other TLS settings between two `Host`s, you can reference a `TLSContext` as well as -the `tlsSecret`. This is the same as the previous example, but we use a `TLSContext` to set `ALPN` information, -and we assume that the `Secret` contains a wildcard cert. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: wildcard-example-secret -data: - tls.crt: -wildcard here- - tls.key: -wildcard here- ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-context -spec: - secret: wildcard-example-secret - alpn_protocols: [h2, istio] ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener-4848 -spec: - port: 4848 - protocol: HTTPS - securityModel: XFP - hostBinding: # Edit as needed - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - tlsContext: - name: example-context - tlsSecret: - name: wildcard-example-secret ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - tlsContext: - name: example-context - tlsSecret: - name: wildcard-example-secret - requestPolicy: - insecure: - action: Route -``` - -- Note that specifying the `tlsSecret` is still necessary, even when `tlsContext` is specified. - - - - Learn more about Listener
- Learn more about Host - - -### ACME With a TLSContext ($AESproductName$ Only) - -In $AESproductName$, you can use a `TLSContext` with ACME as well. This example is the same as "TLS using ACME", -but we use a `TLSContext` to set `ALPN` information. Again, ACME is only supported in $AESproductName$. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-context -spec: - secret: example-acme-secret - alpn_protocols: [h2, istio] ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - acmeProvider: - email: julian@example.com - tlsContext: - name: example-context - tlsSecret: - name: example-acme-secret -``` - -- Note that we don't provide the `Secret`: the ACME client will create it for us. - - - - Learn more about Listener
- Learn more about Host - - -### Using an L7 Load Balancer to Terminate TLS - -In this scenario, a layer 7 load balancer ahead of $productName$ will terminate TLS, so $productName$ will always see HTTP with a known good `X-Forwarded-Protocol`. We'll use that to route HTTPS and redirect HTTP. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: lb-listener -spec: - port: 8443 - protocol: HTTP - securityModel: XFP - l7Depth: 1 - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: "foo.example.com" - requestPolicy: - insecure: - action: Redirect -``` - -- We set `l7Depth` to 1 to indicate that there's a single trusted L7 load balancer ahead of us. -- We specifically set this Listener to HTTP-only, but we stick with port 8443 just because we expect people setting up TLS at all to expect to use port 8443. (There's nothing special about the port number, pick whatever you like.) -- Our `Host` does not specify a `tlsSecret`, so $productName$ will not try to terminate TLS. -- Since the `Listener` still pays attention to `X-Forwarded-Proto`, both secure and insecure requests - are possible, and we use the `Host` to route HTTPS and redirect HTTP. - - - - Learn more about Listener
- Learn more about Host - - -### Using a Split L4 Load Balancer to Terminate TLS - -Here, we assume that $productName$ is behind a load balancer setup that handles TLS at layer 4: - -- Incoming cleartext traffic is forwarded to $productName$ on port 8080. -- Incoming TLS traffic is terminated at the load balancer, then forwarded to $productName$ _as cleartext_ on port 8443. -- This might involve multiple L4 load balancers, but the actual number doesn't matter. -- The actual port numbers we use don't matter either, as long as $productName$ and the load balancer(s) agree on which port is for which traffic. - -We're going to route HTTPS for both `foo.example.com` and `bar.example.com`, redirect HTTP for `foo.example.com`, and reject HTTP for `bar.example.com`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: split-lb-one-listener -spec: - protocol: HTTP - port: 8080 - securityModel: INSECURE - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: split-lb-two-listener -spec: - protocol: HTTP - port: 8443 - securityModel: SECURE - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - requestPolicy: - insecure: - action: Reject -``` - -- Since L4 load balancers cannot set `X-Forwarded-Protocol`, we don't use it at all here: instead, we dictate that 8080 and 8443 both speak cleartext HTTP, but everything arriving at port 8080 is insecure and everything at port 8443 is secure. - - - - Learn more about Listener
- Learn more about Host - - -### Listening on Multiple Ports - -There's no reason you need to use ports 8080 and 8443, or that you're limited to two ports. Here we'll use ports 9001 and 9002 for HTTP, and port 4001 for HTTPS. We'll route traffic irrespective of protocol. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-9001 -spec: - protocol: HTTP - port: 9001 - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-9002 -spec: - protocol: HTTP - port: 9002 - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-4001 -spec: - protocol: HTTPS - port: 4001 - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: route-host -spec: - requestPolicy: - insecure: - action: Route -``` - -- We can use `X-Forwarded-Proto` for all our `Listener`s: the HTTP-only `Listener`s will set it correctly. -- Each `Listener` can specify only one port, but there's no hardcoded limit on the number of `Listener`s you can have. - - - - Learn more about Listener
- Learn more about Host - - -### Using Labels to Associate `Host`s and `Listener`s - -In the examples above, the `Listener`s all associate with any `Host` in their namespace. In this -example, we will use Kubernetes labels to control the association instead. - -Here, we'll listen for HTTP to `foo.example.com` on port 8888, and for either HTTP or HTTPS to `bar.example.com` on -port 9999 (where we'll redirect HTTP to HTTPS). Traffic to `baz.example.com` will work on both ports, and we'll route -HTTP for it rather than redirecting. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-8888 -spec: - protocol: HTTP - port: 8888 - securityModel: XFP - hostBinding: - selector: - matchLabels: - tenant: foo ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-9999 -spec: - protocol: HTTPS - port: 9999 - securityModel: XFP - hostBinding: - selector: - matchLabels: - tenant: bar ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: bar-secret -data: - tls.crt: -wildcard here- - tls.key: -wildcard here- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host - labels: - tenant: foo -spec: - hostname: foo.example.com - requestPolicy: - insecure: - action: Route ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host - labels: - tenant: bar -spec: - hostname: bar.example.com - tlsSecret: - name: bar-secret ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: baz-host - labels: - tenant: foo - tenant: bar -spec: - hostname: baz.example.com - tlsSecret: - name: bar-secret - requestPolicy: - insecure: - action: Route -``` - -- Note the `labels` on each `Host`, which the `hostBinding` on the `Listener` can reference. - - Note also that only label selectors are supported at the moment. - - - - Learn more about Listener
- Learn more about Host - - -### Wildcard `Host`s and `Mapping`s - -In a `Mapping`, the `host` is now treated as a glob rather than an exact match, with the goal of vastly reducing the need for `host_regex`. (The `hostname` in a `Host` has always been treated as a glob). - -- **Note that only prefix and suffix matches are supported**, so `*.example.com` and `foo.*` are both fine, but `foo.*.com` will not work -- you'll need to use `host_regex` if you really need that. (This is an Envoy limitation.) - -In this example, we'll accept both HTTP and HTTPS, but: - -- Cleartext traffic to any host in `lowsec.example.com` will be routed. -- Cleartext traffic to any host in `normal.example.com` will be redirected. -- Any other cleartext traffic will be rejected. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: example-secret -data: - tls.crt: -wildcard for *.example.com here- - tls.key: -wildcard for *.example.com here- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-8443 -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: lowsec-host -spec: - hostname: "*.lowsec.example.com" - tlsSecret: - name: example-secret - requestPolicy: - insecure: - action: Route ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: normal-host -spec: - hostname: "*.normal.example.com" - tlsSecret: - name: example-secret - requestPolicy: # We could leave this out since - insecure: # redirecting is the default, but - action: Redirect # it's spelled out for clarity. ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: catchall-host -spec: - hostname: "*.example.com" - tlsSecret: - name: example-secret - requestPolicy: - insecure: - action: Reject -``` - -- We'll listen for HTTP or HTTPS on port 8443. -- The three `Host`s apply different insecure routing actions depending on the hostname. -- You could also do this with `host_regex`, but using `host` with globs will give better performance. - - Being able to _not_ associate a given `Mapping` with a given `Host` when the `Mapping`'s - `host` doesn't match helps a lot when you have many `Host`s. - - Reliably determining if a regex (for the `Mapping`) matches a glob (for the `Host`) isn't really possible, so we can't prune `host_regex` `Mapping`s at all. - - - Learn more about Listener
- Learn more about Host - diff --git a/content/en/docs/3.0/howtos/consul.md b/content/en/docs/3.0/howtos/consul.md deleted file mode 100644 index 68ca7aad..00000000 --- a/content/en/docs/3.0/howtos/consul.md +++ /dev/null @@ -1,565 +0,0 @@ - -import Alert from '@material-ui/lab/Alert'; - -# Consul integration - -
-

Contents

- -- [Consul integration](#consul-integration) - - [Architecture overview](#architecture-overview) - - [Installing Consul](#installing-consul) - - [Installing $productName$](#installing-consul) - - [Using Consul for service discovery](#using-consul-for-service-discovery) - - [Using Consul for authorization and encryption](#using-consul-for-authorization-and-encryption) - - [Environment variables](#environment-variables) - - [More information](#more-information) - -
- -[Consul](https://www.consul.io) is a widely used service mesh. -$productName$ natively supports service discovery and unauthenticated -communication to services in Consul. Additionally, the *Ambassador -Consul Connector* enables $productName$ to encrypt and authenticate -its communication via mTLS with services in Consul that make use of -[Consul's *Connect* feature](https://www.consul.io/docs/connect). - -## Architecture overview - -Using Consul with $productName$ is particularly useful when deploying -$productName$ in hybrid cloud environments where you deploy -applications on VMs and Kubernetes. In this environment, Consul -enables $productName$ to securely route over TLS to any application -regardless of where it is deployed. - -In this architecture, Consul serves as the source of truth for your -entire data center, tracking available endpoints, service -configuration, and secrets for TLS encryption. New applications and -services automatically register themselves with Consul using the -Consul agent or API. When you send a request through $productName$, -$productName$ sends the request to an endpoint based on the data in -Consul. - -Ambassador consult diagram - - -This guide first instructs you on registering a service with Consul -and using $productName$ to dynamically route requests to that service -based on Consul's service discovery data, and subsequently instructs -you on using using the Ambassador Consul Connector to use Consul for -authorizing and encrypting requests. - -## Installing Consul - -If you already have Consul installed in your cluster, then go ahead -and skip to the next section. - -1. Before you install Consul, make sure to check the Consul - documentation for any setup steps specific to your platform. Below - you can find setup guides for some of the more popular Kubernetes - platforms. This step is primarily to ensure you have the proper - permissions to set up Consul. You can skip these guides if your - cluster is already configured to grant you the necessary - permissions. - - - [Microsoft Azure Kubernetes Service (AKS)](https://learn.hashicorp.com/tutorials/consul/kubernetes-aks-azure?utm_source=consul.io&utm_medium=docs) - - [Amazon Elastic Kubernetes Service (EKS)](https://learn.hashicorp.com/tutorials/consul/kubernetes-eks-aws?utm_source=consul.io&utm_medium=docs) - - [Google Kubernetes Engine (GKE)](https://learn.hashicorp.com/tutorials/consul/kubernetes-gke-google?utm_source=consul.io&utm_medium=docs) - - - - If you did not find your Kubernetes platform above, check the - [Consul documentation here](https://www.consul.io/docs/k8s) to see - if there are specific setup instructions for your platform. - - - -2. Add the Hashicorp repository for installing Consul with Helm. If - you do not have Helm installed, you can find an [installation guide - here](https://helm.sh/docs/intro/install/). - - ```shell - helm repo add hashicorp https://helm.releases.hashicorp.com - ``` - -3. Create a new `consul-values.yaml` YAML file for the Consul - installation values and copy the values below into that file. - - ```yaml - global: - datacenter: dc1 - - ui: - service: - type: 'LoadBalancer' - - syncCatalog: - enabled: true - - server: - replicas: 1 - bootstrapExpect: 1 - - connectInject: - enabled: true - ``` - - - - Note: you are free to change the value of the `datacenter` field in - the install values. This is the the name of your Consul - Datacenter. - - - -4. Install Consul with Helm using the `consul-values.yaml` values file - you just created. - - ```shell - helm install -f consul-values.yaml hashicorp hashicorp/consul - ``` - -## Installing $productName$ - -If you have not already installed $productName$ in to your cluster, -then go to the [quick start guide](../../tutorials/getting-started) -before continuing any further in this guide. - -## Using Consul for service discovery - -This section of the guide instructs you on configuring $productName$ -to look for services registered to Consul, registering a demo -application with Consul, and configuring $productName$ to route to -this application using endpoint data from Consul. - -In this tutorial, you deploy the application in Kubernetes. However, -this application can be deployed anywhere in your data center, such as -on a VM. - -1. Configure $productName$ to look for services registered to Consul - by creating the `ConsulResolver`. Use `kubectl` to apply the - following manifest: - - ```shell - kubectl apply -f < - - **Note:** If you changed the name of your `datacenter` in the - Consul install values, make sure to change it in the resolver above - to match the name of your datacenter. - - If you changed the name of the helm install from `hashicorp` to - another value, make sure to update the value of the `address` field - in your resolver to match it. - - If you are having trouble figuring out what your `address` field - should be, it follow this format: - `http://{consul_server_pod}.{consul_server_service}.{namespace}.svc.cluster.local:{consul_port}`. - The default Consul port should be `8500` unless you changed it. - - - - This tells $productName$ that Consul is a service discovery endpoint. - - You must set the resolver to your `ConsulResolver` on a - per-`Mapping` basis, otherwise for that `Mapping` $productName$ - uses the default resolver. That is, in order for a `Mapping` to - make use of a service registered in Consul, you need to add - `resolver: consul-dc1` to that `Mapping`. - - For more information about resolver configuration, see the - [resolver reference documentation](../../topics/running/resolvers). - (If you're using Consul deployed elsewhere in your data center, - make sure the `address` points to your Consul FQDN or IP address). - -2. Deploy the Quote demo application. Use `kubectl` to - apply the following manifest: - - ```shell - kubectl apply -f < - - The `SERVICE_NAME` environment variable in the `quote-consul` - `Deployment` specifies the service name for Consul. The default - value is set to "quote-consul", so you only need to include it if - you want to change the service name. - - - - The Quote application contains code to automatically - register itself with Consul, using the `CONSUL_IP` and `POD_IP` - environment variables specified within the `quote-consul` container - spec. - - When you apply this manifest, it registers the `Pod` in the - `quote-consul` `Deployment` as a Consul service with the name - `quote-consul` and the IP address of the `Pod`. - - - - The `"consul.hashicorp.com/connect-inject": "false"` annotation - tells Consul that for this `Deployment` you do not want to use the - sidecar proxy that is part of Consul's Connect feature. Without - Consul's sidecar, the service needs to include code to make a - request to Consul to register the service. The manifest includes - the environment variables `CONSUL_IP`, `POD_IP`, and `SERVICE_NAME` - to provide the Quote service with enough information - to build that request and send it to Consul. To see how this code - works, see our [our Git repo for the Quote - service](https://github.com/datawire/quote). - - - -3. Verify the `quote-consul` `Deployment`'s `Pod` has been registered - with Consul. You can verify this by accessing the Consul UI. - - First use `kubectl port-forward` to make the UI available on your - local workstation: - - ```shell - kubectl port-forward service/hashicorp-consul-ui 8500:80 - ``` - - Then, while the port-forward is running, go to - http://localhost:8500/ in a web browser. You should see a service - named `quote-consul`. - - After you have verified that you see the `quote-consul` service in - your web browser, you may kill the port-forward. - - - - Port forwarding not working for you? Make sure the service name - matches your Consul UI service by checking `kubectl get svc -A` - - - -4. Configure $productName$ to make use of this `quote-consul` service. - Use `kubectl` to apply the following manifest: - - ```shell - kubectl apply -f < - -**Congratulations!** You're successfully routing traffic to the Quote -application, the location of which is registered in -Consul. - - - -## Using Consul for authorization and encryption - -In this part of the guide, you'll install a different version of the -demo application that now uses Consul's *Connect* feature to authorize -its incoming connections using mTLS, and install *Ambassador Consul -Connector* to enable $productName$ to authenticate to such services. - -The following steps assume you've already set up Consul for service -discovery, as detailed above. - -1. The Ambassador Consul Connector retrieves the TLS certificate - issued by the Consul CA and stores it in a Kubernetes `Secret` for - $productName$ to use. Deploy the Ambassador Consul Connector with - `kubectl`: - - ```shell - kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/consul/ambassador-consul-connector.yaml - ``` - - This installs in to your cluster: - - - RBAC resources. - - The Ambassador Consul Connector service. - - A `TLSContext` named `ambassador-consul` to load the - `ambassador-consul-connect` `Secret` into $productName$. - -2. Deploy a new version of the demo application, and configure it to - inject the Consul Connect sidecar by setting - `"consul.hashicorp.com/connect-inject"` to `true`. Note that in - this version of the configuration, you do not have to configure - environment variables for the location of the Consul server. Use - `kubectl` to apply the following manifest: - - ```yaml - kubectl apply -f - < - - Note: Annotations are used to attach metadata to Kubernetes - objects. You can use annotations to link external information to - objects, working in a similar, yet different, fashion to labels. - For more information on annotations, refer to the [Annotating - Kubernetes Services for - Humans](https://kubernetes.io/blog/2021/04/20/annotating-k8s-for-humans/) - article, or get started with annotations in your own cluster with - the [Ambassador Cloud Quick start - guide](https://www.getambassador.io/docs/cloud/latest/service-catalog/quick-start/). - - - - This deploys a demo application `Deployment` called `quote-connect` - (different than the `quote-consul` `Deployment` in the previous - section) with the Consul Connect sidecar proxy. The Connect - sidecar registers the application with Consul, requires TLS to - access the application, and exposes other [Consul Service - Segmentation](https://www.consul.io/docs/connect) features. - - The annotation `consul.hashicorp.com/connect-inject` being set to - `true` in this `Deployment` tells Consul that you want this - `Deployment` to use the Consul Connect sidecar. The sidecar - proxies requests to the service that it is attached to. Keep this - in mind mind when debug requests to the service. - -4. Verify the `quote-connect` `Deployment`'s `Pod` has been registered - with Consul. You can verify this by accessing the Consul UI. - - First use `kubectl port-forward` to make the UI available on your - local workstation: - - ```shell - kubectl port-forward service/hashicorp-consul-ui 8500:80 - ``` - - Then, while the port-forward is running, open - http://localhost:8500/ in a web browser. You should see a service - named `quote-connect`. - - After you have verified that you see the `quote-connect` service in - your web browser, you may kill the port-forward. - -5. Create a `Mapping` to configure $productName$ route to the - `quote-connect` service in Consul. Use `kubectl` to apply the - following manifest: - - ```shell - kubectl apply -f < - -**Congratulations!** You successfully configured the service to work -with the Consul Connect sidecar. - - - -### Environment variables - -The Ambassador Consul Connector can be configured with the following -environment variables. The defaults are best for most use-cases. - -| Environment Variable | Description | Default | -|------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------| -| `_AMBASSADOR_ID` | Set 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`) | `""` | -| `_CONSUL_HOST` | Set the IP or DNS name of the target Consul HTTP API server | `127.0.0.1` | -| `_CONSUL_PORT` | Set the port number of the target Consul HTTP API server | `8500` | -| `_AMBASSADOR_TLS_SECRET_NAME` | Set the name of the Kubernetes `v1.Secret` created by this program that contains the Consul-generated TLS certificate. | `$AMBASSADOR_ID-consul-connect` | -| `_AMBASSADOR_TLS_SECRET_NAMESPACE` | Set the namespace of the Kubernetes `v1.Secret` created by this program. | (same Namespace as the Pod running this integration) | - -## More information - -For more about $productName$'s integration with Consul, read the -[service discovery configuration](../../topics/running/resolvers) -documentation. diff --git a/content/en/docs/3.0/howtos/dist-tracing.md b/content/en/docs/3.0/howtos/dist-tracing.md deleted file mode 100644 index 1a94f2c5..00000000 --- a/content/en/docs/3.0/howtos/dist-tracing.md +++ /dev/null @@ -1,54 +0,0 @@ ---- - Title: Explore distributed tracing and Kubernetes monitoring - description: The Kubernetes monitoring and distributed tracing landscape is complex to grasp. The K8s Initializer can make it easy to enable distributed tracing in any... ---- - -# Explore distributed tracing and Kubernetes monitoring - -The Kubernetes monitoring and distributed tracing landscape is hard to grasp. Although this conceptual approach to [observability is nothing new](https://blog.getambassador.io/distributed-tracing-with-java-microdonuts-kubernetes-and-the-ambassador-api-gateway-ace15b62a89e) — companies like New Relic revolutionized single-application performance monitoring (APM) over a decade ago — it took a few years and the [Dapper publication](https://research.google/pubs/pub36356/) for this idea to migrate to distributed applications. The importance of this technology is only increasing, as more and more of us are building [“deep systems”](https://lightstep.com/deep-systems/). - -As the industry is slowly but surely maturing, standardization is underway. Standardization means proprietary vendor solutions and open source projects are able to collaborate, making our lives easier. For newcomers, understanding the plethora of options, concepts, specifications, and implementations available is still a daunting task: - -* How are Zipkin and Jaeger related? -* What is header propagation? -* Which headers format should I use? -* Who owns the initialization of a trace context? -* How are the data points collected? - -The [K8s Initializer](https://app.getambassador.io/initializer/) can make it easy to enable distributed tracing in any microservices-based system by offering an opinionated and preconfigured application stack that will get you up and running in no time. This way, you can focus on understanding your service topology and interactions rather than waste days on attempting to understand competing standard integrations and tuning configuration switches. - -## One-Click Tracing Configuration with the K8s Initializer - -The K8s Initializer is a tool we built for you to quickly bootstrap any Kubernetes cluster with your own application-ready playground. It will generate YAML manifests for ingress, observability, and more in just a few clicks. Once installed on a local or remote Kubernetes cluster, the generated Kubernetes manifest resources will give you a perfect sandbox environment to deploy your own applications and explore standard integrations. - -Specifically for observability and distributed tracing, the K8s Initializer bundles a Jaeger installation to collect and visualize traces along with a pre-configured Ambassador Edge Stack acting as the ingress controller that will create a trace context on every request. A single selection is required. - -As per the option we selected, we’ll be generating Zipkin-format traces and use B3 headers for propagation between our services. There you have it! Instrument your Java, Python, Golang or Node.js applications with Zipkin and B3 header propagation libraries, then configure your code to send the trace data to the `jaeger-collector.monitoring:9411` service endpoint. - -All that is left to do is making a few requests and visualizing the trace data in the Jaeger UI. - -## Visualizing Trace Data - -As we installed the Ambassador Edge Stack as our ingress controller for Kubernetes via the K8s Initializer, it will instrument parent trace spans for each request coming into our Kubernetes cluster from the internet. The K8s Initializer also pre-configured Ambassador to exposes the Jaeger UI on a subpath: `https://$AMBASSADOR_IP/jaeger/` - -Simply by visiting this URL on our installation, we are able to visualize the generated and collected trace information emitted by our Ambassador installation: - -![Jaeger screenshot](../../images/jaeger.png) - -## Tracing the Future: OpenTelemetry - -The [OpenTelemetry project](https://opentelemetry.io/) was created with the intent of stopping the proliferation of API standards and libraries one might need to support for all their observability needs, effectively replacing the Zipkin-API, OpenCensus, OpenTracing and more competing implementations. - -> OpenTelemetry provides a single set of APIs, libraries, agents, and collector services to capture distributed traces and metrics from your application. You can analyze them using Prometheus, Jaeger, and other observability tools.
--[https://opentelemetry.io/](https://opentelemetry.io/) - -It’s at this point in the conversation that someone inevitably mentions that XKCD... - -![XKCD #927](../../images/xkcd.png) - -OpenTelemetry ultimately supports multiple formats in its [OpenTelemetry-Collector](https://github.com/open-telemetry/opentelemetry-collector), easing the transition from one technology to another when installed as a middleware and translator to relay trace data to other collectors. Along with many of its long-awaited features, it supports multiple trace exporters for Jaeger, Zipkin and proprietary APIs. - -## Learn More -In this tutorial, we’ve shown you how to monitor your Kubernetes application with distributed tracing in just a few clicks with the K8s Initializer. To learn more about these tools and distributed tracing, we also recommend [A Complete Guide to Distributed Tracing by the Lightstep Team](https://lightstep.com/distributed-tracing/). - -We also have guides to setup Edge Stack with [Datadog](../tracing-datadog/), [Zipkin](../tracing-zipkin/), and [Prometheus and Grafana](../prometheus). diff --git a/content/en/docs/3.0/howtos/external-dns.md b/content/en/docs/3.0/howtos/external-dns.md deleted file mode 100644 index f0f51dbb..00000000 --- a/content/en/docs/3.0/howtos/external-dns.md +++ /dev/null @@ -1,130 +0,0 @@ -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 - -Start by checking the [ExternalDNS repo's deployment instructions](https://github.com/kubernetes-sigs/external-dns#deploying-to-a-cluster) to get information about the supported DNS providers and steps to setup ExternalDNS for your provider. Each DNS provider will have its own required steps as well as annotations, arguments, and permissions needed for the following configuration. - - -### Installation - -Configuration for a `ServiceAccount`, `ClusterRole`, and `ClusterRoleBinding` are necessary for the ExternalDNS deployment to support compatability 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 above for annotations and arguments for your DNS Provider. - - -1. Create a YAML file named `externaldns-config.yaml`, and copy the following configuration into it. - - - Ensure that the apiGroups include "getambassador.io" following "networking.k8s.io" and the resources include "hosts" after "ingresses". - - - ```yaml - --- - apiVersion: v1 - kind: ServiceAccount - metadata: - name: external-dns - annotations: - eks.amazonaws.com/role-arn: {ARN} # AWS ARN role - --- - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRole - metadata: - name: external-dns - rules: - - apiGroups: [""] - resources: ["services","endpoints","pods"] - verbs: ["get","watch","list"] - - apiGroups: ["extensions","networking.k8s.io", "getambassador.io"] - resources: ["ingresses", "hosts"] - verbs: ["get","watch","list"] - - apiGroups: [""] - resources: ["nodes"] - verbs: ["list","watch"] - --- - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRoleBinding - metadata: - name: external-dns-viewer - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: external-dns - subjects: - - kind: ServiceAccount - name: external-dns - namespace: default - --- - apiVersion: apps/v1 - kind: Deployment - metadata: - name: external-dns - spec: - strategy: - type: Recreate - selector: - matchLabels: - app: external-dns - template: - metadata: - labels: - app: external-dns - annotations: - iam.amazonaws.com/role: {ARN} # AWS ARN role - spec: - serviceAccountName: external-dns - containers: - - name: external-dns - image: registry.opensource.zalan.do/teapot/external-dns:latest - args: - - --source=ambassador-host - - --domain-filter=example.net # will make ExternalDNS see only the hosted zones matching provided domain, omit to process all available hosted zones - - --provider=aws - - --policy=upsert-only # would prevent ExternalDNS from deleting any records, omit to enable full synchronization - - --aws-zone-type=public # only look at public hosted zones (valid values are public, private or no value for both) - - --registry=txt - - --txt-owner-id= {Hosted Zone ID} # Insert Route53 Hosted Zone ID here - ``` - -2. Review the arguments section from the ExternalDNS deployment - - Configure or remove arguments to fit your needs. Additional arguments required for your DNS provider can be found by checking the [ExternalDNS repo's deployment instructions](https://github.com/kubernetes-sigs/external-dns#deploying-to-a-cluster). - - * `--source=ambassador-host` - required across all DNS providers to tell ExternalDNS to look for hostnames in the $productName$ `Host` configurations. - -3. Apply the above config with the following command to deploy ExternalDNS to your cluster and configure support for $productName$ - - ```shell - kubectl apply -f externaldns-ambassador.yaml - ``` - - - For the above example, ensure that you are using an EKS cluster, or register your cluster with AWS so that ExternalDNS can view and edit your AWS Hosted Zones. If you are using a cluster outside EKS and not registered with AWS you will see permissions errors from the ExternalDNS pod when attempting to list the Hosted Zones. - - -## Usage - -After applying the above configuration, ExternalDNS is ready to use. Configure a `Host` with the following annotation to allow ExternalDNS to get the IP address of your $productName$'s LoadBalancer and register it with your DNS provider. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: your-hostname - annotations: - external-dns.ambassador-service: $productDeploymentName$.$productNamespace$ -spec: - acmeProvider: - authority: none - hostname: your-hostname.example.com -``` - - -Victory! ExternalDNS is now running and configured to report $productName$'s IP and hostname with your DNS provider. diff --git a/content/en/docs/3.0/howtos/filter-dev-guide.md b/content/en/docs/3.0/howtos/filter-dev-guide.md deleted file mode 100644 index eefe8b6b..00000000 --- a/content/en/docs/3.0/howtos/filter-dev-guide.md +++ /dev/null @@ -1,97 +0,0 @@ -# Developing custom filters for routing - -Sometimes you may want $AESproductName$ to manipulate an incoming request. Some example use cases: - -* Inspect an incoming request, and add a custom header that can then be used for routing -* Add custom Authorization headers -* Validate an incoming request fits an OpenAPI specification before passing the request to a target service - -$AESproductName$ supports these use cases by allowing you to execute custom logic in `Filters`. Filters are written in Golang, and managed by $AESproductName$. If you want to write a filter in a language other than Golang, $AESproductName$ also has an HTTP/gRPC interface for Filters called `External`. - -## Prerequisites - -`Plugin` `Filter`s are built as [Go plugins](https://golang.org/pkg/plugin/) and loaded directly into the $AESproductName$ container so they can run in-process with the rest of $AESproductName$. - -To build a `Plugin` `Filter` into the $AESproductName$ container you will need -- Linux or MacOS host (Windows Subsystem for Linux is ok) -- [Docker](https://docs.docker.com/install/) -- [rsync](https://rsync.samba.org/) - -The `Plugin` `Filter` is built by `make` which uses Docker to create a stable build environment in a container and `rsync` to copy files between the container and your host machine. - -See the [README](https://github.com/datawire/apro-example-plugin) for more information on how the `Plugin` works. - -## Creating and deploying filters - -We've created an example filter that you can customize for your particular use case. - -1. Start with the example filter: `git clone - https://github.com/datawire/apro-example-plugin/`. - -2. Make code changes to `param-plugin.go`. Note: If you're developing a non-trivial filter, see the rapid development section below for a faster way to develop and test your filter. - -3. Run `make DOCKER_REGISTRY=...`, setting `DOCKER_REGISTRY` to point - to a registry you have access to. This will generate a Docker image - named `$DOCKER_REGISTRY/amb-sidecar-plugin:VERSION`. - -4. Push the image to your Docker registry: `docker push $DOCKER_REGISTRY/amb-sidecar-plugin:VERSION`. - -5. Configure $AESproductName$ to use the plugin by creating a `Filter` - and `FilterPolicy` CRD, as per the [filter reference](/docs/edge-stack/latest/topics/using/filters/). - -6. Update the standard $AESproductName$ manifest to use your Docker - image instead of the standard sidecar. - - ```patch - value: '60' - - name: AMBASSADOR_INTERNAL_URL - value: https://127.0.0.1:8443 - - image: docker.io/datawire/aes:$version$ - + image: DOCKER_REGISTRY/aes-plugin:VERSION - imagePullPolicy: Always - livenessProbe: - httpGet: - ``` - -## Rapid development of a custom filter - -During development, you may want to sidestep the deployment process for a faster development loop. The `aes-plugin-runner` helps you rapidly develop $AESproductName$ filters locally. - -To install the runner, download the latest version: - -Mac 64-bit | -Linux 64-bit - -Note that the plugin runner must match the version of $AESproductName$ that you are running. Place the binary somewhere in your `$PATH`. - -Information about open-source code used in `aes-plugin-runner` can be found by running `aes-plugin-runner --version`. - -Now, you can quickly test and develop your filter. - -1. In your filter directory, type: `aes-plugin-runner :8080 ./param-plugin.so`. -2. Test the filter by running `curl`: - - ``` - $ curl -Lv localhost:8080?db=2 - * Rebuilt URL to: localhost:8080/?db=2 - * Trying ::1... - * TCP_NODELAY set - * Connected to localhost (::1) port 8080 (#0) - > GET /?db=2 HTTP/1.1 - > Host: localhost:8080 - > User-Agent: curl/7.54.0 - > Accept: */* - > - < HTTP/1.1 200 OK - < X-Dc: Even - < Date: Mon, 25 Feb 2019 19:58:38 GMT - < Content-Length: 0 - < - * Connection #0 to host localhost left intact - ``` - -Note in the example above the `X-Dc` header is added. This lets you inspect the changes the filter is making to your HTTP header. - -## Further reading - -For more details about configuring filters and the `plugin` interface, see the [filter reference](/docs/edge-stack/latest/topics/using/filters/). diff --git a/content/en/docs/3.0/howtos/grpc.md b/content/en/docs/3.0/howtos/grpc.md deleted file mode 100644 index e97f2e56..00000000 --- a/content/en/docs/3.0/howtos/grpc.md +++ /dev/null @@ -1,403 +0,0 @@ -# gRPC Connections - -$productName$ makes it easy to access your services from outside your application. This includes gRPC services, although a little bit of additional configuration is required: by default, Envoy connects to upstream services using HTTP/1.x and then upgrades to HTTP/2 whenever possible. However, gRPC is built on HTTP/2 and most gRPC servers do not speak HTTP/1.x at all. $productName$ must tell its underlying Envoy that your gRPC service only wants to speak to that HTTP/2, using the `grpc` attribute of a `Mapping`. - -## Writing a gRPC service for $productName$ - -There are many examples and walkthroughs on how to write gRPC applications so that is not what this article will aim to accomplish. If you do not yet have a service written you can find examples of gRPC services in all supported languages here: [gRPC Quickstart](https://grpc.io/docs/quickstart/) - -This document will use the [gRPC python helloworld example](https://github.com/grpc/grpc/tree/master/examples/python/helloworld) to demonstrate how to configure a gRPC service with $productName$. - -Follow the example up through [Run a gRPC application](https://grpc.io/docs/languages/python/quickstart/#run-a-grpc-application) to get started. - -### Dockerize - -After building our gRPC application and testing it locally, we need to package it as a Docker container and deploy it to Kubernetes. - -To run a gRPC application, we need to include the client/server and the protocol buffer definitions. - -For gRPC with python, we need to install `grpcio` and the common protos. - -```Dockerfile -FROM python:2.7 - -WORKDIR /grpc - -ENV PATH "$PATH:/grpc" - -COPY greeter_server.py /grpc -COPY helloworld_pb2.py /grpc -COPY helloworld_pb2_grpc.py /grpc - -RUN python -m pip install grpcio -RUN python -m pip install grpcio-tools googleapis-common-protos - -CMD ["python", "./greeter_server.py"] - -EXPOSE 50051 -``` - -Create the container and test it: - -``` -$ docker build -t /grpc_example -$ docker run -p 50051:50051 /grpc_example -``` - -Where `` is your Docker user or registry. - -Switch to another terminal and from the same directory, run the `greeter_client`. The output should be the same as running it outside of the container. - -``` -$ docker run -p 50051:50051 /grpc_example -Greeter client received: Hello, you! -``` - -Once you verify the container works, push it to your Docker registry: - -``` -$ docker push /grpc_example -``` - -### Mapping gRPC services - -$productName$ `Mapping`s are based on URL prefixes; for gRPC, the URL prefix is the full-service name, including the package path (`package.service`). These are defined in the `.proto` definition file. In the example [proto definition file](https://github.com/grpc/grpc/blob/master/examples/protos/helloworld.proto) we see: - -``` -package helloworld; - -// The greeting service definition. -service Greeter { ... } -``` - -so the URL `prefix` is `helloworld.Greeter` and the mapping would be: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py -spec: - hostname: "*" - grpc: True - prefix: /helloworld.Greeter/ - rewrite: /helloworld.Greeter/ - service: grpc-example -``` - -Note the `grpc: true` line - this is what tells Envoy to use HTTP/2 so the request can communicate with your backend service. Also note that you'll need `prefix` and `rewrite` the same here, since the gRPC service needs the package and service to be in the request to do the right thing. - -### Deploying to Kubernetes - -`grpc_example.yaml` - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - acmeProvider: - authority: none - requestPolicy: - insecure: - action: Route ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py -spec: - hostname: "*" - grpc: True - prefix: /helloworld.Greeter/ - rewrite: /helloworld.Greeter/ - service: grpc-example - ---- -apiVersion: v1 -kind: Service -metadata: - labels: - service: grpc-example - name: grpc-example -spec: - type: ClusterIP - ports: - - name: grpc-greet - port: 80 - targetPort: grpc-api - selector: - service: grpc-example ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: grpc-example -spec: - replicas: 1 - selector: - matchLabels: - service: grpc-example - template: - metadata: - labels: - service: grpc-example - spec: - containers: - - name: grpc-example - image: /grpc_example - ports: - - name: grpc-api - containerPort: 50051 - restartPolicy: Always -``` - -The Host is declared here because we are using gRPC without TLS. Since $productName$ terminates TLS by default, in the Host we add a `requestPolicy` which allows insecure connections. After adding the $productName$ mapping to the service, the rest of the Kubernetes deployment YAML file is pretty straightforward. We need to identify the container image to use, expose the `containerPort` to listen on the same port the Docker container is listening on, and map the service port (80) to the container port (50051). - -> For more information on insecure routing, please refer to the [`Host` documentation](../../topics/running/host-crd#secure-and-insecure-requests). - - -Once you have the YAML file and the correct Docker registry, deploy it to your cluster with `kubectl`. - -``` -$ kubectl apply -f grpc_example.yaml -``` - -### Testing the Deployment - -Make sure to test your Kubernetes deployment before making more advanced changes (like adding TLS). To test any service with $productName$, we will need the hostname of the running $productName$ service which you can get with: - -``` -$ kubectl get service ambassador -o wide -``` -Which should return something similar to: - -``` -NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE -ambassador 10.11.12.13 35.36.37.38 80:31656/TCP 1m -``` -where `EXTERNAL-IP` is the `$AMBASSADORHOST` and 80 is the `$PORT`. - -You will need to open the `greeter_client.py` and change `localhost:50051` to `$AMBASSADORHOST:$PORT` - -```diff -- with grpc.insecure_channel('localhost:50051') as channel: -+ with grpc.insecure_channel(‘$AMBASSADORHOST:$PORT’) as channel: - stub = helloworld_pb2_grpc.GreeterStub(channel) - response = stub.SayHello(helloworld_pb2.HelloRequest(name='you')) - print("Greeter client received: " + response.message) -``` - -After making that change, simply run the client again and you will see the gRPC service in your cluster respond: - -``` -$ python greeter_client.py -Greeter client received: Hello, you! -``` - -### gRPC and TLS - -There is some extra configuration required to connect to a gRPC service through $productName$ over an encrypted channel. Currently, the gRPC call is being sent over cleartext to $productName$ which proxies it to the gRPC application. - - gRPC and TLS - -If you want to add TLS encryption to your gRPC calls, first you need to tell $productName$ to add [ALPN protocols](../../topics/running/tls) which are required by HTTP/2 to do TLS. - -For example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls -spec: - hosts: - - "*" - secret: ambassador-cert - alpn_protocols: h2 -``` - -Next, you need to change the client code slightly and tell it to open a secure RPC channel with $productName$. - -```diff -- with grpc.insecure_channel(‘$AMBASSADORHOST:$PORT’) as channel: -+ with grpc.secure_channel(‘$AMBASSADORHOST:$PORT’, grpc.ssl_channel_credentials()) as channel: - stub = helloworld_pb2_grpc.GreeterStub(channel) - response = stub.SayHello(helloworld_pb2.HelloRequest(name='you')) - print("Greeter client received: " + response.message) -``` - -`grpc.ssl_channel_credentials(root_certificates=None, private_key=None, certificate_chain=None)`returns the root certificate that will be used to validate the certificate and public key sent by $productName$. The default values of `None` tells the gRPC runtime to grab the root certificate from the default location packaged with gRPC and ignore the private key and certificate chain fields. Generally, passing no arguments to the method that requests credentials gives the same behavior. Refer to the languages [API Reference](https://grpc.io/docs/) if this is not the case. - -$productName$ is now terminating TLS from the gRPC client and proxying the call to the application over cleartext. - - cert chain public key flow - -If you want to configure authentication in another language, [gRPC provides examples](https://grpc.io/docs/guides/auth.html) with proper syntax for other languages. - -#### Working with Host headers that include the port - -Some gRPC clients automatically include the port in the Host header. This is a problem when using TLS because the certificate will match `myurl.com` but the Host header will be `myurl.com:443`, resulting in the error `rpc error: code = Unimplemented desc =`. If you run into this issue, there are two ways to solve it depending on your use case, both using the Module resource. - -The first is to set the `strip_matching_host_port` [property](../../topics/running/ambassador#strip-matching-host-port) to `true`. However, this only works if the port in the header matches the port that Envoy listens on (8443 by default). In the default installation of $productName$, the public port is 443, which then maps internally to 8443, so this only works for custom installations where the public service port matches the port in the Listener resource. - -The second solution is to use the following [Lua script](../../topics/running/ambassador#lua-scripts), which always strips the port: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador - namespace: ambassador -spec: - config: - lua_scripts: | - function envoy_on_request(request_handle) - local authority = request_handle:headers():get(":authority") - if(string.find(authority, ":") ~= nil) - then - local authority_index = string.find(authority, ":") - local stripped_authority = string.sub(authority, 1, authority_index - 1) - request_handle:headers():replace(":authority", stripped_authority) - end - end -``` - -#### Originating TLS with gRPC service - - cert chain private key flow - -$productName$ can originate TLS with your gRPC service so the entire RPC channel is encrypted. To configure this, first get some TLS certificates and configure the server to open a secure channel with them. Using self-signed certs this can be done with OpenSSL and adding a couple of lines to the server code. - -```diff -def serve(): - server = grpc.server(futures.ThreadPoolExecutor(max_workers=10)) -+ with open('certs/server.key', 'rb') as f: -+ private_key = f.read() -+ with open('certs/server.crt', 'rb') as f: -+ cert_chain = f.read() -+ server_creds = grpc.ssl_server_credentials( ( (private_key, cert_chain), ) ) - helloworld_pb2_grpc.add_GreeterServicer_to_server(Greeter(), server) -- server.add_insecure_port('[::]:50052') -+ server.add_secure_port('[::]:50052', server_creds) - server.start() -``` - -Rebuild your docker container **making sure the certificates are included** and follow the same steps of testing and deploying to Kubernetes. You will need to make a small change to the client code to test locally. - -```diff -- with grpc.insecure_channel(‘localhost:$PORT’) as channel: -+ with grpc.secure_channel(‘localhost:$PORT’, grpc.ssl_channel_credentials(open('certs/server.crt', 'rb').read())) as channel: - stub = helloworld_pb2_grpc.GreeterStub(channel) - response = stub.SayHello(helloworld_pb2.HelloRequest(name='you')) - print("Greeter client received: " + response.message) -``` - -Once deployed we will need to tell $productName$ to originate TLS to the application. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py-tls -spec: - hostname: "*" - grpc: True - tls: upstream - prefix: /hello.Greeter/ - rewrite: /hello.Greeter/ - service: https://grpc-py - ---- -apiVersion: v1 -kind: Service -metadata: - labels: - service: grpc-py - name: grpc-py -spec: - type: ClusterIP - ports: - - name: grpc-greet - port: 443 - targetPort: grpc-api - selector: - service: grpc-py -``` - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: upstream -spec: - alpn_protocols: h2 - secret: ambassador-cert -``` - -We need to tell $productName$ to route to the `service:` over https and have the service listen on `443`. We also need to tell $productName$ to use ALPN protocols when originating TLS with the application, the same way we did with TLS termination. This is done by setting `alpn_protocols: ["h2"]` in a `TLSContext` telling the service to use that tls-context in the mapping by setting `tls: upstream`. - -Refer to the [TLS document](../../topics/running/tls/origination#advanced-configuration-using-a-tlscontext) for more information on TLS origination. - -### gRPC headers - -gRPC services use [HTTP/2 headers](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md). This means that some header-based routing rules will need to be rewritten to support HTTP/2 headers. For example, `host: subdomain.host.com` needs to be rewritten using the `headers: ` attribute with the `:authority` header: - -``` -headers: - :authority: subdomain.host.com -``` - -## Note - -### Ingress controllers - -Some [Kubernetes ingress controllers](https://kubernetes.io/docs/concepts/services-networking/ingress/) do not support HTTP/2 fully. As a result, if you are running $productName$ with an ingress controller in front, you may find that gRPC requests fail even with correct $productName$ configuration. - -A simple way around this is to use $productName$ with a `LoadBalancer` service, rather than an Ingress controller. You can also consider using [$productName$ as your Ingress Controller](../../topics/running/ingress-controller). - -### Mappings with hosts - -As with any `Mapping`, your gRPC service's `Mapping` may include a `host`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py -spec: - hostname: "*" - grpc: true - prefix: /helloworld.Greeter/ - rewrite: /helloworld.Greeter/ - service: grpc-example - host: api.example.com -``` - -Some gRPC client libraries produce requests where the `host` or `:authority` header includes the port number. For example, a request to the above service might include `host: api.example.com:443` instead of just `host: api.example.com`. To avoid having $productName$ return a 404 (not found) response to these requests due to the mismatched host, you may want to set `strip_matching_host_port` in the [Ambassador module](../../topics/running/ambassador#strip-matching-host-port). - -Alternately, you may find it cleaner to make sure your gRPC client does not include the port in the `host` header. Here is an example using gRPC/Go. - -```go -hostname := "api.example.com" -port := "443" -config := &tls.Config{ServerName: hostname} -creds := credentials.NewTLS(config) -opts := []grpc.DialOption{ - grpc.WithTransportCredentials(creds), -// ... -} -conn, err := grpc.Dial(hostname+":"+port, opts...) -// ... -``` - -## gRPC-Web - -$productName$ also supports the [gRPC-Web](../../topics/running/ambassador#grpc) protocol for browser-based gRPC applications. diff --git a/content/en/docs/3.0/howtos/http3-aks.md b/content/en/docs/3.0/howtos/http3-aks.md deleted file mode 100644 index 3e03bcc5..00000000 --- a/content/en/docs/3.0/howtos/http3-aks.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "$productName$ - HTTP/3 support for Azure Kubernetes Service (AKS)" -description: "How to configure HTTP/3 support for Azure Kubernetes Service (AKS). This guide shows how to setup the LoadBalancer service for AKS to support both TCP and UDP communications." ---- - -# Azure Kubernetes Service Engine HTTP/3 configuration - -This guide shows how to setup HTTP/3 support for Azure Kubernetes Service (AKS). The instructions provided in this page are a continuation of the [HTTP/3 in $productName$](../../../topics/running/http3) documentation. - -## Configuring an external load balancer for AKS - -To configure an external load balancer for AKS, you need to: - -1. Reserve a public static IP address. -2. Create two `LoadBalancer` services, one for TCP and one for UDP. -3. Assign the public static IP address to the `loadBalancerIP` field. - -An example of the two load balancer services described above looks as follows: - -```yaml -# selectors and labels removed for clarity -apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$ - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - --- - apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$-udp - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http3 - port: 443 # Default support for HTTP/3 requires you to use 443 for the external client-facing port. - targetPort: 8443 - protocol: UDP - -``` - -In the above example, AKS generates two `LoadBalancer` services, one for UDP and the other for TCP. - - -You should verify that the Managed Identity or Serivce Principal has permissions to assign the IP address to the newly created LoadBalancer services. Refer to the Azure Docs - Managed Identity for more information. - diff --git a/content/en/docs/3.0/howtos/http3-eks.md b/content/en/docs/3.0/howtos/http3-eks.md deleted file mode 100644 index ce54fd0c..00000000 --- a/content/en/docs/3.0/howtos/http3-eks.md +++ /dev/null @@ -1,252 +0,0 @@ ---- -title: "HTTP/3 with Amazon Elastic Kubernetes Service—EKS | $productName$" -description: "How to configure HTTP/3 support for Amazon Elastic Kubernetes Service (EKS). This guide shows how to setup the LoadBalancer service for EKS to support both TCP and UDP communications." ---- - -# Amazon Elastic Kubernetes Service HTTP/3 configuration - -This guide shows how to setup HTTP/3 support for Amazon Elastic Kubernetes Service (EKS) The instructions provided in this page are a continuation of the [HTTP/3 in $productName$](../../topics/running/http3) documentation. - -## Create a network load balancer (NLB) - - The virtual private cloud (VPC) for your load balancer needs one public subnet in each availability zone where you have targets. - - ```shell - SUBNET_IDS=( ) - - aws elbv2 create-load-balancer \ - --name ${CLUSTER_NAME}-nlb \ - --type network \ - --subnets ${SUBNET_IDS} - ``` - -## Create a NodePort service - -Now create a `NodePort` service for $productName$ installation with two entries. Use `port: 443` to include support for both TCP and UDP traffic. - ```yaml - # Selectors and labels removed for clarity. - apiVersion: v1 - kind: Service - metadata: - name: $productDeploymentName$-http3 - namespace: $productNamespace$ - spec: - type: NodePort - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - nodePort: 30080 - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - nodePort: 30443 - - name: http3 - port: 443 - targetPort: 8443 - protocol: UDP - nodePort: 30443 - ``` - -## Create target groups - -Run the following command with the variables for your VPC ID and cluster name: - - ```shell - VPC_ID= - CLUSTER_NAME= - - aws elbv2 create-target-group --name ${CLUSTER_NAME}-tcp-tg \ - --protocol TCP --port 30080 --vpc-id ${VPC_ID} \ - --health-check-protocol TCP \ - --health-check-port 30080 \ - --target-type instance - - aws elbv2 create-target-group --name ${CLUSTER_NAME}-tcp-udp-tg \ - --protocol TCP_UDP --port 30443 --vpc-id ${VPC_ID} \ - --health-check-protocol TCP \ - --health-check-port 30443 \ - --target-type instance - ``` - -## Register your instances - -Next, register your cluster's instance with the the instance IDs and Amazon Resource Names (ARN). - -To get your cluster's instance IDs, enter the following command: - ```shell - aws ec2 describe-instances \ - --filters Name=tag:eks:cluster-name,Values=${CLUSTER_NAME} \ - --output text - --query 'Reservations[*].Instances[*].InstanceId' \ - ``` - -To get your ARNs, enter the following command: - ```shell - TCP_TG_NAME=${CLUSTER_NAME}-tcp-tg-name - TCP_UDP_TG_NAME=${CLUSTER_NAME}-tcp-udp-tg-name - - aws elbv2 describe-target-groups \ - --query 'TargetGroups[?TargetGroupName==`'${TCP_TG_NAME}'`].TargetGroupArn' \ - --output text - aws elbv2 describe-target-groups \ - --query 'TargetGroups[?TargetGroupName==`'${TCP_UDP_TG_NAME}'`]. TargetGroupArn' \ - --output text - ``` - -Register the instances with the target groups and load balancer using the instance IDs and ARNs you retrieved. - ```shell - INSTANCE_IDS=( ) - REGION= - TG_NAME= - TCP_TG_ARN=arn:aws:elasticloadbalancing:${REGION}:079.....:targetgroup/${TG_NAME}/... - TCP_UDP_TG_ARN=arn:aws:elasticloadbalancing:${REGION}:079.....:targetgroup/${TG_NAME}/... - - aws elbv2 register-targets --target-group-arn ${TCP_TG_ARN} --targets ${INSTANCE_IDS} - aws elbv2 register-targets --target-group-arn ${TCP_UDP_TG_ARN} --targets ${INSTANCE_IDS} - ``` - -## Create listeners in AWS. - -Register your cluster's instance with the instance IDs and ARNs. - -To get the load balancer's ARN, enter the following command: - ```shell - aws elbv2 describe-load-balancers --name ${CLUSTER_NAME}-nlb \ - --query 'LoadBalancers[0].LoadBalancerArn' \ - --output text - ``` - -Create a TCP listener on port 80 that that forwards to the TargetGroup {TCP_TG_ARN}. - ```shell - aws elbv2 create-listener --load-balancer-arn ${LB_ARN} \ - --protocol TCP --port 80 \ - --default-actions Type=forward,TargetGroupArn=${TCP_TG_ARN} - ``` - - Create a TCP_UDP listener on port 443 that forwards to the TargetGroup {TCP_UDP_TG_ARN}. - ```shell - aws elbv2 create-listener --load-balancer-arn ${LB_ARN} \ - --protocol TCP_UDP --port 443 \ - --default-actions Type=forward,TargetGroupArn=${TCP_UDP_TG_ARN} - ``` - -## Update the security groups - -Now you need to update your security groups to receive traffic. This security group covers all node groups attached to the EKS cluster: - ```shell - aws eks describe-cluster --name ${CLUSTER_NAME} | grep clusterSecurityGroupId - ``` - -Now authorize the cluster security group to allow internet traffic: - ```shell - for x in ${CLUSTER_SG}; do \ - aws ec2 authorize-security-group-ingress --group-id $$x --protocol tcp --port 30080 --cidr 0.0.0.0/0; \ - aws ec2 authorize-security-group-ingress --group-id $$x --protocol tcp --port 30443 --cidr 0.0.0.0/0; \ - aws ec2 authorize-security-group-ingress --group-id $$x --protocol udp --port 30443 --cidr 0.0.0.0/0; \ - done - ``` - -## Get the DNS name for the load balancers - -Enter the following command to get the DNS name for your load balancers and create a CNAME record at your domain provider: - ```shell - aws elbv2 describe-load-balancers --name ${CLUSTER_NAME}-nlb \ - --query 'LoadBalancers[0].DNSName' \ - --output text - ``` - -## Create Listener resources - -Now you need to create the `Listener` resources for $productName$. The first `Listener` in the example below handles traffic for HTTP/1.1 and HTTP/2, while the second `Listener` handles all HTTP/3 traffic. - - ```yaml - kubectl apply -f - < - acmeProvider: - authority: none - tlsSecret: - name: tls-cert # The QUIC network protocol requires TLS with a valid certificate - tls: - min_tls_version: v1.3 - max_tls_version: v1.3 - alpn_protocols: h2,http/1.1 - EOF - ``` - -## Apply the quote service and a Mapping to test the HTTP/3 configuration. - -Finally, apply the quote service to a $productName$ `Mapping`. - - ```shell - kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$version$/quickstart/qotm.yaml - kubectl apply -f - </backend/ - ``` -Your domain now shows that it is being served with HTTP/3. diff --git a/content/en/docs/3.0/howtos/http3-gke.md b/content/en/docs/3.0/howtos/http3-gke.md deleted file mode 100644 index 876b323d..00000000 --- a/content/en/docs/3.0/howtos/http3-gke.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: "$productName$ - HTTP/3 support for Google Kubernetes Engine (GKE)" -description: "How to configure HTTP/3 support for Google Kubernetes Engine (GKE). This guide shows how to setup the LoadBalancer service for GKE to support both TCP and UDP communications." ---- - -# Google Kubernetes Service Engine HTTP/3 configuration - -This guide shows how to setup HTTP/3 support for Google Kubernetes Engine (GKE). The instructions provided in this page are a continuation of the [HTTP/3 in $productName$](../../../topics/running/http3) documentation. - -## Configuring an external load balancer for GKE - -Currently, GKE only supports adding feature flags to `alpha` clusters, and doesn't support the creation of mixed protocol services of type `LoadBalancer`. To configure an external load balancer for GKE, you need to: - -1. Reserve a public static IP address. -2. Create two `LoadBalancer` services, one for TCP and one for UDP. -3. Assign the public static IP address to the `loadBalancerIP` field. - -An example of the two load balancer services described above looks as follows: - -```yaml -# selectors and labels removed for clarity -apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$ - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - --- - apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$-udp - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http3 - port: 443 # Default support for HTTP/3 requires you to use 443 for the external client-facing port. - targetPort: 8443 - protocol: UDP - -``` - -In the above example, GKE generates two `LoadBalancer` services, one for UDP and the other for TCP. diff --git a/content/en/docs/3.0/howtos/index.md b/content/en/docs/3.0/howtos/index.md deleted file mode 100644 index f16cdd46..00000000 --- a/content/en/docs/3.0/howtos/index.md +++ /dev/null @@ -1,25 +0,0 @@ -# "How-to" guides - -These guides are designed to help users quickly accomplish common tasks. The guides assume a certain level of understanding of $productName$. Many of these guides are contributed by third parties; we welcome contributions via Pull Request at https://github.com/emissary-ingress/emissary. - -* Integrating with Service Mesh. $productName$ natively integrates with many service meshes. - * [HashiCorp Consul](consul) - * [Istio](istio) - * [Linkerd](linkerd2) -* Distributed tracing. $productName$ natively supports a number of distributed tracing systems to enable developers to visualize request flow in microservice and service-oriented architectures. - * [Datadog](tracing-datadog) - * [Zipkin](tracing-zipkin) -* Monitoring. $productName$ integrates with a number of different monitoring/metrics providers. - * [Prometheus](prometheus) -* [Developing Custom Filters](filter-dev-guide) -* Frameworks and Protocols. $productName$ supports a wide range of protocols and cloud-native frameworks. - * [gRPC](grpc) - * [Knative Serverless Framework](knative) - * [WebSockets](websockets) -* Security. $productName$ supports a number of strategies for securing Kubernetes services. - * [Protecting the Diagnostics Interface](protecting-diag-access) - * [HTTPS and TLS termination](tls-termination) - * [Certificate Manager](cert-manager) can be used to automatically obtain and renew TLS certificates; $AESproductName$ natively integrates this functionality. - * [Client Certificate Validation](client-cert-validation) - * [Basic Authentication](basic-auth) is a tutorial on how to use the external authentication API to code your own authentication service. - * [Basic Rate Limiting](rate-limiting-tutorial) diff --git a/content/en/docs/3.0/howtos/istio.md b/content/en/docs/3.0/howtos/istio.md deleted file mode 100644 index 6fa74fcf..00000000 --- a/content/en/docs/3.0/howtos/istio.md +++ /dev/null @@ -1,445 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Istio integration - -$productName$ and Istio: Edge Proxy and Service Mesh together in one. $productName$ is deployed at the edge of your network and routes incoming traffic to your internal services (aka "north-south" traffic). [Istio](https://istio.io/) is a service mesh for microservices, and is designed to add application-level Layer (L7) observability, routing, and resilience to service-to-service traffic (aka "east-west" traffic). Both Istio and $productName$ are built using [Envoy](https://www.envoyproxy.io). - -$productName$ and Istio can be deployed together on Kubernetes. In this configuration, $productName$ manages -traditional edge functions such as authentication, TLS termination, and edge routing. Istio mediates communication -from $productName$ to services, and communication between services. - -This allows the operator to have the best of both worlds: a high performance, modern edge service ($productName$) combined with a state-of-the-art service mesh (Istio). While Istio has introduced a [Gateway](https://istio.io/latest/docs/tasks/traffic-management/ingress/ingress-control/#configuring-ingress-using-an-istio-gateway) abstraction, $productName$ still has a much broader feature set for edge routing than Istio. For more on this topic, see our blog post on [API Gateway vs Service Mesh](https://blog.getambassador.io/api-gateway-vs-service-mesh-104c01fa4784). - -This guide explains how to take advantage of both $productName$ and Istio to have complete control and observability over how requests are made in your cluster: - -- [Install Istio](#install-istio) and configure auto-injection -- [Install $productName$ with Istio integration](#install-edge) -- [Configure an mTLS `TLSContext`](#configure-an-mtls-tlscontext) -- [Route to services using mTLS](#route-to-services-using-mtls) - -If desired, you may also - -- [Enable strict mTLS](#enable-strict-mtls) -- [Configure Prometheus metrics collection](#configure-prometheus-metrics-collection) -- [Configure Istio distributed tracing](#configure-istio-distributed-tracing) - -To follow this guide, you need: - -- A Kubernetes cluster version 1.15 and above -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- Istio version 1.10 or higher - -## Install Istio - -Start by [installing Istio](https://istio.io/docs/setup/getting-started/). Any supported installation method for -Istio will work for use with $productName$. - -### Configure Istio Auto-Injection - -Istio functions by supplying a sidecar container running Envoy with every service in the mesh (including -$productName$). The sidecar is what enforces Istio policies for traffic to and from the service, notably -including mTLS encryption and certificate handling. As such, it is very important that the sidecar be -correctly supplied for every service in the mesh! - -While it is possible to manage sidecars by hand, it is far easier to allow Istio to automatically inject -the sidecar as necessary. To do this, set the `istio-injection` label on each Kubernetes Namespace for -which you want auto-injection: - -```yaml -kubectl label namespace $namespace istio-injection=enabled --overwrite -``` - - - The following example uses the `istio-injection` label to arrange for auto-injection in the - `$productNamespace$` Namespace below. You can manage sidecar injection by hand if you wish; what - is critical is that every service that participates in the Istio mesh have the Istio - sidecar. - - -## Install $productName$ with Istio Integration - -Properly integrating $productName$ with Istio provides support for: - -* [Mutual TLS (mTLS)](../../topics/running/tls/mtls/), with certificates managed by Istio, to allow end-to-end encryption -for east-west traffic; -* Automatic generation of Prometheus metrics for services; and -* Istio distributed tracing for end-to-end observability. - -The simplest way to enable everything is to install $productName$ using [Helm](https://helm.sh), though -you can use manual installation with YAML if you wish. - -### Installation with Helm (Recommended) - -To install with Helm, write the following YAML to a file called `istio-integration.yaml`: - -```yaml -# Listeners are required in $productName$ 2.0. -# This will create the two default Listeners for HTTP on port 8080 and HTTPS on port 8443. -createDefaultListeners: true - -# These are annotations that will be added to the $productName$ pods. -podAnnotations: - # These first two annotations tell Istio not to try to do port management for the - # $productName$ pod itself. Though these annotations are placed on the $productName$ - # pods, they are interpreted by Istio. - traffic.sidecar.istio.io/includeInboundPorts: "" # do not intercept any inbound ports - traffic.sidecar.istio.io/includeOutboundIPRanges: "" # do not intercept any outbound traffic - - # We use proxy.istio.io/config to tell the Istio proxy to write newly-generated mTLS certificates - # into /etc/istio-certs, which will be mounted below. Though this annotation is placed on the - # $productName$ pods, it is interpreted by Istio. - proxy.istio.io/config: | - proxyMetadata: - OUTPUT_CERTS: /etc/istio-certs - - # We use sidecar.istio.io/userVolumeMount to tell the Istio sidecars to mount the istio-certs - # volume at /etc/istio-certs, allowing the sidecars to see the generated certificates. Though - # this annotation is placed on the $productName$ pods, it is interpreted by Istio. - sidecar.istio.io/userVolumeMount: '[{"name": "istio-certs", "mountPath": "/etc/istio-certs"}]' - -# We define a single storage volume called "istio-certs". It starts out empty, and Istio -# uses it to communicate mTLS certs between the Istio proxy and the Istio sidecars (see the -# annotations above). -volumes: - - emptyDir: - medium: Memory - name: istio-certs - -# We also tell $productName$ to mount the "istio-certs" volume at /etc/istio-certs in the -# $productName$ pod. This gives $productName$ access to the mTLS certificates, too. -volumeMounts: - - name: istio-certs - mountPath: /etc/istio-certs/ - readOnly: true - -# Finally, we need to set some environment variables for $productName$. -env: - # AMBASSADOR_ISTIO_SECRET_DIR tells $productName$ to look for Istio mTLS certs, and to - # make them available as a secret named "istio-certs". - AMBASSADOR_ISTIO_SECRET_DIR: "/etc/istio-certs" - - # AMBASSADOR_ENVOY_BASE_ID is set to prevent collisions with the Istio sidecar's Envoy, - # which runs with base-id 0. - AMBASSADOR_ENVOY_BASE_ID: "1" -``` - -To install $productName$ with Helm, use these values to configure Istio integration: - -1. Create the `$productNamespace$` Namespace: - - ```yaml - kubectl create namespace $productNamespace$ - ``` - -2. Enable Istio auto-injection for it: - - ```yaml - kubectl label namespace $productNamespace$ istio-injection=enabled --overwrite - ``` - -3. Make sure the Helm repo is configured: - - ```bash - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - -4. Use Helm to install $productName$ in $productNamespace$: - - ```bash - helm install $productHelmName$ --namespace $productNamespace$ -f istio-integration.yaml datawire/$productHelmName$ && \ - kubectl -n $productNamespace$ wait --for condition=available --timeout=90s deploy -lapp.kubernetes.io/instance=$productDeploymentName$ - ``` - -### Installation Using YAML - -To install using YAML files, you need to manually incorporate the contents of the `istio-integration.yaml` -file shown above into your deployment YAML: - -* `pod-annotations` should be configured as Kubernetes `annotations` on the $productName$ Pods; -* `volumes`, `volumeMounts`, and `env` contents should be included in the $productDeploymentName$ Deployment; and -* you must also label the $productNamespace$ Namespace for auto-injection as described above. - -### Configuring an Existing Installation - -If you have already installed $productName$ and want to enable Istio: - -1. Install Istio. -2. Label the $productNamespace$ namespace for Istio auto-injection, as above. -2. Edit the $productName$ Deployments to contain the `annotations`, `volumes`, `volumeMounts`, and `env` elements - shown above. - * If you installed with Helm, you can use `helm upgrade` with `-f istio-integration.yaml` to modify the - installation for you. -3. Restart the $productName$ pods. - -## Configure an mTLS `TLSContext` - -After configuring $productName$ for Istio integration, the Istio mTLS certificates are available within -$productName$: - -- Both the `istio-proxy` sidecar and $productName$ mount the `istio-certs` volume at `/etc/istio-certs`. -- The `istio-proxy` sidecar saves the mTLS certificates into `/etc/istio-certs` (per the `OUTPUT_CERTS` - environment variable). -- $productName$ reads the mTLS certificates from `/etc/istio-certs` (per the `AMBASSADOR_ISTIO_SECRET_DIR` - environment variable) and creates a Secret named `istio-certs`. - - - At present, the Secret name istio-certs cannot be changed. - - -To make use of the `istio-certs` Secret, create a `TLSContext` referencing it: - - ```shell - $ kubectl apply -f - < - You must either explicitly specify port 80 in your 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 - <This guide applies to $OSSproductName$. It will not work correctly -on $AESproductName$. - -$productName$ can validate incoming requests before routing them to a backing service. In this tutorial, we'll configure $productName$ to use a simple third party rate limit service. (If you don't want to implement your own rate limiting service, $AESproductName$ integrates a [powerful, flexible rate limiting service](/docs/edge-stack/latest/topics/using/rate-limits/rate-limits/).) - -## Before you get started - -This tutorial assumes you have already followed the $productName$ [Installation](../../topics/install/) and [Quickstart Tutorial](../../tutorials/quickstart-demo) guides. If you haven't done that already, you should do so now. - -Once completed, you'll have a Kubernetes cluster running $productName$ and the Quote service. Let's walk through adding rate limiting to this setup. - -## 1. Deploy the rate limit service - -$productName$ delegates the actual rate limit logic to a third party service. We've written a [simple rate limit service](https://github.com/emissary-ingress/emissary/tree/v2.1.0/docker/test-ratelimit) that: - -- listens for requests on port 5000; -- handles gRPC `shouldRateLimit` requests; -- allows requests with the `x-ambassador-test-allow: "true"` header; and -- marks all other requests as `OVER_LIMIT`; - -Here's the YAML we'll start with: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: RateLimitService -metadata: - name: ratelimit -spec: - service: "example-rate-limit:5000" ---- -apiVersion: v1 -kind: Service -metadata: - name: example-rate-limit -spec: - type: ClusterIP - selector: - app: example-rate-limit - ports: - - port: 5000 - name: http-example-rate-limit - targetPort: http-api ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: example-rate-limit -spec: - replicas: 1 - strategy: - type: RollingUpdate - selector: - matchLabels: - app: example-rate-limit - template: - metadata: - labels: - app: example-rate-limit - spec: - containers: - - name: example-rate-limit - image: datawire/test_services:test-ratelimit:0.0.4 - imagePullPolicy: Always - ports: - - name: http-api - containerPort: 5000 - resources: - limits: - cpu: "0.1" - memory: 100Mi -``` - -This configuration tells $productName$ about the rate limit service, notably that it is serving requests at `example-rate-limit:5000`. $productName$ will see the `RateLimitService` and reconfigure itself within a few -seconds, allowing incoming requests to be rate-limited. - -Note that you can configure the `RateLimitService` to use a specific label `domain`. -If `domain` is not specified (which is the situation here), the default is `ambassador`. - -If $productName$ cannot contact the rate limit service, it will allow the request to be processed as if there were no rate limit service configuration. - -## 2. Configure $productName$ Mappings - -$productName$ only validates requests on `Mapping`s which set labels to use for rate limiting, -so you'll need to apply `labels` to your `Mapping`s to enable rate limiting. For more information -on the labelling process, see the [Rate Limits configuration documentation](../../topics/using/rate-limits/). - - - These labels require Mapping resources with apiVersion - getambassador.io/v2 or newer — if you're updating an old installation, check the - apiVersion! - - -If $productName$ cannot contact the rate limit service, it will allow the request to be processed as if there were no rate limit service configuration. - -Replace the label that is applied to the `service-backend` with: - -```yaml -labels: - ambassador: - - request_label_group: - - x-ambassador-test-allow: - request_headers: - key: "x-ambassador-test-allow" - header_name: "x-ambassador-test-allow" -``` - -so the `Mapping` definition will now look like this: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: "*" - prefix: /backend/ - service: quote - labels: - ambassador: - - request_label_group: - - x-ambassador-test-allow: - request_headers: - key: "x-ambassador-test-allow" - header_name: "x-ambassador-test-allow" -``` - - - -Note that the `key` could be anything you like, but our example rate limiting service expects it to -match the name of the header. Also note that since our `RateLimitService` expects to use labels in the -`ambassador` domain, our `Mapping` must match. - -## 2. Test rate limiting - -If we `curl` to a rate-limited URL: - -``` -$ curl -Lv -H "x-ambassador-test-allow: probably" $AMBASSADORURL/backend/ -``` - -We get a 429, since we are limited. - -``` -HTTP/1.1 429 Too Many Requests -content-type: text/html; charset=utf-8 -content-length: 0 -``` - -If we set the correct header value to the service request, we will get a quote successfully: - -``` -$ curl -Lv -H "x-ambassador-test-allow: true" $AMBASSADORURL/backend/ - -TCP_NODELAY set -* Connected to 35.196.173.175 (35.196.173.175) port 80 (#0) -> GET /backed HTTP/1.1 -> Host: 35.196.173.175 -> User-Agent: curl/7.54.0 -> Accept: */* -> -< HTTP/1.1 200 OK -< content-type: application/json -< date: Thu, 23 May 2019 15:25:06 GMT -< content-length: 172 -< x-envoy-upstream-service-time: 0 -< server: envoy -< -{ - "server": "humble-blueberry-o2v493st", - "quote": "Nihilism gambles with lives, happiness, and even destiny itself!", - "time": "2019-05-23T15:25:06.544417902Z" -* Connection #0 to host 54.165.128.189 left intact -} -``` - -## More - -For more details about configuring the external rate limit service, read the [rate limit documentation](../../topics/using/rate-limits/). diff --git a/content/en/docs/3.0/howtos/route.md b/content/en/docs/3.0/howtos/route.md deleted file mode 100644 index b2d9dc0f..00000000 --- a/content/en/docs/3.0/howtos/route.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -description: "$productName$ uses the Mapping resource to map a resource, like a URL prefix, to a Kubernetes service or web service." ---- - -import Alert from '@material-ui/lab/Alert'; - -# Get traffic from the edge - -
-

Contents

- -* [Examples](#examples) -* [Applying a Mapping Resource](#applying-a-mapping-resouce) -* [Resources](#resources) -* [Services](#services) -* [Extending Mappings](#extending-mappings) -* [Best Practices](#best-practices) -* [What's next?](#img-classos-logo-srcimageslogopng-whats-next) - -
- -The core $productName$ resource used to manage cluster ingress is the `Mapping` resource. - -**A `Mapping` resource routes a URL path (or prefix) to a service (either a Kubernetes service or other web service).** - - - Remember that Listener and Host resources are  - required for a functioning $productName$ installation that can route traffic!
- Learn more about Listener.
- Learn more about Host. - - -## Examples - -This `Mapping` would route requests to `https:///webapp/` to the `webapp-svc` Service. **This is not a -complete example on its own; see below.** - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: webapp-mapping -spec: - prefix: /webapp/ - service: webapp-svc -``` - -| Name | Type | Description | -| :--- | :--- | :--- | -| `metadata.name` | String | Identifies the Mapping. | -| `spec.prefix` | String | The URL prefix identifying your resource. [See below](#resources) on how $productName$ handles resources. | -| `spec.service` | String | The service handling the resource. If a Kubernetes service, it must include the namespace (in the format `service.namespace`) if the service is in a different namespace than $productName$. [See below](#services) on service name formatting.| - -Here's another example using a web service that maps requests to `/httpbin/` to `http://httpbin.org` (again, **this is not a -complete example on its own; see below**): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin-mapping -spec: - prefix: /httpbin/ - service: http://httpbin.org - hostname: '*' -``` - -### Complete example configuration - -For demonstration purposes, here's a possible way of combining a `Listener`, a `Host`, and both `Mapping`s above that is complete and functional: - -- it will accept HTTP or HTTPS on port 8443; -- $productName$ is terminating TLS; -- HTTPS to `foo.example.com` will be routed as above; -- HTTP to `foo.example.com` will be redirected to HTTPS; -- HTTP or HTTPS to other hostnames will be rejected; and -- the associations between the `Listener`, the `Host`, and the `Mappings` use Kubernetes `label`s. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: foo-example-secret -data: - tls.crt: -certificate PEM- - tls.key: -secret key PEM- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-8443 -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: - selector: - matchLabels: - exampleName: basic-https ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host - labels: - exampleName: basic-https -spec: - hostname: "foo.example.com" - tlsSecret: - name: foo-example-secret - selector: - matchLabels: - exampleName: basic-https ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: webapp-mapping - labels: - exampleName: basic-https -spec: - prefix: /webapp/ - service: webapp-svc - hostname: 'foo.example.com' ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin-mapping - labels: - exampleName: basic-https -spec: - prefix: /httpbin/ - service: http://httpbin.org - hostname: 'foo.example.com' - -``` - -Note the addition of `label`s and `selector`s to explicitly specify which resources should associate in this example. - - - Learn more about Listener.
- Learn more about Host. - - -## Applying a Mapping resource - -A Mapping resource can be managed using the same workflow as any other Kubernetes resources (like a Service or Deployment). For example, if the above Mapping is saved into a file called `httpbin-mapping.yaml`, the following command will apply the configuration directly to $productName$: - -``` -kubectl apply -f httpbin-mapping.yaml -``` - -For production use, best practice is to store the file in a version control system and apply the changes with a continuous deployment pipeline. The Ambassador Operating Model provides more detail. - -## Resources - -To $productName$, a resource is a group of one or more URLs that all share a common prefix in the URL path. For example, these URLs all share the `/resource1/` path prefix, so `/resource1/` can be considered a single resource: - -* `https://ambassador.example.com/resource1/foo` -* `https://ambassador.example.com/resource1/bar` -* `https://ambassador.example.com/resource1/baz/zing` - -On the other hand, these URLs share only the prefix `/` -- you _could_ tell $productName$ to treat them as a single resource, but it's probably not terribly useful. - -* `https://ambassador.example.com/resource1/foo` -* `https://ambassador.example.com/resource2/bar` -* `https://ambassador.example.com/resource3/baz/zing` - -Note that the length of the prefix doesn't matter; a prefix like `/v1/this/is/my/very/long/resource/name/` is valid. - -Also note that $productName$ does not actually require the prefix to start and end with `/` -- however, in practice, it's a good idea. Specifying a prefix of `/man` would match all of the following, which probably is not what was intended: - -* `https://ambassador.example.com/man/foo` -* `https://ambassador.example.com/mankind` -* `https://ambassador.example.com/man-it-is/really-hot-today` - -## Services - -$productName$ routes traffic to a service. A service is defined as `[scheme://]service[.namespace][:port]`. Everything except for the service is optional. - -- `scheme` can be either `http` or `https`; if not present, the default is `http`. -- `service` is the name of a service (typically the service name in Kubernetes or Consul); it is not allowed to contain the `.` character. -- `namespace` is the namespace in which the service is running. Starting with $productName$ 1.0.0, if not supplied, it defaults to the namespace in which the Mapping resource is defined. The default behavior can be configured using the [Module resource](../../topics/running/ambassador). When using a Consul resolver, `namespace` is not allowed. -- `port` is the port to which a request should be sent. If not specified, it defaults to `80` when the scheme is `http` or `443` when the scheme is `https`. Note that the [resolver](../../topics/running/resolvers) may return a port in which case the `port` setting is ignored. - -While using service.namespace.svc.cluster.local may work for Kubernetes resolvers, the preferred syntax is service.namespace. - - -## Extending Mappings - -Mapping resources support a rich set of annotations to customize the specific routing behavior. Here's an example service for implementing the [CQRS pattern](https://docs.microsoft.com/en-us/azure/architecture/patterns/cqrs) (using HTTP): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-get -spec: - prefix: /cqrs/ - method: GET - service: getcqrs - hostname: '*' ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-put -spec: - prefix: /cqrs/ - method: PUT - service: putcqrs - hostname: '*' -``` - -## Best Practices - -$productName$'s configuration is assembled from multiple YAML blocks which are managed by independent application teams. This implies that certain best practices should be followed. - -#### $productName$'s configuration should be under version control. - -While you can always read back the $productName$'s configuration from Kubernetes or its diagnostic service, the $productName$ will not do versioning for you. - -#### $productName$ tries to not start with a broken configuration, but it's not perfect. - -Gross errors will result in the $productName$ refusing to start, in which case `kubectl logs` will be helpful. However, it's always possible to map a resource to the wrong service, or use the wrong `rewrite` rules. $productName$ can't detect that on its own, although its [diagnostic service](../../topics/running/diagnostics/) can help you figure it out. - -#### Be careful of mapping collisions. - -If two different developers try to map `/myservice/` to something, this can lead to unexpected behavior. $productName$'s [canary deployment](../../topics/using/canary/) logic means that it's more likely that traffic will be split between them than that it will throw an error -- again, the diagnostic service can help you here. - -#### Unless specified, mapping attributes cannot be applied to any other resource type. - -## 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/content/en/docs/3.0/howtos/tls-termination.md b/content/en/docs/3.0/howtos/tls-termination.md deleted file mode 100644 index d634c76b..00000000 --- a/content/en/docs/3.0/howtos/tls-termination.md +++ /dev/null @@ -1,195 +0,0 @@ -# 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 - selector: - matchLabels: - hostname: wildcard-host -``` - -**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/content/en/docs/3.0/howtos/tracing-datadog.md b/content/en/docs/3.0/howtos/tracing-datadog.md deleted file mode 100644 index d627e29f..00000000 --- a/content/en/docs/3.0/howtos/tracing-datadog.md +++ /dev/null @@ -1,63 +0,0 @@ -# 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/content/en/docs/3.0/howtos/tracing-zipkin.md b/content/en/docs/3.0/howtos/tracing-zipkin.md deleted file mode 100644 index 37ddc902..00000000 --- a/content/en/docs/3.0/howtos/tracing-zipkin.md +++ /dev/null @@ -1,129 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Distributed tracing with Zipkin - -In this tutorial, we'll configure $productName$ to initiate a trace on some sample requests, and use Zipkin 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. Deploy Zipkin - -In this tutorial, you will use a simple deployment of the open-source [Zipkin](https://github.com/openzipkin/zipkin/wiki) distributed tracing system to store and visualize $productName$-generated traces. The trace data will be stored in memory within the Zipkin container, and you will be able to explore the traces via the Zipkin web UI. - -First, add the following YAML to a file named `zipkin.yaml`. This configuration will create a Zipkin Deployment that uses the [openzipkin/zipkin](https://hub.docker.com/r/openzipkin/zipkin/) container image and also an associated Service. We will also include a `TracingService` that configures $productName$ to use the Zipkin service (running on the default port of 9411) to provide tracing support. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TracingService -metadata: - name: tracing -spec: - service: "zipkin:9411" - driver: zipkin - config: {} ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: zipkin -spec: - replicas: 1 - selector: - matchLabels: - app: zipkin - template: - metadata: - labels: - app: zipkin - spec: - containers: - - name: zipkin - image: openzipkin/zipkin - env: - # note: in-memory storage holds all data in memory, purging older data upon a span limit. - # you should use a proper storage in production environments - - name: STORAGE_TYPE - value: mem ---- -apiVersion: v1 -kind: Service -metadata: - labels: - name: zipkin - name: zipkin -spec: - ports: - - port: 9411 - targetPort: 9411 - selector: - app: zipkin -``` - -Next, deploy this configuration into your cluster: - -``` -$ kubectl apply -f zipkin.yaml -``` - -As a final step we want to restart $productName$ as this is necessary to add the tracing header. This command will restart all the Pods (assuming $productName$ is installed in the ambassador namespace): - -``` -$ kubectl -n ambassador rollout restart deploy -``` - - Restarting $productName$ is required after deploying a Tracing Service for changes to take effect. - - -## 2. 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/backend/ -``` - -## 3. Test traces - -To test things out, we'll need to access the Zipkin UI. If you're on Kubernetes, get the name of the Zipkin pod: - -``` -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -ambassador-5ffcfc798-c25dc 2/2 Running 0 1d -prometheus-prometheus-0 2/2 Running 0 113d -zipkin-868b97667c-58v4r 1/1 Running 0 2h -``` - -And then use `kubectl port-forward` to access the pod: - -``` -$ kubectl port-forward zipkin-868b97667c-58v4r 9411 -``` - -Open your web browser to `http://localhost:9411` for the Zipkin UI. - -If you're on `minikube` you can access the `NodePort` directly, and this ports number can be obtained via the `minikube services list` command. If you are using `Docker for Mac/Windows`, you can use the `kubectl get svc` command to get the same information. - -``` -$ minikube service list -|-------------|----------------------|-----------------------------| -| NAMESPACE | NAME | URL | -|-------------|----------------------|-----------------------------| -| default | ambassador-admin | http://192.168.99.107:30319 | -| default | ambassador | http://192.168.99.107:31893 | -| default | zipkin | http://192.168.99.107:31043 | -|-------------|----------------------|-----------------------------| -``` - -Open your web browser to the Zipkin dashboard `http://192.168.99.107:31043/zipkin/`. - -In the Zipkin UI, click on the "Find Traces" button to get a listing instrumented traces. Each of the traces that are displayed can be clicked on, which provides further information about each span and associated metadata. - -## Learn more - -For more details about configuring the external tracing service, read the documentation on [external tracing](../../topics/running/services/tracing-service). diff --git a/content/en/docs/3.0/howtos/websockets.md b/content/en/docs/3.0/howtos/websockets.md deleted file mode 100644 index 25cac7da..00000000 --- a/content/en/docs/3.0/howtos/websockets.md +++ /dev/null @@ -1,43 +0,0 @@ -# WebSocket connections - -$productName$ makes it easy to access your services from outside your -application, and this includes services that use WebSockets. Only a -small amount of additional configuration is required, which is as -simple as telling the Mapping to allow "upgrading" from the HTTP protocol to -the "websocket" protocol: - -```yaml -allow_upgrade: -- websocket -``` - -## Example WebSocket service - -The example configuration below demonstrates the addition of the `allow_upgrade:` attribute to support websockets. The use of `use_websocket` is now deprecated. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: my-service-mapping -spec: - hostname: "*" - prefix: /my-service/ - service: my-service - allow_upgrade: - - websocket - ---- -kind: Service -apiVersion: v1 -metadata: - name: my-service -spec: - selector: - app: MyApp - ports: - - protocol: TCP - port: 80 - targetPort: 9376 -``` diff --git a/content/en/docs/3.0/images/Auth0_JWT.png b/content/en/docs/3.0/images/Auth0_JWT.png deleted file mode 100644 index e18155f5..00000000 Binary files a/content/en/docs/3.0/images/Auth0_JWT.png and /dev/null differ diff --git a/content/en/docs/3.0/images/Auth0_domain_clientID.png b/content/en/docs/3.0/images/Auth0_domain_clientID.png deleted file mode 100644 index a7f8edf6..00000000 Binary files a/content/en/docs/3.0/images/Auth0_domain_clientID.png and /dev/null differ diff --git a/content/en/docs/3.0/images/Auth0_method_callback_origins.png b/content/en/docs/3.0/images/Auth0_method_callback_origins.png deleted file mode 100644 index 8d31138e..00000000 Binary files a/content/en/docs/3.0/images/Auth0_method_callback_origins.png and /dev/null differ diff --git a/content/en/docs/3.0/images/aes-success.png b/content/en/docs/3.0/images/aes-success.png deleted file mode 100644 index 66f28d3f..00000000 Binary files a/content/en/docs/3.0/images/aes-success.png and /dev/null differ diff --git a/content/en/docs/3.0/images/ambassador-arch.png b/content/en/docs/3.0/images/ambassador-arch.png deleted file mode 100644 index 5a5cb652..00000000 Binary files a/content/en/docs/3.0/images/ambassador-arch.png and /dev/null differ diff --git a/content/en/docs/3.0/images/ambassador-logo.svg b/content/en/docs/3.0/images/ambassador-logo.svg deleted file mode 100644 index 1f0e06a8..00000000 --- a/content/en/docs/3.0/images/ambassador-logo.svg +++ /dev/null @@ -1,49 +0,0 @@ - - - - ambassador logo@1x - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.0/images/ambassador_oidc_flow.jpg b/content/en/docs/3.0/images/ambassador_oidc_flow.jpg deleted file mode 100644 index 4f1c0c7e..00000000 Binary files a/content/en/docs/3.0/images/ambassador_oidc_flow.jpg and /dev/null differ diff --git a/content/en/docs/3.0/images/apple.png b/content/en/docs/3.0/images/apple.png deleted file mode 100644 index 8b8277f1..00000000 Binary files a/content/en/docs/3.0/images/apple.png and /dev/null differ diff --git a/content/en/docs/3.0/images/auth-flow.png b/content/en/docs/3.0/images/auth-flow.png deleted file mode 100644 index e1ba4387..00000000 Binary files a/content/en/docs/3.0/images/auth-flow.png and /dev/null differ diff --git a/content/en/docs/3.0/images/authentication-icon.svg b/content/en/docs/3.0/images/authentication-icon.svg deleted file mode 100644 index 342e8a3d..00000000 --- a/content/en/docs/3.0/images/authentication-icon.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_897228_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.0/images/blackbird.png b/content/en/docs/3.0/images/blackbird.png deleted file mode 100644 index 1f10e5cc..00000000 Binary files a/content/en/docs/3.0/images/blackbird.png and /dev/null differ diff --git a/content/en/docs/3.0/images/canary-release-overview.png b/content/en/docs/3.0/images/canary-release-overview.png deleted file mode 100644 index c683a23d..00000000 Binary files a/content/en/docs/3.0/images/canary-release-overview.png and /dev/null differ diff --git a/content/en/docs/3.0/images/configure-icon.svg b/content/en/docs/3.0/images/configure-icon.svg deleted file mode 100644 index 0f556840..00000000 --- a/content/en/docs/3.0/images/configure-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_858572_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.0/images/consul-ambassador.png b/content/en/docs/3.0/images/consul-ambassador.png deleted file mode 100644 index c4911624..00000000 Binary files a/content/en/docs/3.0/images/consul-ambassador.png and /dev/null differ diff --git a/content/en/docs/3.0/images/container-inner-dev-loop.png b/content/en/docs/3.0/images/container-inner-dev-loop.png deleted file mode 100644 index 06586cd6..00000000 Binary files a/content/en/docs/3.0/images/container-inner-dev-loop.png and /dev/null differ diff --git a/content/en/docs/3.0/images/datawire-logo.svg b/content/en/docs/3.0/images/datawire-logo.svg deleted file mode 100644 index fb45872c..00000000 --- a/content/en/docs/3.0/images/datawire-logo.svg +++ /dev/null @@ -1,27 +0,0 @@ - - - - Group 3 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.0/images/diagnostics-example.png b/content/en/docs/3.0/images/diagnostics-example.png deleted file mode 100644 index 6c825b0c..00000000 Binary files a/content/en/docs/3.0/images/diagnostics-example.png and /dev/null differ diff --git a/content/en/docs/3.0/images/diagnostics.png b/content/en/docs/3.0/images/diagnostics.png deleted file mode 100644 index 29248703..00000000 Binary files a/content/en/docs/3.0/images/diagnostics.png and /dev/null differ diff --git a/content/en/docs/3.0/images/docker-compose.png b/content/en/docs/3.0/images/docker-compose.png deleted file mode 100644 index b8829521..00000000 Binary files a/content/en/docs/3.0/images/docker-compose.png and /dev/null differ diff --git a/content/en/docs/3.0/images/docker.png b/content/en/docs/3.0/images/docker.png deleted file mode 100644 index 1f35e5ea..00000000 Binary files a/content/en/docs/3.0/images/docker.png and /dev/null differ diff --git a/content/en/docs/3.0/images/edge-stack-1.13.4.png b/content/en/docs/3.0/images/edge-stack-1.13.4.png deleted file mode 100644 index 954ac1a9..00000000 Binary files a/content/en/docs/3.0/images/edge-stack-1.13.4.png and /dev/null differ diff --git a/content/en/docs/3.0/images/edge-stack-1.13.7-json-logging.png b/content/en/docs/3.0/images/edge-stack-1.13.7-json-logging.png deleted file mode 100644 index 4a47cbdf..00000000 Binary files a/content/en/docs/3.0/images/edge-stack-1.13.7-json-logging.png and /dev/null differ diff --git a/content/en/docs/3.0/images/edge-stack-1.13.7-memory.png b/content/en/docs/3.0/images/edge-stack-1.13.7-memory.png deleted file mode 100644 index 9c415ba3..00000000 Binary files a/content/en/docs/3.0/images/edge-stack-1.13.7-memory.png and /dev/null differ diff --git a/content/en/docs/3.0/images/edge-stack-1.13.7-tcpmapping-consul.png b/content/en/docs/3.0/images/edge-stack-1.13.7-tcpmapping-consul.png deleted file mode 100644 index c455a47f..00000000 Binary files a/content/en/docs/3.0/images/edge-stack-1.13.7-tcpmapping-consul.png and /dev/null differ diff --git a/content/en/docs/3.0/images/edge-stack-1.13.8-cloud-bugfix.png b/content/en/docs/3.0/images/edge-stack-1.13.8-cloud-bugfix.png deleted file mode 100644 index 6beaf653..00000000 Binary files a/content/en/docs/3.0/images/edge-stack-1.13.8-cloud-bugfix.png and /dev/null differ diff --git a/content/en/docs/3.0/images/emissary-1.13.10-cors-origin.png b/content/en/docs/3.0/images/emissary-1.13.10-cors-origin.png deleted file mode 100644 index b7538e5f..00000000 Binary files a/content/en/docs/3.0/images/emissary-1.13.10-cors-origin.png and /dev/null differ diff --git a/content/en/docs/3.0/images/fast-icon.svg b/content/en/docs/3.0/images/fast-icon.svg deleted file mode 100644 index 354542ee..00000000 --- a/content/en/docs/3.0/images/fast-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1187990_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.0/images/features-icons/basic-authentication.svg b/content/en/docs/3.0/images/features-icons/basic-authentication.svg deleted file mode 100644 index 2bd19edf..00000000 --- a/content/en/docs/3.0/images/features-icons/basic-authentication.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_897228_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.0/images/features-icons/canary-release.svg b/content/en/docs/3.0/images/features-icons/canary-release.svg deleted file mode 100644 index f8de57d9..00000000 --- a/content/en/docs/3.0/images/features-icons/canary-release.svg +++ /dev/null @@ -1,27 +0,0 @@ - - - - Group 25 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.0/images/features-icons/cors.svg b/content/en/docs/3.0/images/features-icons/cors.svg deleted file mode 100644 index e559d924..00000000 --- a/content/en/docs/3.0/images/features-icons/cors.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_111967_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.0/images/features-icons/datadog.png b/content/en/docs/3.0/images/features-icons/datadog.png deleted file mode 100644 index eea05f8c..00000000 Binary files a/content/en/docs/3.0/images/features-icons/datadog.png and /dev/null differ diff --git a/content/en/docs/3.0/images/features-icons/datadog.svg b/content/en/docs/3.0/images/features-icons/datadog.svg deleted file mode 100644 index e46e8118..00000000 --- a/content/en/docs/3.0/images/features-icons/datadog.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Screen Shot 2018-04-05 at 8.22.25 AM - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.0/images/features-icons/diagnostics.svg b/content/en/docs/3.0/images/features-icons/diagnostics.svg deleted file mode 100644 index 940e1bc2..00000000 --- a/content/en/docs/3.0/images/features-icons/diagnostics.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_196445_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.0/images/features-icons/distributed-tracing.png b/content/en/docs/3.0/images/features-icons/distributed-tracing.png deleted file mode 100644 index 6b69e28c..00000000 Binary files a/content/en/docs/3.0/images/features-icons/distributed-tracing.png and /dev/null differ diff --git a/content/en/docs/3.0/images/features-icons/grpc.png b/content/en/docs/3.0/images/features-icons/grpc.png deleted file mode 100644 index b2f5a0d9..00000000 Binary files a/content/en/docs/3.0/images/features-icons/grpc.png and /dev/null differ diff --git a/content/en/docs/3.0/images/features-icons/prometheus.svg b/content/en/docs/3.0/images/features-icons/prometheus.svg deleted file mode 100644 index d5252a66..00000000 --- a/content/en/docs/3.0/images/features-icons/prometheus.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - prometheus_logo_grey - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.0/images/features-icons/rate-limiting.svg b/content/en/docs/3.0/images/features-icons/rate-limiting.svg deleted file mode 100644 index f1b6eacb..00000000 --- a/content/en/docs/3.0/images/features-icons/rate-limiting.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - Group 10 - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.0/images/features-icons/regex-routing.svg b/content/en/docs/3.0/images/features-icons/regex-routing.svg deleted file mode 100644 index 113b53b5..00000000 --- a/content/en/docs/3.0/images/features-icons/regex-routing.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_699774_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.0/images/features-icons/request-transformers.svg b/content/en/docs/3.0/images/features-icons/request-transformers.svg deleted file mode 100644 index 0b13e2dc..00000000 --- a/content/en/docs/3.0/images/features-icons/request-transformers.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_96239_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.0/images/features-icons/shadowing.svg b/content/en/docs/3.0/images/features-icons/shadowing.svg deleted file mode 100644 index 9e85eee1..00000000 --- a/content/en/docs/3.0/images/features-icons/shadowing.svg +++ /dev/null @@ -1,15 +0,0 @@ - - - - shadow - Created with Sketch. - - - - - - - - - - diff --git a/content/en/docs/3.0/images/features-icons/statsd.png b/content/en/docs/3.0/images/features-icons/statsd.png deleted file mode 100644 index 28374438..00000000 Binary files a/content/en/docs/3.0/images/features-icons/statsd.png and /dev/null differ diff --git a/content/en/docs/3.0/images/features-icons/statsd.svg b/content/en/docs/3.0/images/features-icons/statsd.svg deleted file mode 100644 index cabc90db..00000000 --- a/content/en/docs/3.0/images/features-icons/statsd.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - 88eb31f74479e422e4e9abfc6c2b00ee - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.0/images/features-icons/third-party-auth.svg b/content/en/docs/3.0/images/features-icons/third-party-auth.svg deleted file mode 100644 index 5359a24a..00000000 --- a/content/en/docs/3.0/images/features-icons/third-party-auth.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_511233_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.0/images/features-icons/timeouts.svg b/content/en/docs/3.0/images/features-icons/timeouts.svg deleted file mode 100644 index 47f63056..00000000 --- a/content/en/docs/3.0/images/features-icons/timeouts.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_587034_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.0/images/features-icons/tls-termination.svg b/content/en/docs/3.0/images/features-icons/tls-termination.svg deleted file mode 100644 index 6a631a96..00000000 --- a/content/en/docs/3.0/images/features-icons/tls-termination.svg +++ /dev/null @@ -1,17 +0,0 @@ - - - - noun_63544_cc - Created with Sketch. - - - - - - - - - - - - diff --git a/content/en/docs/3.0/images/features-icons/url-rewrite.svg b/content/en/docs/3.0/images/features-icons/url-rewrite.svg deleted file mode 100644 index 023e2e05..00000000 --- a/content/en/docs/3.0/images/features-icons/url-rewrite.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1295942_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.0/images/features-icons/websockets.svg b/content/en/docs/3.0/images/features-icons/websockets.svg deleted file mode 100644 index af17b9c0..00000000 --- a/content/en/docs/3.0/images/features-icons/websockets.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - noun_50814_cc - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.0/images/features-table.jpg b/content/en/docs/3.0/images/features-table.jpg deleted file mode 100644 index 3de2eb4f..00000000 Binary files a/content/en/docs/3.0/images/features-table.jpg and /dev/null differ diff --git a/content/en/docs/3.0/images/gRPC-TLS-Ambassador.png b/content/en/docs/3.0/images/gRPC-TLS-Ambassador.png deleted file mode 100644 index 0189253e..00000000 Binary files a/content/en/docs/3.0/images/gRPC-TLS-Ambassador.png and /dev/null differ diff --git a/content/en/docs/3.0/images/gRPC-TLS-Originate.png b/content/en/docs/3.0/images/gRPC-TLS-Originate.png deleted file mode 100644 index 1b62010d..00000000 Binary files a/content/en/docs/3.0/images/gRPC-TLS-Originate.png and /dev/null differ diff --git a/content/en/docs/3.0/images/github-login.png b/content/en/docs/3.0/images/github-login.png deleted file mode 100644 index cfd4d4bf..00000000 Binary files a/content/en/docs/3.0/images/github-login.png and /dev/null differ diff --git a/content/en/docs/3.0/images/global-features-bg.svg b/content/en/docs/3.0/images/global-features-bg.svg deleted file mode 100644 index a39c5232..00000000 --- a/content/en/docs/3.0/images/global-features-bg.svg +++ /dev/null @@ -1,34 +0,0 @@ - - - - ambassador_logo@2x - Created with Sketch. - - - - - - - - diff --git a/content/en/docs/3.0/images/grafana.png b/content/en/docs/3.0/images/grafana.png deleted file mode 100644 index befe3377..00000000 Binary files a/content/en/docs/3.0/images/grafana.png and /dev/null differ diff --git a/content/en/docs/3.0/images/grpc-tls.png b/content/en/docs/3.0/images/grpc-tls.png deleted file mode 100644 index 4d705ff0..00000000 Binary files a/content/en/docs/3.0/images/grpc-tls.png and /dev/null differ diff --git a/content/en/docs/3.0/images/helm-navy.png b/content/en/docs/3.0/images/helm-navy.png deleted file mode 100644 index a9710143..00000000 Binary files a/content/en/docs/3.0/images/helm-navy.png and /dev/null differ diff --git a/content/en/docs/3.0/images/helm.png b/content/en/docs/3.0/images/helm.png deleted file mode 100644 index 1c5af71b..00000000 Binary files a/content/en/docs/3.0/images/helm.png and /dev/null differ diff --git a/content/en/docs/3.0/images/highly-available-icon.svg b/content/en/docs/3.0/images/highly-available-icon.svg deleted file mode 100644 index 9cb3eff9..00000000 --- a/content/en/docs/3.0/images/highly-available-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1205522_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.0/images/jaeger.png b/content/en/docs/3.0/images/jaeger.png deleted file mode 100644 index 3b821c09..00000000 Binary files a/content/en/docs/3.0/images/jaeger.png and /dev/null differ diff --git a/content/en/docs/3.0/images/kubernetes.png b/content/en/docs/3.0/images/kubernetes.png deleted file mode 100644 index a392a886..00000000 Binary files a/content/en/docs/3.0/images/kubernetes.png and /dev/null differ diff --git a/content/en/docs/3.0/images/left-arrow.svg b/content/en/docs/3.0/images/left-arrow.svg deleted file mode 100644 index 75cdc7f1..00000000 --- a/content/en/docs/3.0/images/left-arrow.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Path 2 - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.0/images/linux.png b/content/en/docs/3.0/images/linux.png deleted file mode 100644 index 1832c594..00000000 Binary files a/content/en/docs/3.0/images/linux.png and /dev/null differ diff --git a/content/en/docs/3.0/images/logo.png b/content/en/docs/3.0/images/logo.png deleted file mode 100644 index 701f63ba..00000000 Binary files a/content/en/docs/3.0/images/logo.png and /dev/null differ diff --git a/content/en/docs/3.0/images/mapping-editor.png b/content/en/docs/3.0/images/mapping-editor.png deleted file mode 100644 index f8b751a1..00000000 Binary files a/content/en/docs/3.0/images/mapping-editor.png and /dev/null differ diff --git a/content/en/docs/3.0/images/network-architecture.png b/content/en/docs/3.0/images/network-architecture.png deleted file mode 100644 index 3217b3e1..00000000 Binary files a/content/en/docs/3.0/images/network-architecture.png and /dev/null differ diff --git a/content/en/docs/3.0/images/penguin-background.svg b/content/en/docs/3.0/images/penguin-background.svg deleted file mode 100644 index 7affc0d5..00000000 --- a/content/en/docs/3.0/images/penguin-background.svg +++ /dev/null @@ -1,102 +0,0 @@ - - - - @2xambassador_logo - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.0/images/pro-iap.png b/content/en/docs/3.0/images/pro-iap.png deleted file mode 100644 index 787265d8..00000000 Binary files a/content/en/docs/3.0/images/pro-iap.png and /dev/null differ diff --git a/content/en/docs/3.0/images/quote.svg b/content/en/docs/3.0/images/quote.svg deleted file mode 100644 index bab6e871..00000000 --- a/content/en/docs/3.0/images/quote.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - “ - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.0/images/right-arrow.svg b/content/en/docs/3.0/images/right-arrow.svg deleted file mode 100644 index 627144c6..00000000 --- a/content/en/docs/3.0/images/right-arrow.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Path 2 Copy - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.0/images/routing-icon.svg b/content/en/docs/3.0/images/routing-icon.svg deleted file mode 100644 index bd860b13..00000000 --- a/content/en/docs/3.0/images/routing-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1062254_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.0/images/self-service-features-bg.svg b/content/en/docs/3.0/images/self-service-features-bg.svg deleted file mode 100644 index 40bc400a..00000000 --- a/content/en/docs/3.0/images/self-service-features-bg.svg +++ /dev/null @@ -1,93 +0,0 @@ - - - - Group 8 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - SELF-SERVICE FEATURES - - - - diff --git a/content/en/docs/3.0/images/shadowing.png b/content/en/docs/3.0/images/shadowing.png deleted file mode 100644 index 097ecbd5..00000000 Binary files a/content/en/docs/3.0/images/shadowing.png and /dev/null differ diff --git a/content/en/docs/3.0/images/speedometers.png b/content/en/docs/3.0/images/speedometers.png deleted file mode 100644 index 7ce2c2a2..00000000 Binary files a/content/en/docs/3.0/images/speedometers.png and /dev/null differ diff --git a/content/en/docs/3.0/images/tp-architecture.png b/content/en/docs/3.0/images/tp-architecture.png deleted file mode 100644 index 20ae3589..00000000 Binary files a/content/en/docs/3.0/images/tp-architecture.png and /dev/null differ diff --git a/content/en/docs/3.0/images/tp-tutorial-1.png b/content/en/docs/3.0/images/tp-tutorial-1.png deleted file mode 100644 index ee68dc7d..00000000 Binary files a/content/en/docs/3.0/images/tp-tutorial-1.png and /dev/null differ diff --git a/content/en/docs/3.0/images/tp-tutorial-2.png b/content/en/docs/3.0/images/tp-tutorial-2.png deleted file mode 100644 index 129dc6ee..00000000 Binary files a/content/en/docs/3.0/images/tp-tutorial-2.png and /dev/null differ diff --git a/content/en/docs/3.0/images/tp-tutorial-3.png b/content/en/docs/3.0/images/tp-tutorial-3.png deleted file mode 100644 index 946629fc..00000000 Binary files a/content/en/docs/3.0/images/tp-tutorial-3.png and /dev/null differ diff --git a/content/en/docs/3.0/images/tp-tutorial-4.png b/content/en/docs/3.0/images/tp-tutorial-4.png deleted file mode 100644 index cb6e7a9d..00000000 Binary files a/content/en/docs/3.0/images/tp-tutorial-4.png and /dev/null differ diff --git a/content/en/docs/3.0/images/trad-inner-dev-loop.png b/content/en/docs/3.0/images/trad-inner-dev-loop.png deleted file mode 100644 index 618b674f..00000000 Binary files a/content/en/docs/3.0/images/trad-inner-dev-loop.png and /dev/null differ diff --git a/content/en/docs/3.0/images/windows.png b/content/en/docs/3.0/images/windows.png deleted file mode 100644 index a065dc17..00000000 Binary files a/content/en/docs/3.0/images/windows.png and /dev/null differ diff --git a/content/en/docs/3.0/images/xkcd.png b/content/en/docs/3.0/images/xkcd.png deleted file mode 100644 index ed0d5c33..00000000 Binary files a/content/en/docs/3.0/images/xkcd.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/edge-stack-1.13.4.png b/content/en/docs/3.0/release-notes/edge-stack-1.13.4.png deleted file mode 100644 index 954ac1a9..00000000 Binary files a/content/en/docs/3.0/release-notes/edge-stack-1.13.4.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/edge-stack-1.13.7-json-logging.png b/content/en/docs/3.0/release-notes/edge-stack-1.13.7-json-logging.png deleted file mode 100644 index 4a47cbdf..00000000 Binary files a/content/en/docs/3.0/release-notes/edge-stack-1.13.7-json-logging.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/edge-stack-1.13.7-memory.png b/content/en/docs/3.0/release-notes/edge-stack-1.13.7-memory.png deleted file mode 100644 index 9c415ba3..00000000 Binary files a/content/en/docs/3.0/release-notes/edge-stack-1.13.7-memory.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/edge-stack-1.13.7-tcpmapping-consul.png b/content/en/docs/3.0/release-notes/edge-stack-1.13.7-tcpmapping-consul.png deleted file mode 100644 index c455a47f..00000000 Binary files a/content/en/docs/3.0/release-notes/edge-stack-1.13.7-tcpmapping-consul.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/edge-stack-1.13.8-cloud-bugfix.png b/content/en/docs/3.0/release-notes/edge-stack-1.13.8-cloud-bugfix.png deleted file mode 100644 index 6beaf653..00000000 Binary files a/content/en/docs/3.0/release-notes/edge-stack-1.13.8-cloud-bugfix.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/edge-stack-2.0.0-host_crd.png b/content/en/docs/3.0/release-notes/edge-stack-2.0.0-host_crd.png deleted file mode 100644 index c77ef528..00000000 Binary files a/content/en/docs/3.0/release-notes/edge-stack-2.0.0-host_crd.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/edge-stack-2.0.0-ingressstatus.png b/content/en/docs/3.0/release-notes/edge-stack-2.0.0-ingressstatus.png deleted file mode 100644 index 6856d308..00000000 Binary files a/content/en/docs/3.0/release-notes/edge-stack-2.0.0-ingressstatus.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/edge-stack-2.0.0-insecure_action_hosts.png b/content/en/docs/3.0/release-notes/edge-stack-2.0.0-insecure_action_hosts.png deleted file mode 100644 index 79c20bad..00000000 Binary files a/content/en/docs/3.0/release-notes/edge-stack-2.0.0-insecure_action_hosts.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/edge-stack-2.0.0-listener.png b/content/en/docs/3.0/release-notes/edge-stack-2.0.0-listener.png deleted file mode 100644 index ea45a02b..00000000 Binary files a/content/en/docs/3.0/release-notes/edge-stack-2.0.0-listener.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/edge-stack-2.0.0-prune_routes.png b/content/en/docs/3.0/release-notes/edge-stack-2.0.0-prune_routes.png deleted file mode 100644 index bc43229f..00000000 Binary files a/content/en/docs/3.0/release-notes/edge-stack-2.0.0-prune_routes.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/edge-stack-2.0.0-tlscontext.png b/content/en/docs/3.0/release-notes/edge-stack-2.0.0-tlscontext.png deleted file mode 100644 index 68dbad80..00000000 Binary files a/content/en/docs/3.0/release-notes/edge-stack-2.0.0-tlscontext.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/edge-stack-2.0.0-v3alpha1.png b/content/en/docs/3.0/release-notes/edge-stack-2.0.0-v3alpha1.png deleted file mode 100644 index c0ac3596..00000000 Binary files a/content/en/docs/3.0/release-notes/edge-stack-2.0.0-v3alpha1.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/emissary-1.13.10-cors-origin.png b/content/en/docs/3.0/release-notes/emissary-1.13.10-cors-origin.png deleted file mode 100644 index b7538e5f..00000000 Binary files a/content/en/docs/3.0/release-notes/emissary-1.13.10-cors-origin.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/emissary-ga.png b/content/en/docs/3.0/release-notes/emissary-ga.png deleted file mode 100644 index 062f043a..00000000 Binary files a/content/en/docs/3.0/release-notes/emissary-ga.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/tada.png b/content/en/docs/3.0/release-notes/tada.png deleted file mode 100644 index c8832e8e..00000000 Binary files a/content/en/docs/3.0/release-notes/tada.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/v2.0.4-k8s-1.22.png b/content/en/docs/3.0/release-notes/v2.0.4-k8s-1.22.png deleted file mode 100644 index ed9b0415..00000000 Binary files a/content/en/docs/3.0/release-notes/v2.0.4-k8s-1.22.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/v2.0.4-l7depth.png b/content/en/docs/3.0/release-notes/v2.0.4-l7depth.png deleted file mode 100644 index 9314324c..00000000 Binary files a/content/en/docs/3.0/release-notes/v2.0.4-l7depth.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/v2.0.4-mapping-dns-type.png b/content/en/docs/3.0/release-notes/v2.0.4-mapping-dns-type.png deleted file mode 100644 index 7770c77d..00000000 Binary files a/content/en/docs/3.0/release-notes/v2.0.4-mapping-dns-type.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/v2.0.4-v3alpha1.png b/content/en/docs/3.0/release-notes/v2.0.4-v3alpha1.png deleted file mode 100644 index 9c50b8fb..00000000 Binary files a/content/en/docs/3.0/release-notes/v2.0.4-v3alpha1.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/v2.0.4-version.png b/content/en/docs/3.0/release-notes/v2.0.4-version.png deleted file mode 100644 index 9481b7db..00000000 Binary files a/content/en/docs/3.0/release-notes/v2.0.4-version.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/v2.0.5-auth-circuit-breaker.png b/content/en/docs/3.0/release-notes/v2.0.5-auth-circuit-breaker.png deleted file mode 100644 index cac8cf7b..00000000 Binary files a/content/en/docs/3.0/release-notes/v2.0.5-auth-circuit-breaker.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/v2.0.5-mappingselector.png b/content/en/docs/3.0/release-notes/v2.0.5-mappingselector.png deleted file mode 100644 index 31942ede..00000000 Binary files a/content/en/docs/3.0/release-notes/v2.0.5-mappingselector.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/v2.1.0-canary.png b/content/en/docs/3.0/release-notes/v2.1.0-canary.png deleted file mode 100644 index 39d3bbbf..00000000 Binary files a/content/en/docs/3.0/release-notes/v2.1.0-canary.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/v2.1.0-gzip-enabled.png b/content/en/docs/3.0/release-notes/v2.1.0-gzip-enabled.png deleted file mode 100644 index 061fcbc9..00000000 Binary files a/content/en/docs/3.0/release-notes/v2.1.0-gzip-enabled.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/v2.1.0-smoother-migration.png b/content/en/docs/3.0/release-notes/v2.1.0-smoother-migration.png deleted file mode 100644 index ebd77497..00000000 Binary files a/content/en/docs/3.0/release-notes/v2.1.0-smoother-migration.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/v2.1.2-annotations.png b/content/en/docs/3.0/release-notes/v2.1.2-annotations.png deleted file mode 100644 index b5498c3c..00000000 Binary files a/content/en/docs/3.0/release-notes/v2.1.2-annotations.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/v2.1.2-host-mapping-matching.png b/content/en/docs/3.0/release-notes/v2.1.2-host-mapping-matching.png deleted file mode 100644 index 1cfba5ed..00000000 Binary files a/content/en/docs/3.0/release-notes/v2.1.2-host-mapping-matching.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/v2.1.2-mapping-cors.png b/content/en/docs/3.0/release-notes/v2.1.2-mapping-cors.png deleted file mode 100644 index f76ea01c..00000000 Binary files a/content/en/docs/3.0/release-notes/v2.1.2-mapping-cors.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/v2.1.2-mapping-less-weighted.png b/content/en/docs/3.0/release-notes/v2.1.2-mapping-less-weighted.png deleted file mode 100644 index 7e299062..00000000 Binary files a/content/en/docs/3.0/release-notes/v2.1.2-mapping-less-weighted.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/v2.1.2-mapping-no-rewrite.png b/content/en/docs/3.0/release-notes/v2.1.2-mapping-no-rewrite.png deleted file mode 100644 index 5d3d5a29..00000000 Binary files a/content/en/docs/3.0/release-notes/v2.1.2-mapping-no-rewrite.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/v2.2.0-cloud.png b/content/en/docs/3.0/release-notes/v2.2.0-cloud.png deleted file mode 100644 index 5923fcb4..00000000 Binary files a/content/en/docs/3.0/release-notes/v2.2.0-cloud.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/v2.2.0-percent-escape.png b/content/en/docs/3.0/release-notes/v2.2.0-percent-escape.png deleted file mode 100644 index df4d81b9..00000000 Binary files a/content/en/docs/3.0/release-notes/v2.2.0-percent-escape.png and /dev/null differ diff --git a/content/en/docs/3.0/release-notes/v2.2.0-tls-cert-validation.png b/content/en/docs/3.0/release-notes/v2.2.0-tls-cert-validation.png deleted file mode 100644 index f8635b5a..00000000 Binary files a/content/en/docs/3.0/release-notes/v2.2.0-tls-cert-validation.png and /dev/null differ diff --git a/content/en/docs/3.0/releaseNotes.yml b/content/en/docs/3.0/releaseNotes.yml deleted file mode 100644 index 1b4dd433..00000000 --- a/content/en/docs/3.0/releaseNotes.yml +++ /dev/null @@ -1,1094 +0,0 @@ -# -*- fill-column: 100 -*- - -# This file should be placed in the folder for the version of the -# product that's meant to be documented. A `/release-notes` page will -# be automatically generated and populated at build time. -# -# Note that an entry needs to be added to the `doc-links.yml` file in -# order to surface the release notes in the table of contents. -# -# The YAML in this file should contain: -# -# changelog: An (optional) URL to the CHANGELOG for the product. -# items: An array of releases with the following attributes: -# - version: The (optional) version number of the release, if applicable. -# - date: The date of the release in the format YYYY-MM-DD. -# - notes: An array of noteworthy changes included in the release, each having the following attributes: -# - type: The type of change, one of `bugfix`, `feature`, `security` or `change`. -# - title: A short title of the noteworthy change. -# - body: >- -# Two or three sentences describing the change and why it -# is noteworthy. This is HTML, not plain text or -# markdown. It is handy to use YAML's ">-" feature to -# allow line-wrapping. -# - image: >- -# The URL of an image that visually represents the -# noteworthy change. This path is relative to the -# `release-notes` directory; if this file is -# `FOO/releaseNotes.yml`, then the image paths are -# relative to `FOO/release-notes/`. -# - docs: The path to the documentation page where additional information can be found. -# - href: A path from the root to a resource on the getambassador website, takes precedence over a docs link. - -changelog: https://github.com/emissary-ingress/emissary/blob/$branch$/CHANGELOG.md -items: - - 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.4.0 - date: 'TBD' - 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. - - - 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. - - - 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/content/en/docs/3.0/topics/concepts/architecture.md b/content/en/docs/3.0/topics/concepts/architecture.md deleted file mode 100644 index 6dd054fe..00000000 --- a/content/en/docs/3.0/topics/concepts/architecture.md +++ /dev/null @@ -1,28 +0,0 @@ -# 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). - -Ambassador Architecture Diagram - - -## 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/content/en/docs/3.0/topics/concepts/gitops-continuous-delivery.md b/content/en/docs/3.0/topics/concepts/gitops-continuous-delivery.md deleted file mode 100644 index 336a1c66..00000000 --- a/content/en/docs/3.0/topics/concepts/gitops-continuous-delivery.md +++ /dev/null @@ -1,66 +0,0 @@ -# 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/content/en/docs/3.0/topics/concepts/index.md b/content/en/docs/3.0/topics/concepts/index.md deleted file mode 100644 index 2d02a027..00000000 --- a/content/en/docs/3.0/topics/concepts/index.md +++ /dev/null @@ -1,10 +0,0 @@ -# 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/content/en/docs/3.0/topics/concepts/kubernetes-network-architecture.md b/content/en/docs/3.0/topics/concepts/kubernetes-network-architecture.md deleted file mode 100644 index 6650aa60..00000000 --- a/content/en/docs/3.0/topics/concepts/kubernetes-network-architecture.md +++ /dev/null @@ -1,52 +0,0 @@ -# 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: - -
- -![Kubernetes Network Architecture](../../../../../../images/documentation/kubernetes-network.inline.svg) - -
- -Each of the components in this topology is discussed in further detail below. - -### Load balancer - -The load balancer is deployed outside of the Kubernetes cluster. Typically, the load balancer also has one or more static IP addresses assigned to it. A DNS entry is then created to map a domain name (e.g., example.com) to the static IP address. - -Cloud infrastructure providers such as Amazon Web Services, Azure, Digital Ocean, and Google make it easy to create these load balancers directly from Kubernetes. This is done by creating a Kubernetes service of `type: LoadBalancer`. When this service is created, the cloud provider will use the metadata contained in the Kubernetes service definition to provision a load balancer. - -If the Kubernetes cluster is deployed in a private data center, an external load balancer is still generally used. Provisioning of this load balancer usually requires the involvement of the data center operations team. - -In both the private data center and cloud infrastructure case, the external load balancer should be configured to point to the edge proxy. - -### Edge Proxy / ingress controller - -The Edge Proxy is typically a Layer 7 proxy that is deployed directly in the cluster. The core function of the edge proxy is to accept incoming traffic from the external load balancer and route the traffic to Kubernetes services. The edge proxy should be configured using Kubernetes manifests. This enables a common management workflow for both the edge proxy and Kubernetes services. - -The most popular approach to configuring edge proxies is with the Kubernetes ingress resource. When an edge proxy can process ingress resources, it is called an ingress controller. Not all edge proxies are ingress controllers (because they can't process ingress resources), but all ingress controllers are edge proxies. - -The ingress resource is a Kubernetes standard. As such, it is a lowest common denominator resource. In practice, users find that the ingress resource is insufficient in scope to address the requirements for edge routing. Semantics such as TLS termination, redirecting to TLS, timeouts, rate limiting, and authentication are all beyond the scope of the ingress resource. - -$productName$ can function as an ingress controller (i.e., it reads ingress resources), although it also includes many other capabilities that are beyond the scope of the ingress specification. Most $productName$ users find that the various additional capabilities of $productName$ are essential, and end up using $productName$'s extensions to the ingress resource, instead of using ingress resources themselves. - -### Kubernetes services and Pods - -Each instance of your application is deployed in a Kubernetes pod. As the workload on your application increases or decreases, Kubernetes can automatically add or remove pods. A Kubernetes _service_ represents a group of pods that comprise the same version of a given application. Traffic can be routed to the pods via a Kubernetes service, or it can be routed directly to the pods. - -When traffic is routed to the pods via a Kubernetes service, Kubernetes uses a built-in mechanism called `kube-proxy` to load balance traffic between the pods. Due to its implementation, `kube-proxy` is a Layer 4 proxy, i.e., it load balances at a connection level. For particular types of traffic such as HTTP/2 and gRPC, this form of load balancing is particularly problematic as it can easily result in a very uneven load balancing configuration. - -Traffic can also be routed directly to pods, bypassing the Kubernetes service. Since pods are much more ephemeral than Kubernetes services, this approach requires an edge proxy that is optimized for this use case. In particular, the edge proxy needs to support real-time discovery of pods, and be able to dynamically update pod locations without downtime. - -$productName$ supports routing both to Kubernetes services and directly to pods. - -## Further reading - -* [Kubernetes Ingress 101](https://blog.getambassador.io/kubernetes-ingress-nodeport-load-balancers-and-ingress-controllers-6e29f1c44f2d) -* [Envoy Proxy Performance on Kubernetes](/resources/envoyproxy-performance-on-k8s/) diff --git a/content/en/docs/3.0/topics/concepts/microservices-api-gateways.md b/content/en/docs/3.0/topics/concepts/microservices-api-gateways.md deleted file mode 100644 index ba95b8fc..00000000 --- a/content/en/docs/3.0/topics/concepts/microservices-api-gateways.md +++ /dev/null @@ -1,60 +0,0 @@ -# Microservices API gateways - -A microservices API gateway is an API gateway designed to accelerate the development workflow of independent services teams. A microservices API gateway provides all the functionality for a team to independently publish, monitor, and update a microservice. - -This focus on accelerating the development workflow is distinct from the purpose of traditional API gateways, which focus on the challenges of managing APIs. Over the past decade, organizations have worked to expose internal systems through well-defined APIs. The challenge of safely exposing hundreds or thousands of APIs to end-users (both internal and external) led to the emergence of API gateways. Over time, API gateways have become centralized, mission critical pieces of infrastructure that control access to these APIs. - -In this article, we'll discuss how the difference in business objective (productivity vs management) results in a very different API gateway. - -## Microservices organization - -In a microservices organization, small teams of developers work independently from each other to rapidly deliver functionality to the customer. In order for each service team to work independently, with a productive workflow, a services team needs to be able to: - -1. Publish their service, so that others can use the service -2. Monitor their service, to see how well it's working -3. Test and update their service, so they can keep on improving the service - -The team needs to do all of this *without* requiring assistance from another operations or platform team--as soon as a services team requires another team, they're no longer working independently, and this can lead to bottlenecks. - -For service publication, a microservices API gateway provides a static address for consumers, and dynamically route requests to the appropriate service address. In addition, providing authentication and TLS termination for security are typical considerations in exposing a service to other consumers. - -Understanding the end-user experience of a service is crucial to improving the service. For example, a software update could inadvertently impact the latency of certain requests. A microservices API gateway is well situated to collect key observability metrics on end-user traffic as it routes traffic to the end service. - -A microservices API gateway also supports dynamically routing user requests to different service versions for canary testing. By routing a small fraction of end-user requests to a new version of a service, service teams can safely test the impact of new updates to a small subset of users. - -## Microservices API Gateways vs. enterprise API Gateways - -At first glance, the use case described above may be fulfilled with an enterprise-focused API gateway. While this may be true, the actual emphasis of enterprise API gateways and microservices API gateways are somewhat different: - -| Use case | Traditional Enterprise API gateway | Microservices API gateway | -|---------------|-------------------|------------------------------| -| Primary Purpose | Expose, compose, and manage internal business APIs | Expose and observe internal business services | -| Publishing Functionality | API management team or service team registers / updates gateway via admin API | Service team registers / updates gateway via declarative code as part of the deployment process | -| Monitoring | Admin and operations focused e.g. meter API calls per consumer, report errors (e.g. internal 5XX). | Developer focused e.g. latency, traffic, errors, saturation | -| Handling and Debugging Issues | L7 error-handling (e.g. custom error page or payload). Run gateway/API with additional logging. Troubleshoot issue in staging environment | Configure more detailed monitoring. Enable traffic shadowing and / or canarying | -| Testing | Operate multiple environments for QA, Staging, and Production. Automated integration testing, and gated API deployment. Use client-driven API versioning for compatibility and stability (e.g. semver) | Facilitate canary routing for dynamic testing (taking care with data mutation side effects). Use developer-driven service versioning for upgrade management | -| Local Development | Deploy gateway locally (via installation script, Vagrant or Docker), and attempt to mitigate infrastructure differences with production. Use language-specific gateway mocking and stubbing frameworks | Deploy gateway locally via service orchestration platform (e.g. Kubernetes) | - -## Self-service publishing - -A team needs to be able to publish a new service to customers without requiring an operations or API management team. This ability to self-service for deployment and publication enables the team to keep the feature release velocity high. While a traditional enterprise API gateway may provide a simple mechanism (e.g., REST API) for publishing a new service, in practice, the usage is often limited to the use of a dedicated team that is responsible for the gateway. The primary reason for limiting publication to a single team is to provide an additional (human) safety mechanism: an errant API call could have potentially disastrous effects on production. - -Microservices API gateways utilize mechanisms that enable service teams to easily *and* safely publish new services, with the inherent understanding that the producing team are responsible for their service, and will fix an issue if one occurs. A microservices gateway provides configurable monitoring for issue detection, and provides hooks for debugging, such as inspecting traffic or traffic shifting/duplication. - -## Monitoring and rate limiting - -A common business model for APIs is metering, where a consumer is charged different fees depending on API usage. Traditional enterprise API gateways excel in this use case: they provide functionality for monitoring per-client usage of an API, and the ability to limit usage when the client exceeds their quota. - -A microservice gateway also requires monitoring and rate limiting, but for different reasons. Monitoring user-visible metrics such as throughput, latency, and availability, are important to ensure that new updates don't impact the end-user. Robust end-user metrics are critical to allowing rapid, incremental updates. Rate limiting is used to improve the overall resilience of a service. When a service is not responding as expected, an API gateway can throttle incoming requests to allow a service to recover and prevent a cascade failure. - -## Testing and updates - -A microservices application has multiple services, each of which is being independently updated. Automated pre-production testing of a moving target is necessary but not sufficient for microservices. Canary testing, where a small percentage of production traffic is routed to a new service version, is an important tool to help test an update. By limiting a new service version to a small percentage of users, the impact of a service failure is limited. - -In a traditional enterprise API gateway, routing is used to isolate or compose/aggregate changing API versions. Automated pre-production testing and manual post-production verification and exploration are required. - -## Summary - -Traditional enterprise API gateways are designed to solve the challenges of API management. While they may appear to solve some of the challenges of adopting microservices, the reality is that a microservices workflow creates a different set of requirements. Integrating a microservices API gateway into your development workflow empowers service teams to self-publish, monitor, and update their service, quickly and safely. This will enable your organization to ship software more rapidly, and with more reliability than ever before. - -For further reading on how an API Gateway can accelerate continuous delivery, read [this blog post](https://blog.getambassador.io/continuous-delivery-how-can-an-api-gateway-help-or-hinder-1ff15224ec4d). diff --git a/content/en/docs/3.0/topics/concepts/progressive-delivery.md b/content/en/docs/3.0/topics/concepts/progressive-delivery.md deleted file mode 100644 index 32f31f2f..00000000 --- a/content/en/docs/3.0/topics/concepts/progressive-delivery.md +++ /dev/null @@ -1,48 +0,0 @@ -# Progressive delivery - -Today's cloud-native applications may consist of hundreds of services, each of which are being updated at any time. Thus, many cloud-native organizations augment regression test strategies with testing in production using progressive delivery techniques. - -Progressive Delivery is an approach for releasing software to production users. In the progressive delivery model, software is released to ever growing subsets of production users. This approach reduces the blast radius in the event of a failure. - -## Why test in production? - -Modern cloud applications are continuously deployed, as different teams rapidly update their respective services. Deploying and testing updates in a pre-production staging environment introduces a bottleneck to the speed of iteration. More importantly, staging environments are not representative of what will be running in production when the deployment actually occurs given the velocity of service updates and changes in production. Testing in production addresses both of these challenges: developers evaluate their changes in the real-world environment, enabling rapid iteration. - -## Progressive delivery strategies - -There are a number of different strategies for progressive delivery. These include: - -* Feature flags, where specific features are made available to specific user groups -* Canary releases, where a (small) percentage of traffic is routed to a new version of a service before the service is full production -* Traffic shadowing, where real user traffic is copied, or shadowed, from production to the service under test - -Observability is a critical requirement for testing in production. Regardless of progressive delivery strategy, collecting key metrics around latency, traffic, errors, and saturation (the [“Four Golden Signals of Monitoring”](https://landing.google.com/sre/sre-book/chapters/monitoring-distributed-systems/#xref_monitoring_golden-signals)) provides valuable insight into the stability and performance of a new version of the service. Moreover, application developers can compare the metrics (e.g., latency) between the production version and an updated version. If the metrics are similar, then updates can proceed with much greater confidence. - -$productName$ supports a variety of strategies for progressive delivery. These strategies are discussed in further detail below. - -### Canary releases - -Canary releases shifts a small amount of real user traffic from production to the service under test. - -The user will see the direct response from the canary version of the service from any traffic that is shifted to the canary release, and they will not trigger or see the response from the current production released version of the service. The canary results can also be verified (both the downstream response and associated upstream side effects), but it is key to understand that any side effects will be persisted. - -In addition to allowing verification that the service is not crashing or otherwise behaving badly from an operational perspective when dealing with real user traffic and behavior, canary releasing allows user validation. For example, if a business KPI performs worse for all canaried requests, then this most likely indicates that the canaried service should not be fully released in its current form. - -Canary tests can be automated, and are typically run after testing in a pre-production environment has been completed. The canary release is only visible to a fraction of actual users, and any bugs or negative changes can be reversed quickly by either routing traffic away from the canary or by rolling-back the canary deployment. - -
-Canary release process overview - -Canary releases are not a panacea. In particular, many services may not receive sufficient traffic in order for canary releases to provide useful information in an actionable timeframe. - -### Traffic shadowing - -This approach “shadows” or mirrors a small amount of real user traffic from production to the service under test. - -Although the shadowed results can be verified (both the downstream response and associated upstream side effects) they are not returned to the user -- the user only sees the results from the currently released service. Typically any side effects are not persisted or are executed as a no-op and verified (much like setting up a mock, and verifying that a method/function was called with the correct parameters). - -This allows verification that the service is not crashing or otherwise behaving badly from an operational perspective when dealing with real user traffic and behavior (and the larger the percentage of traffic shadowed, the higher the probability of confidence). - -## Further reading - -* [Canary release pattern](https://blog.getambassador.io/cloud-native-patterns-canary-release-1cb8f82d371a) diff --git a/content/en/docs/3.0/topics/concepts/rate-limiting-at-the-edge.md b/content/en/docs/3.0/topics/concepts/rate-limiting-at-the-edge.md deleted file mode 100644 index 1f849861..00000000 --- a/content/en/docs/3.0/topics/concepts/rate-limiting-at-the-edge.md +++ /dev/null @@ -1,33 +0,0 @@ -# Rate limiting concepts at the edge - -Rate limiting at the edge is a technique that is used to prevent a sudden or sustained increase in user traffic from breaking an API or underlying service. On the Internet, users can do whatever they want to your APIs, as you have no direct control over these end-users. Whether it’s intentional or not, these users can impact the availability, responsiveness, and scalability of your service. - -## Two approaches: Rate limiting and load shedding - -Rate limiting use cases that fall into this scenario range from implementing functional requirements related to a business scenario -- for example, where requests from paying customers is prioritized over requests from non-paying trial users -- to implementing cross-functional requirements, such as resilience from a malicious actor attempting to issue a denial-of-service (DoS) attack. - -A closely related technique to rate limiting is load shedding, and this can be used to selectively prioritize traffic (by dropping requests) based on the state of the entire system. For example, if a backend data store has become overloaded and slow to respond, it may be appropriate to drop (or “shed”) low priority requests or requests that are not time sensitive. - -## Use cases and scenarios - -The table below outlines several scenarios where rate limiting and load shedding can provide an effective solution to a range of functional and cross-functional requirements. The “Type of Rate Limiter” column provides a summary of the category of rate limiting that would be most appropriate for the scenario, and the “Specifics” column outlines what business or system properties would be involved in computing rate limiting decisions. - -| Scenario | Type of Rate Limiter |                            Specifics                        -| --- | --- | --- | -**Fairness.** One or more users are sending large volumes of requests, and thus impacting other users of the API | **User request rate limiting -** restricts each user to a predetermined number of requests per time unit.

**Concurrent user request limiting -** limits the number of concurrent user requests that can be inflight at any given point in time. |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
  • Geographic rate limiter
  • Time-based rate limiter
-**Prioritisation.** The business model depends on handling high priority requests over others | **User request rate limiting** |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device, free vs non-free user etc)
-**Resilience.** The API backend cannot scale rapidly enough to meet request demand due to a technical issue. | **Backend utilisation load shedder -** rate limit based upon utilisation of aggregate backend instances.

**Node/server utilisation load shedder -** rate limit based upon utilisation of individual or isolated groups of compute nodes/servers. |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
-**Security.** Prevent bad actors from using a DoS attack to overwhelm services, fuzzing, or brute force attacks |**User request rate limiting**

**Node/server utilisation load shedder** |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
  • Service identifier load shedder e.g. login service, audit service
-**Responsiveness.** As per the Reactive Manifesto, responsive systems focus on providing rapid and consistent response times, establishing reliable upper bounds so they deliver a consistent quality of service | **Concurrent user request limiting**

**Backend utilisation load shedder**

**Node/server utilisation load shedder** |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
  • Service identifier load shedder e.g. login service, audit service
- -## Avoiding contention with rate limiting configuration: Decoupling Dev and Ops - -One of the core features of $productName$ is the decentralization of configuration, allowing operations and development teams to independently control $productName$, as well as individual application development teams to minimize collaboration when configuring independently deployable services. This same approach applies to rate limiting configuration. - -The $productName$ rate limiting configuration allows centralized operations teams to define and implement global rate limiting and load shedding policies to protect the system, while still allowing individual application teams to define rate limiting policies that enforce business rules, for example, around paying and non-paying customers (perhaps implementing the so-called “freemium” model). See [Advanced Rate Limiting](../../../howtos/advanced-rate-limiting) documentation for examples. - -## Benefits of applying a rate limiter to the edge - -Modern applications and APIs can experience floods of traffic over a short time period (e.g. from achieving a HackerNews front page link), and increasingly bad actors and cyber criminals are targeting public-facing services. - -By implementing rate limiting and load shedding capabilities at the edge, a large amount of scenarios that are bad for business can be mitigated. These capabilities also make the life of the operations and development team that much easier, as the need to constantly firefight ingress traffic is reduced. diff --git a/content/en/docs/3.0/topics/install/ambassador-oss-community.md b/content/en/docs/3.0/topics/install/ambassador-oss-community.md deleted file mode 100644 index b53d1407..00000000 --- a/content/en/docs/3.0/topics/install/ambassador-oss-community.md +++ /dev/null @@ -1,14 +0,0 @@ -# Integration in community projects - -import Table from "../../../../../src/components/CommunityTable"; - -**$AESproductName$ is now available and includes additional functionality beyond the current $OSSproductName$.** -These features include automatic HTTPS, OAuth/OpenID Connect authentication support, integrated rate -limiting, a developer portal, and [more](/edge-stack-faq/). - -## $OSSproductName$ integrations - -If you still want to use just $OSSproductName$, don't worry! $OSSproductName$ -is currently available out-of-the-box in some Kubernetes installers and local environments. - -
\ No newline at end of file diff --git a/content/en/docs/3.0/topics/install/bare-metal.md b/content/en/docs/3.0/topics/install/bare-metal.md deleted file mode 100644 index 84ac1c8d..00000000 --- a/content/en/docs/3.0/topics/install/bare-metal.md +++ /dev/null @@ -1,93 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Install with bare metal - -In cloud environments, provisioning a readily available network load balancer with $productName$ is the best option for handling ingress into your Kubernetes cluster. When running Kubernetes on a bare metal setup, where network load balancers are not available by default, we need to consider different options for exposing $productName$. - -## Exposing $productName$ via NodePort - -The simplest way to expose an application in Kubernetes is via a `NodePort` service. In this configuration, we create the $productName$ service] and identify `type: NodePort` instead of `LoadBalancer`. Kubernetes will then create a service and assign that service a port to be exposed externally and direct traffic to $productName$ via the defined `port`. - -```yaml ---- -apiVersion: v1 -kind: Service -metadata: - name: ambassador -spec: - type: NodePort - ports: - - name: http - port: 8088 - targetPort: 8080 - nodePort: 30036 # Optional: Define the port you would like exposed - protocol: TCP - selector: - service: ambassador -``` - -Using a `NodePort` leaves $productName$ isolated from the host network, allowing the Kubernetes service to handle routing to $productName$ pods. You can drop-in this YAML to replace the `LoadBalancer` service in the [YAML installation guide](../yaml-install) and use `http://:/` as the host for requests. - -## Exposing $productName$ via host network - -When running $productName$ on a bare metal install of Kubernetes, you have the option to configure $productName$ pods to use the network of the host they are running on. This method allows you to bind $productName$ directly to port 80 or 443 so you won't need to identify the port in requests. - -i.e `http://:/` becomes `http:///` - -This can be configured by setting `hostNetwork: true` in the $productName$ deployment. `dnsPolicy: ClusterFirstWithHostNet` will also need to set to tell $productName$ to use *KubeDNS* when attempting to resolve mappings. - -```diff ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: ambassador -spec: - replicas: 1 - selector: - matchLabels: - service: ambassador - template: - metadata: - annotations: - sidecar.istio.io/inject: "false" - labels: - service: ambassador - app.kubernetes.io/managed-by: getambassador.io - spec: -+ hostNetwork: true -+ dnsPolicy: ClusterFirstWithHostNet - serviceAccountName: ambassador - containers: - - name: ambassador - image: docker.io/datawire/ambassador:$version$ - resources: - limits: - cpu: 1 - memory: 400Mi - requests: - cpu: 200m - memory: 100Mi - env: - - name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace - livenessProbe: - httpGet: - path: /ambassador/v0/check_alive - port: 8877 - initialDelaySeconds: 30 - periodSeconds: 3 - readinessProbe: - httpGet: - path: /ambassador/v0/check_ready - port: 8877 - initialDelaySeconds: 30 - periodSeconds: 3 - restartPolicy: Always -``` - -This configuration does not require a defined $productName$ service, so you can remove that service if you have defined one. - -**Note:** Before configuring $productName$ with this method, consider some of the functionality that is lost by bypassing the Kubernetes service including only having one $productName$ able to bind to port 8080 or 8443 per node and losing any load balancing that is typically performed by Kubernetes services. diff --git a/content/en/docs/3.0/topics/install/convert-to-v3alpha1.md b/content/en/docs/3.0/topics/install/convert-to-v3alpha1.md deleted file mode 100644 index e12d9aed..00000000 --- a/content/en/docs/3.0/topics/install/convert-to-v3alpha1.md +++ /dev/null @@ -1,275 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Convert Configuration Resources to `getambassador.io/v3alpha1` - -Once your $productName$ $version$ installation is running, it is **strongly recommended** that -you convert your existing configuration resources from `getambassador.io/v2` to -`getambassador.io/v3alpha1`. - - - While it is not necessary to convert all your resources to getambassador.io/v3alpha1 - immediately, you should ultimately update them all for full functionality with $productName$ - - -In general, the best way to convert any resource is to start with `kubectl get`: using -`kubectl get -o yaml` on any `getambassador.io/v2` resource will cause $productName$ to -translate it to a `getambassador.io/v3alpha1` resource. You can then verify that the -`getambassador.io/v3alpha1` resource looks correct and re-apply it, which will convert the -stored copy to `getambassador.io/v3alpha1`. - -As you do the conversion, here are the things to bear in mind: - -## 1. `ambassador_id` must be an array, not a simple string. - -`getambassador.io/v2` allowed `ambassador_id` to be either an array of strings, or a simple -string. In `getambassador.io/v3alpha1`, only the array form is supported: instead of -`ambassador_id: "foo"`, use `ambassador_id: [ "foo" ]`. This applies to all $productName$ -resources, and is supported by all versions of Ambassador 1.X. - -## 2. You must have a `Listener` for each port on which $productName$ should listen. - - - Learn more about Listener - - -`Listener` is **mandatory**. Defining your own `Listener`(s) allows you to carefully -tailor the set of ports you actually need to use, and exactly which `Host` resources -are matched with them (see below). - -## 3. `Listener`, `Host`, and `Mapping` must be explicit about how they associate. - -You need to have `Listener`s, `Host`s, and `Mapping`s correctly associated with each other for $productName$ 2.X configuration. - -### 3.1. `Listener` and `Host` are associated through `Listener.hostBinding` - - - Learn more about Listener
- Learn more about Host - - -In a `Listener`, the `hostBinding` controls whether a given `Host` is associated with that `Listener`, as discussed in the [`Listener`](../../running/listener) documentation. -**The recommended setting is using `hostBinding.selector`** to choose only `Host`s that have a defined -Kubernetes label: - -```yaml -hostBinding: - selector: - matchLabels: - my-listener: listener-8080 -``` - -The above example shows a `Listener` configured to associate only with `Host`s that have a `my-listener: listener-8080` label. - -For migration purposes, it is possible to have a `Listener` associate with all of the `Host`s. This is not recommended for production environments, however, as it can resulting confusing behavior with large numbers of `Host`s, and it -can also result in larger Envoy configurations that slow reconfiguration. - -```yaml -hostBinding: - namespace: - from: ALL -``` - -but **this is not recommended in production**. Allowing every `Host` to associate -with every `Listener` can result in confusing behavior with large numbers of `Host`s, and it -can also result in larger Envoy configurations that slow reconfiguration. - -### 3.2. `Host` and `Mapping` are associated through `Host.mappingSelector` - - -In $productName$ 1.X, `Mapping`s were nearly always associated with every `Host`. Since this -tends to result in larger Envoy configurations that slow down reconfiguration, $productName$ 2.X -inverts this behavior: **`Host` and `Mapping` will not associate without explicit selection**. - -To have a `Mapping` associate with a `Host`, at least one of the following must hold: - -- Recommended: The `Host` must define a `mappingSelector` that matches a `label` on the `Mapping`. -- Alternately, the `Mapping` must define `hostname` that matches the `hostname` of the `Host`. - (Note that the `hostname` of both `Host` and `AmbasssadorMapping` is a DNS glob.) - -If the `Host` defines a `mappingSelector` and the `Mapping` also defines a `hostname`, both must match. - -As a migration aid: - -- A `Mapping` with a `hostname` of `"*"` will associate with any `Host` that -has no `mappingSelector`, and -- A `v3alpha1` `Mapping` will honor `host` if `hostname` is not present. - - - Learn more about Host
- Learn more about Mapping - - - - A Mapping that specifies host_regex: true is associated with  - all Hosts. This is generally far less desirable than using hostname - with a DNS glob. - - - - Support for host and host_regex will be removed before - v3alpha1 is promoted to v3. - - -## 4. Use `Host` to terminate TLS - - - Learn more about Host
- Learn more about TLSContext - - -In $productName$ 1.X, simply creating a `TLSContext` is sufficient to terminate TLS, but in -2.X you _must_ use a `Host`. The minimal setup to terminate TLS is now something like this: - -```yaml ---- -apiVersion: v1 -kind: Secret -metadata: - name: my-secret -type: kubernetes.io/tls -data: - tls.crt: base64-PEM - tls.key: base64-PEM ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: my-host -spec: - hostname: host.example.com - tlsSecret: my-secret -``` - -In the example above, TLS is terminated for `host.example.com`. A `TLSContext` is still right way to share data -about TLS configuration across `Host`s: set both `tlsSecret` and `tlsContext` in the `Host`. - -## 5. `Mapping` should use `hostname` if possible - - - Learn more about Mapping - - -The `getambassador.io/v3alpha1` `Mapping` introduces the new `hostname` element, which is always -a DNS glob. Using `hostname` instead of `host` is **strongly recommended** unless you absolutely -require regular expression matching: - -- if `host` is being used for an exact match, simply rename `host` to `hostname`. -- if `host` is being used for a regex that effects a prefix or suffix match, rename it - to `hostname` and rewrite the regex into a DNS glob, e.g. `host: .*\.example\.com` would become - `hostname: *.example.com`. - -Additionally, when `hostname` is used, the `Mapping` will be associated with a `Host` only -if `hostname` matches the hostname of the `Host`. If the `Host`'s `selector` is also set, -both the `selector` and the hostname must line up. - - - An 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. - - -## 6. `Mapping` added headers must not be simple strings - - - Learn more about Mapping - - -The `getambassador.io/v2` `Mapping` supported strings and dictionaries for `add_request_headers` and -`add_response_headers`, for example: - -```yaml -add_request_headers: - X-Add-String: bar - X-Add-Dict: - value: bar -``` - -In `getambassador.io/v2`, both `X-Add-String` and `X-Add-Dict` will be added with the value `bar`. - -The string form - shown with `X-Add-String` - is not supported in `getambassador.io/v3alpha1`. Use the -dictionary form instead (which works in both `getambassador.io/v2` and `getambassador.io/v3alpha1`). - -## 7. `Mapping` `headers` and `query_parameters` must not be `true` - - - Learn more about Mapping - - -`headers` and `query_parameters` in a `Mapping` control header matches and query-parameter matches. In -`getambassador.io/v2`, they support both strings and dictionaries, and each has a `_regex` variant. -For example: - - ```yaml - headers: - x-exact-match: foo - x-existence-match: true - headers_regex: - x-regex-match: "fo.*o" - ``` - -In this example, the `Mapping` requires the `x-exact-match` header to have the value `foo`, the -`x-regex-match` whose value starts with `fo` and ends with `o`. However, `x-existence-match` requires -simply that the `x-existence-match` header exists. - -In `getambassador.io/v3alpha1`, the `true` value for an existence match is not supported. Instead, -use `headers_regex` for the same header with value of `.*`. This is fully supported in 1.k) - -`query_parameters` and `query_parameters_regex` work exactly like `headers` and `headers_reex`. - -## 8. `Mapping` `labels` must be converted to new syntax - - - Learn more about Mapping - - -In `getambassador.io/v2`, the `labels` element in a `Mapping` supported several different types of -data. In `getambassador.io/v3alpha1`, all labels must have the same type, so labels must be converted -to the new syntax: - -| `getambassador.io/v2` | `getambassador.io/v3alpha1` | -| -------------------------------- | ----------------------------------------------------------- | -| `source_cluster` | `{ source_cluster: { key: source_cluster } }` | -| `destination_cluster` | `{ destination_cluster: { key: destination_cluster }` } | -| `remote_address` | `{ remote_address: { key: remote_address } }` | -| `{ my_key: { header: my_hdr } }` | `{ generic_key: { value: my_val } }` | -| `{ my_val }` | `{ generic_key: { value: my_val } }` | -| `{ my_key: { header: my_hdr } }` | `{ request_headers: { key: my_key, header_name: my_hdr } }` | - -You can check the [Rate Limiting Labels documentation](../../using/rate-limits#attaching-labels-to-requests) -for more examples. - -## 9. `tls` cannot be `true` in `AuthService`, `Mapping`, `RateLimitService`, and `TCPMapping` - - - Learn more about AuthService
- Learn more about Mapping
- Learn more about RateLimitService
- Learn more about TCPMapping - - -The `tls` element in `AuthService`, `Mapping`, `RateLimitService`, and `TCPMapping` controls TLS -origination. In `getambassador.io/v2`, it may be a string naming a `TLSContext` to use to determine -which client certificate is sent, or the boolean value `true` to request TLS origination with no -cluent certificate being sent. - -In `getambassador.io/v3alpha1`, only the string form is supported. To originate TLS with no client -certificate (the semantic of `tls: true`), omit the `tls` element and prefix the `service` with -`https://`. Note that `TCPMapping` in `getambassador.io/v2` does not support the `https://prefix`. - -## 10. Some `Module` settings have moved or changed - - - Learn more about Listener - - -A few settings have moved from the `Module` in 2.0. Make sure you review the following settings -and move them to their new locations if you are using them in a `Module`: - -- Configuration for the `PROXY` protocol is part of the `Listener` resource in $productName$ 2.0, -so the `use_proxy_protocol` element of the `ambassador` `Module` is no longer supported. - -- `xff_num_trusted_hops` has been removed from the `Module`, and its functionality has been moved -to the `l7Depth` setting in the `Listener` resource. - -- It is no longer possible to configure TLS using the `tls` element of the `Module`. Its -functionality is fully covered by the `TLSContext` resource. diff --git a/content/en/docs/3.0/topics/install/docker.md b/content/en/docs/3.0/topics/install/docker.md deleted file mode 100644 index e430a55c..00000000 --- a/content/en/docs/3.0/topics/install/docker.md +++ /dev/null @@ -1,73 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Run the demo with Docker - -In this Docker quickstart guide, we'll get $productName$ running locally -with a demo configuration. In the next section, we'll then walk through how to -deploy $productName$ in Kubernetes with a custom configuration. - -## 1. Running the demo configuration - -By default, $productName$ uses a demo configuration to show some of its basic features. Get it running with Docker, and expose $productName$ on port 8080: - -``` -docker run -it -p 8080:8080 --name=$productDeploymentName$ --rm docker.io/emissaryingress/emissary:$version$ --demo -``` - -## 2. $productName$'s diagnostics - -$productName$ provides live diagnostics viewable with a web browser. While this would normally not be exposed to the public network, the Docker demo publishes the diagnostics service at the following URL: - -`http://localhost:8080/ambassador/v0/diag/` - -You'll have to authenticate to view this page: use the username `admin`, -password `admin` (obviously this would be a poor choice in the real world!). -We'll talk more about authentication shortly. - -To access the Diagnostics page with authentication, use `curl http://localhost:8080/ambassador/v0/diag/ -u admin:admin` - -Some of the most important information - your $productName$ version, how recently $productName$'s configuration was updated, and how recently Envoy last reported status to $productName$ - is right at the top. The diagnostics overview can show you what it sees in your configuration map, and which Envoy objects were created based on your configuration. - -## 3. The Quote service - -Since $productName$ is a comprehensive, self-service edge stack, its primary purpose is to provide access and control to microservices for the teams that manage them. The demo is preconfigured with a mapping that connects the `/qotm/` resource to the "Quote" service -- a demo service that supplies quotations. You can try it out by opening - -`http://localhost:8080/qotm/` - -in your browser, or from the command line as - -``` -curl -L 'http://localhost:8080/qotm/?json=true' -``` - -This request will route to the `qotm` service at `demo.getambassador.io`, and return a random quote. - -You can see details of the mapping by clicking the blue `http://localhost:8080/qotm/` link at the very bottom of the `Ambassador Route Table` in the diagnostics overview. - -## 4. Authentication - -On the diagnostic overview, you can also see that $productName$ is configured to do authentication -- in the middle of the overview page, you'll see the `Ambassador Services In Use` section, and you can click the `tcp://127.0.0.1:5050` link for details on the `AuthService` configuration. This demo auth service is running inside the Docker container with $productName$ and the Quote service, and $productName$ uses it to mediate access to everything behind $productName$. - -You saw above that access to the diagnostic overview required you to authenticate as an administrator. Getting a random quote does not require authentication, but to get a specific quote, you'll have to authenticate as a demo user. To see this in action, open - -`http://localhost:8080/qotm/quote/5` - -in your browser. From the command line, you can see that: - -``` -curl -Lv 'http://localhost:8080/qotm/quote/5?json=true' -``` - -will return a 401, but - -``` -curl -Lv -u username:password 'http://localhost:8080/qotm/quote/5?json=true' -``` - -will succeed. (Note that that's literally "username" and "password" -- the demo auth service is deliberately not very secure!) - -Note that it's up to the auth service to decide what needs authentication -- teaming $productName$ with an authentication service can be as flexible or strict as you need it to be. - -## Next steps - -We've just walked through some of the core features of $productName$ in a local configuration. To see $productName$ in action on Kubernetes, check out the [Installation Guide](../). diff --git a/content/en/docs/3.0/topics/install/helm.md b/content/en/docs/3.0/topics/install/helm.md deleted file mode 100644 index 4c8a9836..00000000 --- a/content/en/docs/3.0/topics/install/helm.md +++ /dev/null @@ -1,102 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Install with Helm - - - - To migrate from $productName$ 1.X to $productName$ 2.X, see the - [$productName$ migration matrix](../migration-matrix/). This guide - **will not work** for that, due to changes to the configuration - resources used for $productName$ 2.X. - - - -[Helm](https://helm.sh) is a package manager for Kubernetes that automates the release and management of software on Kubernetes. $productName$ can be installed via a Helm chart with a few simple steps, depending on if you are deploying for the first time, upgrading $productName$ from an existing installation, or migrating from $productName$. - -## Before you begin - -The $productName$ Helm chart is hosted by Datawire and published at `https://app.getambassador.io`. - -Start by adding this repo to your helm client with the following command: - -``` -helm repo add datawire https://app.getambassador.io -helm repo update -``` - -## Install with Helm - -When you run the Helm chart, it installs $productName$. - -1. Install the $productName$ CRDs. - - Before installing $productName$ $version$ itself, you must configure your - Kubernetes cluster to support the `getambassador.io/v3alpha1` and `getambassador.io/v2` - configuration resources. This is required. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. Install the $productName$ Chart with the following command: - - ``` - helm install -n $productNamespace$ --create-namespace \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - -3. Next Steps - - $productName$ shold now be successfully installed and running, but in order to get started deploying Services and test routing to them you need to configure a few more resources. - - - [The `Listener` Resource](../../running/listener/) is required to configure which ports the $productName$ pods listen on so that they can begin responding to requests. - - [The `Mapping` Resouce](../../using/intro-mappings/) is used to configure routing requests to services in your cluster. - - [The `Host` Resource](../../running/host-crd/) configures TLS termination for enablin HTTPS communication. - - Explore how $productName$ [configures communication with clients](../../../howtos/configure-communications) - - - We strongly recommend following along with our Quickstart Guide to get started by creating a Listener, deploying a simple service to test with, and setting up a Mapping to route requests from $productName$ to the demo service. - - - - $productName$ $version$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - -For more advanced configuration and details about helm values, -[please see the helm chart.](https://artifacthub.io/packages/helm/datawire/emissary-ingress/) - -## Upgrading an existing installation - -See the [migration matrix](../migration-matrix) for instructions about upgrading -$productName$. diff --git a/content/en/docs/3.0/topics/install/index.less b/content/en/docs/3.0/topics/install/index.less deleted file mode 100644 index bc649e7c..00000000 --- a/content/en/docs/3.0/topics/install/index.less +++ /dev/null @@ -1,57 +0,0 @@ -@media (max-width: 769px) { - #index-installContainer { - flex-direction: column; - } - .index-dropdown { - width: auto; - } - .index-dropBtn { - width: 100%; - } -} - -.index-dropBtn { - background-color: #8e77ff; - color: white; - padding: 10px; - font-size: 16px; - border: none; - margin-top: -20px; -} - -.index-dropdown { - position: relative; - display: inline-block; -} - -.index-dropdownContent { - display: none; - position: absolute; - background-color: #f1f1f1; - width: 100%; - box-shadow: 0px 8px 16px 0px rgba(0, 0, 0, 0.2); - z-index: 1; -} - -.index-dropdownContent a { - color: black; - padding: 12px 16px; - text-decoration: none; - display: block; -} - -.index-dropdownContent a:hover { - background-color: #ddd; -} - -.index-dropdown:hover .index-dropdownContent { - display: block; -} - -.index-dropdown:hover .index-dropBtn { - background-color: #5f3eff; -} - -#index-installContainer { - display: flex; -} diff --git a/content/en/docs/3.0/topics/install/index.md b/content/en/docs/3.0/topics/install/index.md deleted file mode 100644 index 40fa95fd..00000000 --- a/content/en/docs/3.0/topics/install/index.md +++ /dev/null @@ -1,47 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; -import './index.less' - -# Installing $productName$ - -## 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/content/en/docs/3.0/topics/install/migrate-to-2-alternate.md b/content/en/docs/3.0/topics/install/migrate-to-2-alternate.md deleted file mode 100644 index 0b4b6743..00000000 --- a/content/en/docs/3.0/topics/install/migrate-to-2-alternate.md +++ /dev/null @@ -1,40 +0,0 @@ ---- - 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$ 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/content/en/docs/3.0/topics/install/migrate-to-3-alternate.md b/content/en/docs/3.0/topics/install/migrate-to-3-alternate.md deleted file mode 100644 index d0b791a1..00000000 --- a/content/en/docs/3.0/topics/install/migrate-to-3-alternate.md +++ /dev/null @@ -1,36 +0,0 @@ -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/content/en/docs/3.0/topics/install/migration-matrix.md b/content/en/docs/3.0/topics/install/migration-matrix.md deleted file mode 100644 index eca67369..00000000 --- a/content/en/docs/3.0/topics/install/migration-matrix.md +++ /dev/null @@ -1,44 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrading $productName$ - - - Read the instructions below before making any changes to your cluster! - - -There are currently multiple paths for upgrading $productName$, depending on what version you're currently -running, what you want to be running, and whether you installed $productName$ using [Helm](../helm) or -YAML. - -(To check out if you installed $productName$ using Helm, run `helm list --all` and see if -$productName$ is listed. If so, you installed using Helm.) - - - Read the instructions below before making any changes to your cluster! - - -## If you are currently running $AESproductName$ - -See the [instructions on updating $AESproductName$](../../../../../edge-stack/$aesDocsVersion$/topics/install/migration-matrix). - -## If you installed $OSSproductName$ using Helm - -| If you're running. | You can upgrade to | -|----------------------------------|----------------------------------------------------------------------------------------------------------------------------| -| $OSSproductName$ $version$ | [$AESproductName$ $aesVersion$](/docs/edge-stack/$aesDocsVersion$/topics/install/upgrade/helm/emissary-3.0/edge-stack-3.0) | -| $OSSproductName$ $versionTwoX$ | [$OSSproductName$ $version$](../upgrade/helm/emissary-2.3/emissary-3.0) | -| $OSSproductName$ 2.2.X | [$OSSproductName$ $versionTwoX$](../upgrade/helm/emissary-2.2/emissary-2.3) | -| $OSSproductName$ 2.0.5 | [$OSSproductName$ $versionTwoX$](../upgrade/helm/emissary-2.0/emissary-2.3) | -| $OSSproductName$ $versionOneX$ | [$OSSproductName$ $versionTwoX$](../upgrade/helm/emissary-1.14/emissary-2.3) | -| $OSSproductName$ prior to $versionOneX$ | [$OSSproductName$ $versionOneX$](../../../../1.14/topics/install/upgrading) | - -## If you installed $OSSproductName$ manually by applying YAML - -| If you're running. | You can upgrade to | -|----------------------------------|----------------------------------------------------------------------------------------------------------------------------| -| $OSSproductName$ $version$ | [$AESproductName$ $aesVersion$](/docs/edge-stack/$aesDocsVersion$/topics/install/upgrade/yaml/emissary-3.0/edge-stack-3.0) | -| $OSSproductName$ $versionTwoX$ | [$OSSproductName$ $version$](../upgrade/yaml/emissary-2.3/emissary-3.0) | -| $OSSproductName$ 2.2.X | [$OSSproductName$ $versionTwoX$](../upgrade/yaml/emissary-2.2/emissary-2.3) | -| $OSSproductName$ 2.0.5 | [$OSSproductName$ $versionTwoX$](../upgrade/yaml/emissary-2.0/emissary-2.3) | -| $OSSproductName$ $versionOneX$ | [$OSSproductName$ $versionTwoX$](../upgrade/yaml/emissary-1.14/emissary-2.3) | -| $OSSproductName$ prior to $versionOneX$ | [$OSSproductName$ $versionOneX$](../../../../1.14/topics/install/upgrading) | diff --git a/content/en/docs/3.0/topics/install/upgrade/helm/emissary-1.14/emissary-2.3.md b/content/en/docs/3.0/topics/install/upgrade/helm/emissary-1.14/emissary-2.3.md deleted file mode 100644 index 46428e0e..00000000 --- a/content/en/docs/3.0/topics/install/upgrade/helm/emissary-1.14/emissary-2.3.md +++ /dev/null @@ -1,312 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 1.14.X to $productName$ $versionTwoX$ (Helm) - - - This guide covers migrating from $productName$ 1.14.X to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -We're pleased to introduce $productName$ $versionTwoX$! The 2.X family introduces a number of -changes to allow $productName$ to more gracefully handle larger installations (including -multitenant or multiorganizational installations), reduce memory footprint, and improve -performance. In keeping with [SemVer](https://semver.org), $productName$ 2.X introduces -some changes that aren't backward-compatible with 1.X. These changes are detailed in -[Major Changes in $productName$ 2.X](../../../../../../about/changes-2.x/). - -## Migration Overview - - - Read the migration instructions below before making any changes to your - cluster! - - -The recommended strategy for migration is to run $productName$ 1.14 and $productName$ -$versionTwoX$ side-by-side in the same cluster. This gives $productName$ $versionTwoX$ -and $productName$ 1.14 access to all the same configuration resources, with some -important caveats: - -1. **$productName$ 1.14 will not see any `getambassador.io/v3alpha1` resources.** - - This is intentional; it provides a way to apply configuration only to - $productName$ $versionTwoX$, while not interfering with the operation of your - $productName$ 1.14 installation. - -2. **If needed, you can use labels to further isolate configurations.** - - If you need to prevent your $productName$ $versionTwoX$ installation from - seeing a particular bit of $productName$ 1.14 configuration, you can apply - a Kubernetes label to the configuration resources that should be seen by - your $productName$ $versionTwoX$ installation, then set its - `AMBASSADOR_LABEL_SELECTOR` environment variable to restrict its 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$ $versionTwoX$, then set - `AMBASSADOR_LABEL_SELECTOR=version-two=true` in its Deployment. - -3. **Be careful about label selectors on Kubernetes Services!** - - If you have services in $productName$ 1.14 that use selectors that will match - Pods from $productName$ $versionTwoX$, traffic will be erroneously split between - $productName$ 1.14 and $productName$ $versionTwoX$. The labels used by $productName$ - $versionTwoX$ include: - - ```yaml - app.kubernetes.io/name: emissary-ingress - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/part-of: emissary-ingress - app.kubernetes.io/managed-by: getambassador.io - product: aes - profile: main - ``` - -4. **Be careful to only have one $productName$ Agent running at a time.** - - The $productName$ Agent is responsible for communications between - $productName$ and Ambassador Cloud. If multiple versions of the Agent are - running simultaneously, Ambassador Cloud could see conflicting information - about your cluster. - - The best way to avoid multiple agents when installing with Helm is to use - `--set agent.enabled=false` to tell Helm not to install a new Agent with - $productName$ $versionTwoX$. Once testing is done, you can switch Agents safely. - -You can also migrate by [installing $productName$ $versionTwoX$ in a separate cluster](../../../../migrate-to-2-alternate). -This permits absolute certainty that your $productName$ 1.14 configuration will not be -affected by changes meant for $productName$ $versionTwoX$, and it eliminates concerns about -ACME, but it is more effort. - -## Side-by-Side Migration Steps - -Migration is a seven-step process: - -1. **Make sure that older configuration resources are not present.** - - $productName$ 2.X does not support `getambassador.io/v0` or `getambassador.io/v1` - resources, and Kubernetes will not permit removing support for CRD versions that are - still in use for stored resources. To verify that no resources older than - `getambassador.io/v2` are active, run - - ``` - kubectl get crds -o 'go-template={{range .items}}{{.metadata.name}}={{.status.storedVersions}}{{"\n"}}{{end}}' | fgrep getambassador.io - ``` - - If `v1` is present in the output, **do not begin migration.** The old resources must be - converted to `getambassador.io/v2` and the `storedVersion` information in the cluster - must be updated. If necessary, contact Ambassador Labs on [Slack](http://a8r.io/slack) - for more information. - -2. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you must configure your - Kubernetes cluster to support its new `getambassador.io/v3alpha1` configuration - resources. Note that `getambassador.io/v2` resources are still supported, but **you - must install support for `getambassador.io/v3alpha1`** to run $productName$ $versionTwoX$, - even if you intend to continue using only `getambassador.io/v2` resources for some - time. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -3. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, you need to install $productName$ $versionTwoX$ itself - **in the same namespace as your existing $productName$ 1.14 installation**. It's important - to use the same namespace so that the two installations can see the same secrets, etc. - - Start by making sure that your `emissary` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Typically, $productName$ 1.14 was installed in the `ambassador` namespace. If you installed - $productName$ 1.14 in a different namespace, change the namespace in the commands below. - - - If you do not need to set `AMBASSADOR_LABEL_SELECTOR`: - - ```bash - helm install -n ambassador \ - --set agent.enabled=false \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - - - If you do need to set `AMBASSADOR_LABEL_SELECTOR`, use `--set`, for example: - - ```bash - helm install -n ambassador \ - --set agent.enabled=false \ - --set env.AMBASSADOR_LABEL_SELECTOR="version-two=true" \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 2.X. - Do not use the ambassador Helm chart. - - - - $productName$ $versionTwoX$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - -4. **Install `Listener`s and `Host`s as needed.** - - An important difference between $productName$ 1.14 and $productName$ $versionTwoX$ is the - new **mandatory** `Listener` CRD. Also, when running both installations side by side, - you will need to make sure that a `Host` is present for the new $productName$ $versionTwoX$ - Service. For example: - - ```bash - kubectl apply -f - < - Kubernetes will not allow you to have a 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.
-
- If you find that your $productName$ $versionTwoX$ installation and your $productName$ 1.14 - installation absolutely must have resources that are only seen by one version or the - other way, see overview section 2, "If needed, you can use labels to further isolate configurations". - - - **If you find that you need to roll back**, just reinstall your 1.14 CRDs and delete your - installation of $productName$ $versionTwoX$. - -6. **When ready, switch over to $productName$ $versionTwoX$.** - - You can run $productName$ 1.14 and $productName$ $versionTwoX$ side-by-side as long as you care - to. However, taking full advantage of $productName$ 2.X's capabilities **requires** - [updating your configuration to use `getambassador.io/v3alpha1` configuration resources](../../../../convert-to-v3alpha1), - since some useful features in $productName$ $versionTwoX$ are only available using - `getambassador.io/v3alpha1` resources. - - When you're ready to have $productName$ $versionTwoX$ handle traffic on its own, switch - your original $productName$ 1.14 Service to point to $productName$ $versionTwoX$. Use - `kubectl edit service ambassador` and change the `selectors` to: - - ``` - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/name: emissary-ingress - profile: main - ``` - - Repeat using `kubectl edit service ambassador-admin` for the `ambassador-admin` - Service. - -7. **Finally, install the $productName$ $versionTwoX$ Ambassador Agent.** - - First, scale the 1.14 agent to 0: - - ``` - kubectl scale -n ambassador deployment/ambassador-agent --replicas=0 - ``` - - Once that's done, install the new Agent. **Note that if you needed to set - `AMBASSADOR_LABEL_SELECTOR`, you must add that to this `helm upgrade` command.** - - ```bash - helm upgrade -n ambassador \ - --set agent.enabled=true \ - $productHelmName$ datawire/$productHelmName$ \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - -Congratulations! At this point, $productName$ $versionTwoX$ is fully running and it's safe to remove the `ambassador` and `ambassador-agent` Deployments: - -``` -kubectl delete deployment/ambassador deployment/ambassador-agent -``` - -Once $productName$ 1.14 is no longer running, you may [convert](../../../../convert-to-v3alpha1) -any remaining `getambassador.io/v2` resources to `getambassador.io/v3alpha1`. -You may also want to redirect DNS to the `edge-stack` Service and remove the -`ambassador` Service. diff --git a/content/en/docs/3.0/topics/install/upgrade/helm/emissary-2.0/emissary-2.3.md b/content/en/docs/3.0/topics/install/upgrade/helm/emissary-2.0/emissary-2.3.md deleted file mode 100644 index 150ad270..00000000 --- a/content/en/docs/3.0/topics/install/upgrade/helm/emissary-2.0/emissary-2.3.md +++ /dev/null @@ -1,75 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.0.5 to $productName$ $versionTwoX$ (Helm) - - - This guide covers migrating from $productName$ 2.0.5 to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster; Helm will not do this for you. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, use Helm to install $productName$ $versionTwoX$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 2.X. - Do not use the ambassador Helm chart. - diff --git a/content/en/docs/3.0/topics/install/upgrade/helm/emissary-2.2/emissary-2.3.md b/content/en/docs/3.0/topics/install/upgrade/helm/emissary-2.2/emissary-2.3.md deleted file mode 100644 index f20a49a3..00000000 --- a/content/en/docs/3.0/topics/install/upgrade/helm/emissary-2.2/emissary-2.3.md +++ /dev/null @@ -1,75 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.2.X to $productName$ $versionTwoX$ (Helm) - - - This guide covers migrating from $productName$ 2.2.0 or 2.2.2 to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster; Helm will not do this for you. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, use Helm to install $productName$ $versionTwoX$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 2.X. - Do not use the ambassador Helm chart. - diff --git a/content/en/docs/3.0/topics/install/upgrade/helm/emissary-2.3/emissary-3.0.md b/content/en/docs/3.0/topics/install/upgrade/helm/emissary-2.3/emissary-3.0.md deleted file mode 100644 index 04f0a6e9..00000000 --- a/content/en/docs/3.0/topics/install/upgrade/helm/emissary-2.3/emissary-3.0.md +++ /dev/null @@ -1,131 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.3.Z to $productName$ $version$ (Helm) - - - This guide covers migrating from $productName$ 2.3.Z to $productName$ $version$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - - - Make sure that you have updated any 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$. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -$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. - -### Resources to check before migrating to $version$. - -$productName$ 3.0 has been upgraded from Envoy 1.17.X to Envoy 1.22 which removed support for the Envoy V2 Transport Protocol. This means all `AuthService`, `RatelimitService`, and `LogServices` must be updated to use the V3 Protocol. Additionally support for some of the runtime bootstrap flags has been removed. - -You can refer to the [Major changes in $productName$ 3.x](../../../../../../about/changes-3.y/) guide for an overview of the changes. - -1. Check Transport Protocol usage on all resources before migrating. - - The `AuthService`, `RatelimitService`, and `LogServices` 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. - - `protocol_version` should be updated to `v3` for all of the above resources while still running $productName$ $versionTwoX$. As of version `2.3.z`+, support for `protocol_version` `v2` and `v3` is supported in order to allow migration from `protocol_version` `v2` to `v3` before upgrading to $productName$ $version$ where support for `v2` is removed. - - Upgrading any application code for your own implementations of these services is very straightforward. - - The following imports simply need to be updated to switch from Envoy's Transport Protocol `v2` to `v3`, and then the configuration for these resources can be updated to add the `protocl_version: "v3"` when the updated service is deployed. - - `v2` Imports: - ``` - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" - ``` - - `v3` Imports: - ``` - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" - ``` - -2. Check removed runtime changes - - ``` - # 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, - - # Developers 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, - ``` - -3. **Install new CRDs.** - - After reviewing the changes in 3.x and confirming that you are ready to upgrade, the process is the same as upgrading minor versions - in previous version of $productName$ and does not require the complex migration steps that the migration from 1.x tto 2.x required. - - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -4. **Install $productName$ $version$.** - - After installing the new CRDs, use Helm to install $productName$ $version$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 3.Y. - diff --git a/content/en/docs/3.0/topics/install/upgrade/yaml/emissary-1.14/emissary-2.3.md b/content/en/docs/3.0/topics/install/upgrade/yaml/emissary-1.14/emissary-2.3.md deleted file mode 100644 index 613eb690..00000000 --- a/content/en/docs/3.0/topics/install/upgrade/yaml/emissary-1.14/emissary-2.3.md +++ /dev/null @@ -1,282 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 1.14.X to $productName$ $versionTwoX$ (YAML) - - - This guide covers migrating from $productName$ 1.14.X to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -We're pleased to introduce $productName$ $versionTwoX$! The 2.X family introduces a number of -changes to allow $productName$ to more gracefully handle larger installations (including -multitenant or multiorganizational installations), reduce memory footprint, and improve -performance. In keeping with [SemVer](https://semver.org), $productName$ 2.X introduces -some changes that aren't backward-compatible with 1.X. These changes are detailed in -[Major Changes in $productName$ 2.X](../../../../../../about/changes-2.x/). - -## Migration Overview - - - Read the migration instructions below before making any changes to your - cluster! - - -The recommended strategy for migration is to run $productName$ 1.14 and $productName$ -$versionTwoX$ side-by-side in the same cluster. This gives $productName$ $versionTwoX$ -and $productName$ 1.14 access to all the same configuration resources, with some -important caveats: - -1. **$productName$ 1.14 will not see any `getambassador.io/v3alpha1` resources.** - - This is intentional; it provides a way to apply configuration only to - $productName$ $versionTwoX$, while not interfering with the operation of your - $productName$ 1.14 installation. - -2. **If needed, you can use labels to further isolate configurations.** - - If you need to prevent your $productName$ $versionTwoX$ installation from - seeing a particular bit of $productName$ 1.14 configuration, you can apply - a Kubernetes label to the configuration resources that should be seen by - your $productName$ $versionTwoX$ installation, then set its - `AMBASSADOR_LABEL_SELECTOR` environment variable to restrict its 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$ $versionTwoX$, then set - `AMBASSADOR_LABEL_SELECTOR=version-two=true` in its Deployment. - -3. **Be careful about label selectors on Kubernetes Services!** - - If you have services in $productName$ 1.14 that use selectors that will match - Pods from $productName$ $versionTwoX$, traffic will be erroneously split between - $productName$ 1.14 and $productName$ $versionTwoX$. The labels used by $productName$ - $versionTwoX$ include: - - ```yaml - app.kubernetes.io/name: emissary-ingress - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/part-of: emissary-ingress - app.kubernetes.io/managed-by: getambassador.io - product: aes - profile: main - ``` - -4. **Be careful to only have one $productName$ Agent running at a time.** - - The $productName$ Agent is responsible for communications between - $productName$ and Ambassador Cloud. If multiple versions of the Agent are - running simultaneously, Ambassador Cloud could see conflicting information - about your cluster. - - The migration YAML used below to install $productName$ $versionTwoX$ will not - install a duplicate agent. If you are building your own YAML, make sure not - to include a duplicate agent. - -You can also migrate by [installing $productName$ $versionTwoX$ in a separate cluster](../../../../migrate-to-2-alternate). -This permits absolute certainty that your $productName$ 1.14 configuration will not be -affected by changes meant for $productName$ $versionTwoX$, and it eliminates concerns about -ACME, but it is more effort. - -## Side-by-Side Migration Steps - -Migration is a seven-step process: - -1. **Make sure that older configuration resources are not present.** - - $productName$ 2.X does not support `getambassador.io/v0` or `getambassador.io/v1` - resources, and Kubernetes will not permit removing support for CRD versions that are - still in use for stored resources. To verify that no resources older than - `getambassador.io/v2` are active, run - - ``` - kubectl get crds -o 'go-template={{range .items}}{{.metadata.name}}={{.status.storedVersions}}{{"\n"}}{{end}}' | fgrep getambassador.io - ``` - - If `v1` is present in the output, **do not begin migration.** The old resources must be - converted to `getambassador.io/v2` and the `storedVersion` information in the cluster - must be updated. If necessary, contact Ambassador Labs on [Slack](http://a8r.io/slack) - for more information. - -2. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you must configure your - Kubernetes cluster to support its new `getambassador.io/v3alpha1` configuration - resources. Note that `getambassador.io/v2` resources are still supported, but **you - must install support for `getambassador.io/v3alpha1`** to run $productName$ $versionTwoX$, - even if you intend to continue using only `getambassador.io/v2` resources for some - time. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -3. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, you need to install $productName$ $versionTwoX$ itself - **in the same namespace as your existing $productName$ 1.14 installation**. It's important - to use the same namespace so that the two installations can see the same secrets, etc. - - We publish two manifests for different namespaces. Use only the one that - matches the namespace into which you installed $productName$ 1.14: - - - [`emissary-emissaryns.yaml`] for the `emissary` namespace; or - - [`emissary-defaultns.yaml`] for the `default` namespace. - - If you installed $productName$ 1.14 into some other namespace, you'll need to - download one of the files and edit it to match your namespace. - - [`emissary-emissaryns.yaml`]: https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-emissaryns.yaml - [`emissary-defaultns.yaml`]: https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-defaultns.yaml - - **If you need to set `AMBASSADOR_LABEL_SELECTOR`**, you'll need to download - your chosen file and and edit it to do so. - - Assuming that you're using the `default` namespace: - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-defaultns.yaml && \ - kubectl rollout status -n default deployment/edge-stack -w - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - -4. **Install `Listener`s and `Host`s as needed.** - - An important difference between $productName$ 1.14 and $productName$ $versionTwoX$ is the - new **mandatory** `Listener` CRD. Also, when running both installations side by side, - you will need to make sure that a `Host` is present for the new $productName$ $versionTwoX$ - Service. For example: - - ```bash - kubectl apply -f - < - Kubernetes will not allow you to have a 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.
-
- If you find that your $productName$ $versionTwoX$ installation and your $productName$ 1.14 - installation absolutely must have resources that are only seen by one version or the - other way, see overview section 2, "If needed, you can use labels to further isolate configurations". - - - **If you find that you need to roll back**, just reinstall your 1.14 CRDs and delete your - installation of $productName$ $versionTwoX$. - -6. **When ready, switch over to $productName$ $versionTwoX$.** - - You can run $productName$ 1.14 and $productName$ $versionTwoX$ side-by-side as long as you care - to. However, taking full advantage of $productName$ 2.X's capabilities **requires** - [updating your configuration to use `getambassador.io/v3alpha1` configuration resources](../../../../convert-to-v3alpha1), - since some useful features in $productName$ $versionTwoX$ are only available using - `getambassador.io/v3alpha1` resources. - - When you're ready to have $productName$ $versionTwoX$ handle traffic on its own, switch - your original $productName$ 1.14 Service to point to $productName$ $versionTwoX$. Use - `kubectl edit service ambassador` and change the `selectors` to: - - ``` - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/name: emissary-ingress - profile: main - ``` - - Repeat using `kubectl edit service ambassador-admin` for the `ambassador-admin` - Service. - - -Congratulations! At this point, $productName$ $versionTwoX$ is fully running and it's safe to remove the `ambassador` and `ambassador-agent` Deployments: - -``` -kubectl delete deployment/ambassador deployment/ambassador-agent -``` - -Once $productName$ 1.14 is no longer running, you may [convert](../../../../convert-to-v3alpha1) -any remaining `getambassador.io/v2` resources to `getambassador.io/v3alpha1`. -You may also want to redirect DNS to the `edge-stack` Service and remove the -`ambassador` Service. diff --git a/content/en/docs/3.0/topics/install/upgrade/yaml/emissary-2.0/emissary-2.3.md b/content/en/docs/3.0/topics/install/upgrade/yaml/emissary-2.0/emissary-2.3.md deleted file mode 100644 index 7879e6ed..00000000 --- a/content/en/docs/3.0/topics/install/upgrade/yaml/emissary-2.0/emissary-2.3.md +++ /dev/null @@ -1,65 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.0.5 to $productName$ $versionTwoX$ (YAML) - - - This guide covers migrating from $productName$ 2.0.5 to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, upgrade $productName$ $versionTwoX$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/3.0/topics/install/upgrade/yaml/emissary-2.2/emissary-2.3.md b/content/en/docs/3.0/topics/install/upgrade/yaml/emissary-2.2/emissary-2.3.md deleted file mode 100644 index 20674389..00000000 --- a/content/en/docs/3.0/topics/install/upgrade/yaml/emissary-2.2/emissary-2.3.md +++ /dev/null @@ -1,65 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.2.X to $productName$ $versionTwoX$ (YAML) - - - This guide covers migrating from $productName$ 2.2.0 or 2.2.2 to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, upgrade $productName$ $versionTwoX$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/3.0/topics/install/upgrade/yaml/emissary-2.3/emissary-3.0.md b/content/en/docs/3.0/topics/install/upgrade/yaml/emissary-2.3/emissary-3.0.md deleted file mode 100644 index 2d64ba1a..00000000 --- a/content/en/docs/3.0/topics/install/upgrade/yaml/emissary-2.3/emissary-3.0.md +++ /dev/null @@ -1,122 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.3.Z to $productName$ $version$ (YAML) - - - This guide covers migrating from $productName$ 2.3.Z to $productName$ $version$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - - - Make sure that you have updated any 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$. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading -between versions is straightforward. - -$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. - -### Resources to check before migrating to $version$. - -$productName$ 3.0 has been upgraded from Envoy 1.17.X to Envoy 1.22 which removed support for the Envoy V2 Transport Protocol. This means all `AuthService`, `RatelimitService`, and `LogServices` must be updated to use the V3 Protocol. Additionally support for some of the runtime bootstrap flags has been removed. - -You can refer to the [Major changes in $productName$ 3.x](../../../../../../about/changes-3.y/) guide for an overview of the changes. - -1. Check Transport Protocol usage on all resources before migrating. - - The `AuthService`, `RatelimitService`, and `LogServices` 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. - - `protocol_version` should be updated to `v3` for all of the above resources while still running $productName$ $versionTwoX$. As of version `2.3.z`+, support for `protocol_version` `v2` and `v3` is supported in order to allow migration from `protocol_version` `v2` to `v3` before upgrading to $productName$ $version$ where support for `v2` is removed. - - Upgrading any application code for your own implementations of these services is very straightforward. - - The following imports simply need to be updated to switch from Envoy's Transport Protocol `v2` to `v3`, and then the configuration for these resources can be updated to add the `protocl_version: "v3"` when the updated service is deployed. - - `v2` Imports: - ``` - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" - ``` - - `v3` Imports: - ``` - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" - ``` - -2. Check removed runtime changes - - ``` - # 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, - - # Developers 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, - ``` - -3. **Install new CRDs.** - - After reviewing the changes in 3.x and confirming that you are ready to upgrade, the process is the same as upgrading minor versions - in previous version of $productName$ and does not require the complex migration steps that the migration from 1.x tto 2.x required. - - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -4. **Install $productName$ $version$.** - - After installing the new CRDs, upgrade $productName$ $version$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/3.0/topics/install/yaml-install.md b/content/en/docs/3.0/topics/install/yaml-install.md deleted file mode 100644 index b28e6265..00000000 --- a/content/en/docs/3.0/topics/install/yaml-install.md +++ /dev/null @@ -1,87 +0,0 @@ ---- - description: In this guide, we'll walk through the process of deploying $productName$ in Kubernetes for ingress routing. ---- - -import Alert from '@material-ui/lab/Alert'; - -# Install manually - - - - To migrate from $productName$ 1.X to $productName$ 2.X, see the - [$productName$ migration matrix](../migration-matrix/). This guide - **will not work** for that, due to changes to the configuration - resources used for $productName$ 2.X. - - - -In this guide, we'll walk you through installing $productName$ in your Kubernetes cluster. - -The manual install process does not allow for as much control over configuration -as the [Helm install method](../helm), so if you need more control over your $productName$ -installation, it is recommended that you use helm. - -## Before you begin - -$productName$ is designed to run in Kubernetes for production. The most essential requirements are: - -* Kubernetes 1.11 or later -* The `kubectl` command-line tool - -## Install with YAML - -$productName$ is typically deployed to Kubernetes from the command line. If you don't have Kubernetes, you should use our [Docker](../docker) image to deploy $productName$ locally. - -1. In your terminal, run the following command: - - ``` - kubectl create namespace $productNamespace$ || true - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml && \ - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-emissaryns.yaml && \ - kubectl -n $productNamespace$ wait --for condition=available --timeout=90s deploy $productDeploymentName$ - ``` - - - $productName$ $version$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. Determine the IP address or hostname of your cluster by running the following command: - - ``` - kubectl get -n $productNamespace$ service $productDeploymentName$ -o "go-template={{range .status.loadBalancer.ingress}}{{or .ip .hostname}}{{end}}" - ``` - - Your load balancer may take several minutes to provision your IP address. Repeat the provided command until you get an IP address. - -3. Next Steps - - $productName$ shold now be successfully installed and running, but in order to get started deploying Services and test routing to them you need to configure a few more resources. - - - [The `Listener` Resource](../../running/listener/) is required to configure which ports the $productName$ pods listen on so that they can begin responding to requests. - - [The `Mapping` Resouce](../../using/intro-mappings/) is used to configure routing requests to services in your cluster. - - [The `Host` Resource](../../running/host-crd/) configures TLS termination for enablin HTTPS communication. - - Explore how $productName$ [configures communication with clients](../../../howtos/configure-communications) - - - We strongly recommend following along with our Quickstart Guide to get started by creating a Listener, deploying a simple service to test with, and setting up a Mapping to route requests from $productName$ to the demo service. - - -## Upgrading an existing installation - -See the [migration matrix](../migration-matrix) for instructions about upgrading -$productName$. diff --git a/content/en/docs/3.0/topics/running/ambassador-deployment.md b/content/en/docs/3.0/topics/running/ambassador-deployment.md deleted file mode 100644 index fb559d69..00000000 --- a/content/en/docs/3.0/topics/running/ambassador-deployment.md +++ /dev/null @@ -1,21 +0,0 @@ -# Deployment architecture - -$productName$ can be deployed in a variety of configurations. The specific configuration depends on your data center. - -## Public cloud - -If you're using a public cloud provider such as Amazon, Azure, or Google, $productName$ can be deployed directly to a Kubernetes cluster running in the data center. Traffic is routed to $productName$ via a cloud-managed load balancer such as an Amazon Elastic Load Balancer or Google Cloud Load Balancer. Typically, this load balancer is transparently managed by Kubernetes in the form of the `LoadBalancer` service type. $productName$ then routes traffic to your services running in Kubernetes. - -## On-Premise data center - -In an on-premise data center, $productName$ is deployed on the Kubernetes cluster. Instead of exposing it via the `LoadBalancer` service type, $productName$ is exposed as a `NodePort`. Traffic is sent to a specific port on any of the nodes in the cluster, which route the traffic to $productName$, which then routes the traffic to your services running in Kubernetes. You'll also need to deploy a separate load balancer to route traffic from your core routers to $productName$. [MetalLB](https://metallb.universe.tf/) is an open-source external load balancer for Kubernetes designed for this problem. Other options are traditional TCP load balancers such as F5 or Citrix Netscaler. - -## Hybrid data center - -Many data centers include services that are running outside of Kubernetes on virtual machines. For $productName$ to route to services both inside and outside of Kubernetes, it needs the real-time network location of all services. This problem is known as "[service discovery](https://www.datawire.io/guide/traffic/service-discovery-microservices/)" and $productName$ supports using [Consul](https://www.consul.io). Services in your data center register themselves with Consul, and $productName$ uses Consul-supplied data to dynamically route requests to available services. - -## Hybrid on-premise data center - -The diagram below details a common network architecture for a hybrid on-premise data center. Traffic flows from core routers to MetalLB, which routes to $productName$ running in Kubernetes. $productName$ routes traffic to individual services running on both Kubernetes and VMs. Consul tracks the real-time network location of the services, which $productName$ uses to route to the given services. - -![Architecture](../../../images/consul-ambassador.png) diff --git a/content/en/docs/3.0/topics/running/ambassador-with-aws.md b/content/en/docs/3.0/topics/running/ambassador-with-aws.md deleted file mode 100644 index b321543a..00000000 --- a/content/en/docs/3.0/topics/running/ambassador-with-aws.md +++ /dev/null @@ -1,364 +0,0 @@ -# $productName$ with AWS - -$productName$ is a platform agnostic Kubernetes API gateway. It will run in any distribution of Kubernetes whether it is managed by a cloud provider or on homegrown bare-metal servers. - -This document serves as a reference for different configuration options available when running Kubernetes in AWS. See [Installing $productName$](../../install) for the various installation methods available. - -## Recommended configuration - -There are lot of configuration options available to you when running $productName$ in AWS. While you should read this entire document to understand what is best for you, the following is the recommended configuration when running $productName$ in AWS: - -It is recommended to terminate TLS at $productName$ so you can take advantage of all the TLS configuration options available in $productName$ including setting the allowed TLS versions, setting `alpn_protocol` options, enforcing HTTP -> HTTPS redirection, and [automatic certificate management](../host-crd) in the $productName$. - -When terminating TLS at $productName$, you should deploy a L4 [Network Load Balancer (NLB)](#network-load-balancer-nlb) with the proxy protocol enabled to get the best performance out of your load balancer while still preserving the client IP address. - -The following `Service` should be configured to deploy an NLB with cross zone load balancing enabled (see [NLB notes](#network-load-balancer-nlb) for caveat on the cross-zone-load-balancing annotation). You will need to configure the proxy protocol in the NLB manually in the AWS Console. - -```yaml -apiVersion: v1 -kind: Service -metadata: - name: ambassador - namespace: ambassador - annotations: - service.beta.kubernetes.io/aws-load-balancer-type: "nlb" - service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: "true" -spec: - type: LoadBalancer - ports: - - name: HTTP - port: 80 - targetPort: 8080 - - name: HTTPS - port: 443 - targetPort: 8443 - selector: - service: ambassador -``` - - After deploying the `Service` above and manually enabling the proxy protocol you will need to deploy the following [Ambassador `Module`](../ambassador) to tell $productName$ to use the proxy protocol and then restart $productName$ for the configuration to take effect. - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - use_proxy_proto: true - ``` - - $productName$ will now expect traffic from the load balancer to be wrapped with the proxy protocol so it can read the client IP address. - -## AWS load balancer notes - -AWS provides three types of load balancers: - -### "Classic" Elastic Load Balancer (ELB) - -The ELB is the first generation AWS Elastic Load Balancer. It is the default type of load balancer ensured by a `type: LoadBalancer` `Service` and routes directly to individual EC2 instances. It can be configured to run at layer 4 or layer 7 of the OSI model. See [What is a Classic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/introduction.html) for more details. - -* Ensured by default for a `type: LoadBalancer` `Service` -* Layer 4: TCP, TCP/SSL - * Protocol support - * HTTP(S) - * Websockets - * HTTP/2 - * Connection based load balancing - * Cannot modify the request -* Layer 7: HTTP, HTTPS - * Protocol support - * HTTP(S) - * Request based load balancing - * Can modify the request (append to `X-Forwarded-*` headers) -* Can perform TLS termination - -**Notes:** -- While it has been superseded by the `Network Load Balancer` and `Application Load Balancer` the ELB offers the simplest way of provisioning an L4 or L7 load balancer in Kubernetes. -- All of the [load balancer annotations](#load-balancer-annotations) are respected by the ELB. -- If using the ELB for TLS termination, it is recommended to run in L7 mode so it can modify `X-Forwarded-Proto` correctly. - -### Network Load Balancer (NLB) - -The NLB is a second generation AWS Elastic Load Balancer. It can be ensure by a `type: LoadBalancer` `Service` using an annotation. It can only run at layer 4 of the OSI model and load balances based on connection allowing it to handle millions of requests per second. See [What is a Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/introduction.html) for more details. - -* Can be ensured by a `type: LoadBalancer` `Service` -* Layer 4: TCP, TCP/SSL - * Protocol support - * HTTP(S) - * Websockets - * HTTP/2 - * Connection based load balacing - * Cannot modify the request -* Can perform TLS termination - -**Notes:** -- The NLB is the most efficient load balancer capable of handling millions of requests per second. It is recommended for streaming connections since it will maintain the connection stream between the client and $productName$. -- Most of the [load balancer annotations](#load-balancer-annotations) are respected by the NLB. You will need to manually configure the proxy protocol and take an extra step to enable cross zone load balancing. -- Since it operates at L4 and cannot modify the request, you will need to tell $productName$ if it is terminating TLS or not (see [TLS termination](#tls-termination) notes below). - -### Application Load Balancer (ALB) - -The ALB is a second generation AWS Elastic Load Balancer. It cannot be ensured by a `type: LoadBalancer` `Service` and must be deployed and configured manually. It can only run at layer 7 of the OSI model and load balances based on request information allowing it to perform fine-grained routing to applications. See [What is a Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/introduction.html) for more details. - -* Cannot be configured by a `type: LoadBalancer` `Service` -* Layer 7: HTTP, HTTPS - * Protocol support - * HTTP(S) - * Request based load balancing - * Can modify the request (append to `X-Forwarded-*` headers) -* Can perform TLS termination - -**Notes:** - -- The ALB can perform routing based on the path, headers, host, etc.. Since $productName$ performs this kind of routing in your cluster, unless you are using the same load balancer to route to services outside of Kubernetes, the overhead of provisioning an ALB is often not worth the benefits. -- If you would like to use an ALB, you will need to expose $productName$ with a `type: NodePort` service and manually configure the ALB to forward to the correct ports. -- None of the [load balancer annotations](#load-balancer-annotations) are respected by the ALB. You will need to manually configure all options. -- The ALB will properly set the `X-Forward-Proto` header if terminating TLS. See (see [TLS termination](#tls-termination) notes below). - -## Load balancer annotations - -Kubernetes on AWS exposes a mechanism to request certain load balancer configurations by annotating the `type: LoadBalancer` `Service`. The most complete set and explanations of these annotations can be found in this [Kubernetes document](https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer). This document will go over the subset that is most relevant when deploying $productName$. - -- `service.beta.kubernetes.io/aws-load-balancer-ssl-cert`: - - Configures the load balancer to use a valid certificate ARN to terminate TLS at the Load Balancer. - - Traffic from the client into the load balancer is encrypted but, since TLS is being terminated at the load balancer, traffic from the load balancer to $productName$ will be cleartext. You will need to configure $productName$ differently depending on whether the load balancer is running in L4 or L7 (see [TLS termination](#tls-termination) notes below). - -- `service.beta.kubernetes.io/aws-load-balancer-ssl-ports`: - - Configures which port the load balancer will be listening for SSL traffic on. Defaults to `"*"`. - - If you want to enable cleartext redirection, make sure to set this to `"443"` so traffic on port 80 will come in over cleartext. - -- `service.beta.kubernetes.io/aws-load-balancer-backend-protocol`: - - Configures the ELB to operate in L4 or L7 mode. Can be set to `"tcp"`/`"ssl"` for an L4 listener or `"http"`/`"https"` for an L7 listener. Defaults to `"tcp"` or `"ssl"` if `aws-load-balancer-ssl-cert` is set. - -- `service.beta.kubernetes.io/aws-load-balancer-type: "nlb"`: - - When this annotation is set it will launch a [Network Load Balancer (NLB)](#network-load-balancer-nlb) instead of a classic ELB. - -- `service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled`: - - Configures the load balancer to load balance across zones. For high availability, it is typical to deploy nodes across availability zones so this should be set to `"true"`. - - **Note:** You cannot configure this annotation and `service.beta.kubernetes.io/aws-load-balancer-type: "nlb"` at the same time. You must first deploy the `Service` with an NLB and then update it with the cross zone load balancing configuration. - -- `service.beta.kubernetes.io/aws-load-balancer-proxy-protocol`: - - Configures the ELB to enable the proxy protocol. `"*"`, which enables the proxy protocol on all ELB backends, is the only acceptable value. - - The proxy protocol can be used to preserve the client IP address. - - If setting this value, you need to make sure $productName$ is configured to use the proxy protocol (see [preserving the client IP address](#preserving-the-client-ip-address) below). - - **Note:** This annotation will not be recognized if `aws-load-balancer-type: "nlb"` is configured. Proxy protocol must be manually enabled for NLBs. - -## TLS termination - -TLS termination is an important part of any modern web app. $productName$ exposes a lot of TLS termination configuration options that make it a powerful tool for managing encryption between your clients and microservices. Refer to the [TLS Termination](../tls) documentation for more information on how to configure TLS termination at $productName$. - -With AWS, the AWS Certificate Manager (ACM) makes it easy to configure TLS termination at an AWS load balancer using the annotations explained above. - -This means that, when running $productName$ in AWS, you have the choice between terminating TLS at the load balancer using a certificate from the ACM or at $productName$ using a certificate stored as a `Secret` in your cluster. - -The following documentation will cover the different options available to you and how to configure $productName$ and the load balancer to get the most of each. - -### TLS termination at $productName$ - -Terminating TLS at $productName$ will guarantee you to be able to use all of the TLS termination options that $productName$ exposes including enforcing the minimum TLS version, setting the `alpn_protocols`, and redirecting cleartext to HTTPS. - -If terminating TLS at $productName$, you can provision any AWS load balancer that you want with the following (default) port assignments: - -```yaml -spec: - ports: - - name: http - port: 80 - targetPort: 8080 - - name: https - port: 443 - targetPort: 8443 -``` - -While terminating TLS at $productName$ makes it easier to expose more advanced TLS configuration options, it does have the drawback of not being able to use the ACM to manage certificates. You will have to manage your TLS certificates yourself or use the [automatic certificate management](../host-crd) available in $productName$ to have $productName$ do it for you. - -### TLS termination at the load balancer - -If you choose to terminate TLS at your Amazon load balancer you will be able to use the ACM to manage TLS certificates. This option does add some complexity to your $productName$ configuration, depending on which load balancer you are using. - -Terminating TLS at the load balancer means that $productName$ will be receiving all traffic as un-encrypted cleartext traffic. Since $productName$ expects to be serving both encrypted and cleartext traffic by default, you will need to make the following configuration changes to $productName$ to support this: - -#### L4 load balancer (default ELB or NLB) - -* **Load Balancer Service Configuration:** - The following `Service` will deploy a L4 ELB with TLS termination configured at the load balancer: - ```yaml - apiVersion: v1 - kind: Service - metadata: - name: ambassador - namespace: ambassador - annotations: - service.beta.kubernetes.io/aws-load-balancer-ssl-cert: {{ACM_CERT_ARN}} - service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "443" - spec: - type: LoadBalancer - ports: - - name: HTTP - port: 80 - targetPort: 8080 - - name: HTTPS - port: 443 - targetPort: 8080 - selector: - service: ambassador - ``` - - Note that the `spec.ports` has been changed so both the HTTP and HTTPS ports forward to the cleartext port 8080 on $productName$. - -* **`Host`:** - - The `Host` configures how $productName$ handles encrypted and cleartext traffic. The following `Host` configuration will tell $productName$ to `Route` cleartext traffic that comes in from the load balancer: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Host - metadata: - name: ambassador - spec: - hostname: "*" - selector: - matchLabels: - hostname: wildcard - acmeProvider: - authority: none - requestPolicy: - insecure: - action: Route - ``` - -**Important:** - -Because L4 load balancers do not set `X-Forwarded` headers, $productName$ will not be able to distinguish between traffic that came in to the load balancer as encrypted or cleartext. Because of this, **HTTP -> HTTPS redirection is not possible when terminating TLS at a L4 load balancer**. - -#### L7 load balancer (ELB or ALB) - -* **Load Balancer Service Configuration (L7 ELB):** - - The following `Service` will deploy a L7 ELB with TLS termination configured at the load balancer: - ```yaml - apiVersion: v1 - kind: Service - metadata: - name: ambassador - namespace: ambassador - annotations: - service.beta.kubernetes.io/aws-load-balancer-ssl-cert: {{ACM_CERT_ARN}} - service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "443" - service.beta.kubernetes.io/aws-load-balancer-backend-protocol: "http" - spec: - type: LoadBalancer - ports: - - name: HTTP - port: 80 - targetPort: 8080 - - name: HTTPS - port: 443 - targetPort: 8080 - selector: - service: ambassador - ``` - - Note that the `spec.ports` has been changed so both the HTTP and HTTPS ports forward to the cleartext port 8080 on $productName$. - -* **`Host`:** - - The `Host` configures how $productName$ handles encrypted and cleartext traffic. The following `Host` configuration will tell $productName$ to `Redirect` cleartext traffic that comes in from the load balancer: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Host - metadata: - name: ambassador - spec: - hostname: "*" - selector: - matchLabels: - hostname: wildcard - acmeProvider: - authority: none - requestPolicy: - insecure: - action: Redirect - ``` - -* **Module:** - - Since a L7 load balancer will be able to append to `X-Forwarded` headers, we need to configure $productName$ to trust the value of these headers. The following `Module` will configure $productName$ to trust a single L7 proxy in front of $productName$: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - xff_num_trusted_hops: 1 - use_remote_address: false - ``` - -**Note:** - -$productName$ uses the value of `X-Forwarded-Proto` to know if the request originated as encrypted or cleartext. Unlike L4 load balancers, L7 load balancers will set this header so HTTP -> HTTPS redirection is possible when terminating TLS at a L7 load balancer. - -## Preserving the client IP address - -Many applications will want to know the IP address of the connecting client. In Kubernetes, this IP address is often obscured by the IP address of the `Node` that is forwarding the request to $productName$ so extra configuration must be done if you need to preserve the client IP address. - -In AWS, there are two options for preserving the client IP address. - -1. Use a L7 Load Balancer that sets `X-Forwarded-For` - - A L7 load balancer will populate the `X-Forwarded-For` header with the IP address of the downstream connecting client. If your clients are connecting directly to the load balancer, this will be the IP address of your client. - - When using L7 load balancers, you must configure $productName$ to trust the value of `X-Forwarded-For` and not append its own IP address to it by setting `xff_num_trusted_hops` and `use_remote_address: false` in the [Ambassador `Module`](../ambassador): - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - xff_num_trusted_hops: 1 - use_remote_address: false - ``` - - After configuring the above `Module`, you will need to restart $productName$ for the changes to take effect. - -2. Use the proxy protocol - - The [proxy protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) is a wrapper around an HTTP request that, like `X-Forwarded-For`, lists the IP address of the downstream connecting client but is able to be set by L4 load balancers as well. - - In AWS, you can configure ELBs to use the proxy protocol by setting the `service.beta.kubernetes.io/aws-load-balancer-proxy-protocol: "*"` annotation on the service. You must manually configure this on ALBs and NLBs. - - After configuring the load balancer to use the proxy protocol, you need to tell $productName$ to expect it on the request. - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - use_proxy_proto: true - ``` - - After configuring the above `Module`, you will need to restart $productName$ for the changes to take effect. diff --git a/content/en/docs/3.0/topics/running/ambassador-with-gke.md b/content/en/docs/3.0/topics/running/ambassador-with-gke.md deleted file mode 100644 index 2b90581d..00000000 --- a/content/en/docs/3.0/topics/running/ambassador-with-gke.md +++ /dev/null @@ -1,187 +0,0 @@ -# $productName$ with GKE - -Google offers a [L7 load balancer](https://cloud.google.com/kubernetes-engine/docs/concepts/ingress) to -leverage network services such as managed SSL certificates, SSL offloading or the Google content delivery network. -A L7 load balancer in front of $productName$ can be configured by hand or by using the Ingress-GCE resource. Using the -Ingress resource also allows you to create Google-managed SSL certificates through Kubernetes. - -With this setup, HTTPS will be terminated at the Google load balancer. The load balancer will be created and configured by -the Ingress-GCE resource. The load balancer consists of a set of -[forwarding rules](https://cloud.google.com/load-balancing/docs/forwarding-rule-concepts#https_lb) and a set of -[backend services](https://cloud.google.com/load-balancing/docs/backend-service). -In this setup, the ingress resource creates two forwarding rules, one for HTTP and one for HTTPS. The HTTPS -forwarding rule has the SSL certificates attached. Also, one backend service will be created to point to -a list of instance groups at a static port. This will be the NodePort of the $productName$ service. - -With this setup, the load balancer terminates HTTPS and then directs the traffic to the $productName$ service -via the `NodePort`. $productName$ is then doing all the routing to the other internal/external services. - -# Overview of steps - -1. Install and configure the ingress with the HTTP(S) load balancer -2. Install $productName$ -3. Configure and connect $productName$ to ingress -4. Create an SSL certificate and enable HTTPS -5. Create BackendConfig for health checks -6. Configure $productName$ to do HTTP -> HTTPS redirection - -`ambassador` will be running as a `NodePort` service. Health checks will be configured to go to a BackendConfig resource. - -## 0. $productName$ - -This guide will install $OSSproductName$. You can also install $AESproductName$. Please note: -- The ingress and the `ambassador` service need to run in the same namespace -- The `ambassador` service needs to be of type `NodePort` and not `LoadBalancer`. Also remove the line with `externalTrafficPolicy: Local` -- Ambassador-Admin needs to be of type `NodePort` instead of `ClusterIP` since it needs to be available for health checks - -## 1 . Install and configure ingress with the HTTP(S) load balancer - -Create a GKE cluster through the web console. Use the release channel. When the cluster -is up and running follow [this tutorial from Google](https://cloud.google.com/kubernetes-engine/docs/tutorials/http-balancer) to configure -an ingress and a L7 load balancer. After you have completed these steps you will have a running L7 load balancer -and one service. - -## 2. Install $productName$ - -Follow the first section of the [$OSSproductName$ installation guide](../../install/) to install $OSSproductName$. -Stop before defining the `ambassador` service. - -$productName$ needs to be deployed as `NodePort` instead of `LoadBalancer` to work with the L7 load balancer and the ingress. - -Save the YAML below in ambassador.yaml and apply with `kubectl apply -f ambassador.yaml` - -```yaml -apiVersion: v1 -kind: Service -metadata: - name: ambassador -spec: - type: NodePort - ports: - - port: 8080 - targetPort: 8080 - selector: - service: ambassador -``` - -You will now have an `ambassador` service running next to your ingress. - -## 3. Configure and connect `ambassador` to the ingress - -You need to change the ingress for it to send traffic to `ambassador`. Assuming you have followed the tutorial, you should -have a file named basic-ingress.yaml. Change it to point to `ambassador` instead of web: - -```yaml -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - name: basic-ingress -spec: - backend: - serviceName: ambassador - servicePort: 8080 -``` - -Now let's connect the other service from the tutorial to `ambassador` by specifying a Mapping: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: web - namespace: default -spec: - hostname: "*" - prefix: / - service: web:8080 -``` - -All traffic will now go to `ambassador` and from `ambassador` to the `web` service. You should be able to hit your load balancer and get the output. It may take some time until the load balancer infrastructure has rolled out all changes and you might see gateway errors during that time. -As a side note: right now all traffic will go to the `web` service, including the load balancer health check. - -## 4. Create an SSL certificate and enable HTTPS - -Read up on [managed certificates on GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/managed-certs). You need -a DNS name and point it to the external IP of the load balancer. - -certificate.yaml: -```yaml -apiVersion: networking.gke.io/v1beta1 -kind: ManagedCertificate -metadata: - name: www-example-com -spec: - domains: - - www.example.com -``` - -Modify the ingress from before: -```yaml -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - name: basic-ingress - annotations: - networking.gke.io/managed-certificates: www-example-com -spec: - backend: - serviceName: ambassador - servicePort: 8080 -``` - -Please wait (5-15 minutes) until the certificate is created and all edge servers have the certificates ready. -`kubectl describe ManagedCertificate` will show you the status or go to the web console to view the load balancer. - -You should now be able to access the web service via `https://www.example.com`. - -## 5. Configure BackendConfig for health checks - -Create and apply a BackendConfig resource with a [custom health check](https://cloud.google.com/kubernetes-engine/docs/how-to/ingress-features#direct_health) specified: - -```yaml -apiVersion: cloud.google.com/v1 -kind: BackendConfig -metadata: - name: ambassador-hc-config - namespace: ambassador -spec: - # https://cloud.google.com/kubernetes-engine/docs/how-to/ingress-features - timeoutSec: 30 - connectionDraining: - drainingTimeoutSec: 30 - logging: - enable: true - sampleRate: 1.0 - healthCheck: - checkIntervalSec: 10 - timeoutSec: 10 - port: 8877 - type: HTTP - requestPath: /ambassador/v0/check_alive -``` - -Then edit your previous `ambassador.yaml` file to add an annotation referencing the BackendConfig and apply the file: - -``` -apiVersion: v1 -kind: Service -metadata: - name: ambassador - annotations: - cloud.google.com/backend-config: '{"default": "ambassador-hc-config"}' -spec: - type: NodePort - ports: - - port: 8080 - targetPort: 8080 - selector: - service: ambassador -``` - -## 6. Configure $productName$ to do HTTP -> HTTPS redirection - -Configure $productName$ to [redirect traffic from HTTP to HTTPS](../tls/cleartext-redirection/#http-https-redirection). You will need to restart $productName$ to effect the changes with `kubectl rollout restart deployment ambassador`. - -The result should be that `http://www.example.com` will redirect to `https://www.example.com`. - -You can now add more services by specifying the hostname in the Mapping. diff --git a/content/en/docs/3.0/topics/running/ambassador.md b/content/en/docs/3.0/topics/running/ambassador.md deleted file mode 100644 index 3af41d93..00000000 --- a/content/en/docs/3.0/topics/running/ambassador.md +++ /dev/null @@ -1,558 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# The `Ambassador` `Module` Resource - -
-

Contents

- -* [Envoy](#envoy) -* [General](#general) -* [gRPC](#grpc) -* [Header behavior](#header-behavior) -* [Observability](#observability) -* [Protocols](#protocols) -* [Security](#security) -* [Service health / timeouts](#service-health--timeouts) -* [Traffic management](#traffic-management) - - -
- -If present, the `ambassador` `Module` defines system-wide configuration for $productName$. You won't need it unless you need to change one of the system-wide configuration settings below. - -To use the `ambassador` `Module` to configure $productName$, it MUST be named `ambassador`, otherwise it will be ignored. To create multiple `ambassador` `Module`s in the same Kubernetes namespace, you will need to apply them as annotations with separate `ambassador_id`s: you will not be able to use multiple CRDs. - -There are many items that can be configured on the `ambassador` `Module`. They are listed below with examples and grouped by category. - -## Envoy - -##### Content-Length headers - -* `allow_chunked_length: true` tells Envoy to allow requests or responses with both `Content-Length` and `Transfer-Encoding` headers set. The default is `false`. - -By default, messages with both `Content-Length` and `Content-Transfer-Encoding` are rejected. If `allow_chunked_length` is `true`, $productName$ will remove the `Content-Length` header and process the message. See the [Envoy documentation for more details](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto.html?highlight=allow_chunked_length#config-core-v3-http1protocoloptions). - -##### Envoy access logs - -* `envoy_log_path` defines the path of Envoy's access log. By default this is standard output. -* `envoy_log_type` defines the type of access log Envoy will use. Currently, only `json` or `text` are supported. -* `envoy_log_format` defines the Envoy access log line format. - -These logs can be formatted using [Envoy operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) to display specific information about an incoming request. The example below will show only the protocol and duration of a request: - -```yaml -envoy_log_path: /dev/fd/1 -envoy_log_type: json -envoy_log_format: - { - "protocol": "%PROTOCOL%", - "duration": "%DURATION%" - } -``` - -See the Envoy documentation for the [standard log format](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#default-format-string) and a [complete list of log format operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/access_log). - -##### Envoy validation timeout - -* `envoy_validation_timeout` defines the timeout, in seconds, for validating a new Envoy configuration. The default is 10. - -A value of 0 disables Envoy configuration validation. Most installations will not need to change this setting. - -For example: - -```yaml -envoy_validation_timeout: 30 -``` - -would allow 30 seconds to validate the generated Envoy configuration. - -##### Error response overrides - -* `error_response_overrides` permits changing the status code and body text for 4XX and 5XX response codes. The default is not to override any error responses. - -By default, $productName$ will pass through error responses without modification, and errors generated locally will use Envoy's default response body, if any. - -See [using error response overrides](../custom-error-responses) for usage details. For example, this configuration: - -```yaml -error_response_overrides: - - on_status_code: 404 - body: - text_format: "File not found" -``` - -would explicitly modify the body of 404s to say "File not found". - -##### Forwarding client cert details - -Two attributes allow providing information about the client's TLS certificate to upstream certificates: - -* `forward_client_cert_details: true` will tell Envoy to add the `X-Forwarded-Client-Cert` to upstream - requests. The default is `false`. -* `set_current_client_cert_details` will tell Envoy what information to include in the - `X-Forwarded-Client-Cert` header. The default is not to include the `X-Forwarded-Client-Cert` header at all. - -$productName$ will not forward information about a certificate that it cannot validate. - -See the Envoy documentation on [X-Forwarded-Client-Cert](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers.html?highlight=xfcc#x-forwarded-client-cert) and [SetCurrentClientCertDetails](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto.html#extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-setcurrentclientcertdetails) for more information. - -```yaml -forward_client_cert_details: true -set_current_client_cert_details: SANITIZE -``` - -##### Server name - -* `server_name` allows overriding the server name that Envoy sends with responses to clients. The default is `envoy`. - -##### Suppress Envoy headers - -* `suppress_envoy_headers: true` will prevent $productName$ from emitting certain additional - headers to HTTP requests and responses. The default is `false`. - -For the exact set of headers covered by this config, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter#config-http-filters-router-headers-set) - ---- -## General - -##### Ambassador ID - -* `ambassador_id` allows using multiple instances of $productName$ in the same cluster. The default is unset. - -We recommend _not_ setting `ambassador_id` if you are running only one instance of $productName$ in your cluster. For more information, see the [Running and Deployment documentation](../running/#ambassador_id). - -If used, the `ambassador_id` value must be an array, for example: - -```yaml -ambassador_id: [ "test_environment" ] -``` - -##### Defaults - -* `defaults` provides a dictionary of default values that will be applied to various $productName$ resources. The default is to have no defaults configured. - -See [Using `ambassador` `Module` Defaults](../../using/defaults) for more information. - ---- - -## gRPC - -##### Bridges - -* `enable_grpc_http11_bridge: true` will enable the gRPC-HTTP/1.1 bridge. The default is `false`. -* `enable_grpc_web: true` will enable the gRPC-Web bridge. The default is `false`. - -gRPC is a binary HTTP/2-based protocol. While this allows high performance, it can be problematic for clients that are unable to speak HTTP/2 (such as JavaScript in many browsers, or legacy clients in difficult-to-update environments). - -The gRPC-HTTP/1.1 bridge can translate HTTP/1.1 calls with `Content-Type: application/grpc` into gRPC calls: $productName$ will perform buffering and translation as necessary. For more details on the translation process, see the [Envoy gRPC HTTP/1.1 bridge documentation](https://www.envoyproxy.io/docs/envoy/v1.11.2/configuration/http_filters/grpc_http1_bridge_filter.html). - -Likewise, gRPC-Web is a JSON and HTTP-based protocol that allows browser-based clients to take advantage of gRPC protocols. The gRPC-Web specification requires a server-side proxy to translate between gRPC-Web requests and gRPC backend services, and $productName$ can fill this role when the gRPC-Web bridge is enabled. For more details on the translation process, see the [Envoy gRPC HTTP/1.1 bridge documentation](https://www.envoyproxy.io/docs/envoy/v1.11.2/configuration/http_filters/grpc_http1_bridge_filter.html); for more details on gRPC-Web itself, see the [gRPC-Web client GitHub repo](https://github.com/grpc/grpc-web). - -##### Statistics - -* `grpc_stats` allows enabling telemetry for gRPC calls using Envoy's [gRPC Statistics Filter](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/grpc_stats_filter). The default is disabled. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - grpc_stats: - upstream_stats: true - services: - - name: . - method_names: [] -``` - -Supported parameters: -* `all_methods` -* `services` -* `upstream_stats` - -Available metrics: -* `envoy_cluster_grpc__` -* `envoy_cluster_grpc__request_message_count` -* `envoy_cluster_grpc__response_message_count` -* `envoy_cluster_grpc__success` -* `envoy_cluster_grpc__total` -* `envoy_cluster_grpc_upstream_` - **only when `upstream_stats: true`** - -Please note that `` will only be present if `all_methods` is set or the service and the method are present under `services`. If `all_methods` is false or the method is not on the list, the available metrics will be in the format `envoy_cluster_grpc_`. - -* `all_methods`: If set to true, emit stats for all service/method names. -If set to false, emit stats for all service/message types to the same stats without including the service/method in the name. -**This option is only safe if all clients are trusted. If this option is enabled with untrusted clients, the clients could cause unbounded growth in the number -of stats in Envoy, using unbounded memory and potentially slowing down stats pipelines.** - -* `services`: If set, specifies an allow list of service/methods that will have individual stats emitted for them. Any call that does not match the allow list will be counted in a stat with no method specifier (generic metric). - - - If both all_methods and services are present, all_methods will be ignored. - - -* `upstream_stats`: If true, the filter will gather a histogram for the request time of the upstream. - ---- - -## Header behavior - -##### Header case - -* `proper_case: true` forces headers to have their "proper" case as shown in RFC7230. The default is `false`. -* `header_case_overrides` allows forcing certain headers to have specific casing. The default is to override no headers. - -proper_case and header_case_overrides are mutually exclusive. - -RFC7230 specifies that HTTP header names are case-insensitive, but always shows and refers to headers as starting with a capital letter, continuing in lowercase, then repeating the single capital letter after each non-alpha character. This has become an established convention when working with HTTP: - -- `Host`, not `host` or `HOST` -- `Content-Type`, not `content-type`, `Content-type`, or `cOnTeNt-TyPe` - -Internally, Envoy typically uses [all lowercase](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/header_casing) for header names. This is fully compliant with RFC7230, but some services and clients may require headers to follow the stricter casing rules implied by RFC7230 section headers: in that situation, setting `proper_case: true` will tell Envoy to force all headers to use the casing above. - -Alternately, it is also possible - although less common - for services or clients to require some other specific casing for specific headers. `header_case_overrides` specifies an array of header names: if a case-insensitive match for a header is found in the list, the matching header will be replaced with the one in the list. For example, the following configuration will force headers that match `X-MY-Header` and `X-EXPERIMENTAL` to use that exact casing, regardless of the original case used in flight: - -```yaml -header_case_overrides: -- X-MY-Header -- X-EXPERIMENTAL -``` - -If the upstream service responds with `x-my-header: 1`, $productName$ will return `X-MY-Header: 1` to the client. Similarly, if the client includes `x-ExperiMENTAL: yes` in its request, the request to the upstream service will include `X-EXPERIMENTAL: yes`. Other headers will not be altered; $productName$ will use its default lowercase header. - -Please see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto.html#config-core-v3-http1protocoloptions-headerkeyformat) for more information. Note that in general, we recommend updating clients and services rather than relying on `header_case_overrides`. - -##### Linkerd interoperability - -* `add_linkerd_headers: true` will force $productName$ to include the `l5d-dst-override` header for Linkerd. The default is `false`. - -When using older Linkerd installations, requests going to an upstream service may need to include the `l5d-dst-override` header to ensure that Linkerd will route them correctly. Setting `add_linkerd_headers` does this automatically. See the [Mapping](../../using/mappings#linkerd-interoperability-add_linkerd_headers) documentation for more details. - -##### Max request headers size - -* `max_request_headers_kb` sets the maximum allowed request header size in kilobytes. If not set, the default is 60 KB. - -See [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto.html) for more information. - -##### Preserve external request ID - -* `preserve_external_request_id: true` will preserve any `X-Request-Id` header presented by the client. The default is `false`, in which case Envoy will always generate a new `X-Request-Id` value. - -##### Strip matching host port - -* `strip_matching_host_port: true` will tell $productName$ to strip any port number from the host/authority header before processing and routing the request if that port number matches the port number of Envoy's listener. The default is `false`, which will preserve any port number. - -In the default installation of $productName$ the public port is 443, which then maps internally to 8443, so this only works in custom installations where the public Service port and Envoy listener port match. - -A common reason to try using this property is if you are using gRPC with TLS and your client library appends the port to the Host header (i.e. `myurl.com:443`). We have an alternative solution in our [gRPC guide](../../../howtos/grpc#working-with-host-headers-that-include-the-port) that uses a [Lua script](#lua-scripts) to remove all ports from every Host header for that use case. - ---- - -## Miscellaneous - - -##### Envoy's admin port - -* `admin_port` specifies the port where $productName$'s Envoy will listen for low-level admin requests. The default is 8001; it should almost never need changing. - -##### Lua scripts - -* `lua_scripts` allows defining a custom Lua script to run on every request. The default is to run no script. - -This is useful for simple use cases that mutate requests or responses, for example to add a custom header: - -```yaml -lua_scripts: | - function envoy_on_response(response_handle) - response_handle:headers():add("Lua-Scripts-Enabled", "Processed") - end -``` - -For more details on the Lua API, see the [Envoy Lua filter documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/lua_filter.html). - -Some caveats around the embedded scripts: - -* They run in-process, so any bugs in your Lua script can break every request. -* They're run on every request/response to every URL. -* They're inlined in the $productName$ YAML; as such, we do not recommend using Lua scripts for long, complex logic. - -If you need more flexible and configurable options, $AESproductName$ supports a [pluggable Filter system](/docs/edge-stack/latest/topics/using/filters/). - -##### Merge slashes - -* `merge_slashes: true` will cause $productName$ to merge adjacent slashes in incoming paths when doing route matching and request filtering. The default is `false`. - -For example, with `merge_slashes: true`, a request for `//foo///bar` would be matched to a `Mapping` with prefix `/foo/bar`. - -##### Modify Default Buffer Size - -By default, the Envoy that ships with $productName$ uses a defailt of 1MiB soft limit for an upstream service's read and write buffer limits. This setting allows you to configure that buffer limit. See the [Envoy docs](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto.html?highlight=per_connection_buffer_limit_bytes) for more information. - -```yaml -buffer_limit_bytes: 5242880 # Sets the default buffer limit to 5 MiB -``` - -##### Use $productName$ namespace for service resolution - -* `use_ambassador_namespace_for_service_resolution: true` tells $productName$ to assume that unqualified services are in the same namespace as $productName$. The default is `false`. - -By default, when $productName$ sees a service name without a namespace, it assumes that the namespace is the same as the resource referring to the service. For example, for this `Mapping`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-1 - namespace: foo -spec: - hostname: "*" - prefix: / - service: upstream -``` - -$productName$ would look for a Service named `upstream` in namespace `foo`. - -However, if `use_ambassador_namespace_for_service_resolution` is `true`, this `Mapping` would look for a Service named `foo` in the namespace in which $productName$ is installed instead. - ---- - -## Observability - -##### Diagnostics - -* `diagnostics` controls access to the diagnostics interface. - -By default, $productName$ creates a `Mapping` that allows access to the diagnostic interface at `/ambassador/v0/diag` from anywhere in the cluster. To disable the `Mapping` entirely, set `diagnostics.enabled` to `false`: - - -```yaml -diagnostics: - enabled: false -``` - -With diagnostics disabled, `/ambassador/v0/diag` will respond with 404; however, the service itself is still running, and `/ambassador/v0/diag/` is reachable from inside the $productName$ Pod at `https://localhost:8877`. You can use Kubernetes port forwarding to set up remote access to the diagnostics page temporarily: - -``` -kubectl port-forward -n ambassador deploy/ambassador 8877 -``` - -Alternately, to leave the `Mapping` intact but restrict access to only the local Pod, set `diagnostics.allow_non_local` to `false`: - -```yaml -diagnostics: - allow_non_local: true -``` - -See [Protecting Access to the Diagnostics Interface](../../../howtos/protecting-diag-access) for more information. - ---- -## Protocols - -##### Enable IPv4 and IPv6 - -* `enable_ipv4` determines whether IPv4 DNS lookups are enabled. The default is `true`. -* `enable_ipv6` determines whether IPv6 DNS lookups are enabled. The default is `false`. - -If both IPv4 and IPv6 are enabled, $productName$ will prefer IPv6. This can have strange effects if $productName$ receives `AAAA` records from a DNS lookup, but the underlying network of the pod doesn't actually support IPv6 traffic. For this reason, the default is IPv4 only. - -An [`Mapping`](../../using/mappings) can override both `enable_ipv4` and `enable_ipv6`, but if either is not stated explicitly in a `Mapping`, the values here are used. Most $productName$ installations will probably be able to avoid overriding these settings in Mappings. - -##### HTTP/1.0 support - -* `enable_http10: true` will enable handling incoming HTTP/1.0 and HTTP/0.9 requests. The default is `false`. - ---- -## Security - -##### Cross origin resource sharing (CORS) - -* `cors` sets the default CORS configuration for all mappings in the cluster. The default is that CORS is not configured. - -For example: - -```yaml -cors: - origins: http://foo.example,http://bar.example - methods: POST, GET, OPTIONS - ... -``` - -See the [CORS syntax](../../using/cors) for more information. - -##### IP allow and deny - -* `ip_allow` and `ip_deny` define HTTP source IP address ranges to allow or deny. The default is to allow all traffic. - -Only one of ip_allow and ip_deny may be specified. - -If `ip_allow` is specified, any traffic not matching a range to allow will be denied. If `ip_deny` is specified, any traffic not matching a range to deny will be allowed. A list of ranges to allow and a separate list to deny may not both be specified. - -Both take a list of IP address ranges with a keyword specifying how to interpret the address, for example: - -```yaml -ip_allow: -- peer: 127.0.0.1 -- remote: 99.99.0.0/16 -``` - -The keyword `peer` specifies that the match should happen using the IP address of the other end of the network connection carrying the request: `X-Forwarded-For` and the `PROXY` protocol are both ignored. Here, our example specifies that connections originating from the $productName$ pod itself should always be allowed. - -The keyword `remote` specifies that the match should happen using the IP address of the HTTP client, taking into account `X-Forwarded-For` and the `PROXY` protocol if they are allowed (if they are not allowed, or not present, the peer address will be used instead). This permits matches to behave correctly when, for example, $productName$ is behind a layer 7 load balancer. Here, our example specifies that HTTP clients from the IP address range `99.99.0.0` - `99.99.255.255` will be allowed. - -You may specify as many ranges for each kind of keyword as desired. - -##### Rejecting Client Requests With Escaped Slashes - -* `reject_requests_with_escaped_slashes: true` will tell $productName$ to reject requests containing escaped slashes. The default is `false`. - -When set to `true`, $productName$ will reject any client requests that contain escaped slashes (`%2F`, `%2f`, `%5C`, or `%5c`) in their URI path by returning HTTP 400. By default, $productName$ will forward these requests unmodified. - -In general, a request with an escaped slash will _not_ match a `Mapping` prefix with an unescaped slash. However, external authentication services and other upstream services may handle escaped slashes differently, which can lead to security issues if paths with escaped slashes are allowed. By setting `reject_requests_with_escaped_slashes: true`, this class of security concern can be largely avoided. - -##### Trust downstream client IP - -* `use_remote_address: false` tells $productName$ that it cannot trust the remote address of incoming connections, and must instead rely exclusively on the `X-Forwarded-For` header. The default is `true`. - -When `true` (the default), $productName$ will append its own IP address to the `X-Forwarded-For` header so that upstream services of $productName$ can get the full set of IP addresses that have propagated a request. You may also need to set `externalTrafficPolicy: Local` on your `LoadBalancer` to propagate the original source IP address. - -See the [Envoy documentation on the `X-Forwarded-For header` ](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers) and the [Kubernetes documentation on preserving the client source IP](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/#preserving-the-client-source-ip) for more details. - -##### `X-Forwarded-For` trusted hops - -* `xff_num_trusted_hops` sets the default value for [the `l7Depth` setting of a `Listener`](../listener/#securitymodel). The default is 0. - -See the [`Listener` documentation](../listener/#securitymodel) for more details. - ---- - -## Service health / timeouts - -##### Incoming connection idle timeout - -* `listener_idle_timeout_ms` sets the idle timeout for incoming connections. The default is no timeout, meaning that incoming connections may remain idle forever. - -If set, this specifies the length of time (in milliseconds) that an incoming connection is allowed to be idle before being dropped. This can useful if you have proxies and/or firewalls in front of $productName$ and need to control how $productName$ initiates closing an idle TCP connection. - -Please see the [Envoy documentation on HTTP protocol options](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#config-core-v3-httpprotocoloptions) for more information. - -##### Keepalive - -* `keepalive` sets the global TCP keepalive settings. - -$productName$ will use these settings for all `AmbasasdorMapping`s unless overridden in a `Mapping`'s configuration. Without `keepalive`, $productName$ follows the operating system defaults. - -For example, the following configuration: - -```yaml -keepalive: - time: 2 - interval: 2 - probes: 100 -``` - -would enable keepalives every two seconds (`interval`), starting after two seconds of idleness (`time`), with the connection being dropped if 100 keepalives are sent with no response (`probes`). For more information, see the [Envoy keepalive documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/address.proto.html#config-core-v3-tcpkeepalive). - -##### Upstream idle timeout - -* `cluster_idle_timeout_ms` sets the default idle timeout for upstream connections (by default, one hour). - -If set, this specifies the timeout (in milliseconds) after which an idle connection upstream is closed. The idle timeout can be completely disabled by setting `cluster_idle_timeout_ms: 0`, which risks idle upstream connections never getting closed. - -If not set, the default idle timeout is one hour. - -You can override this setting with [`idle_timeout_ms` on a `Mapping`](../../using/timeouts/). - -##### Upstream max lifetime - -* `cluster_max_connection_lifetime_ms` sets the default maximum lifetime of an upstream connection. - -If set, this specifies the maximum amount of time (in milliseconds) after which an upstream connection is drained and closed, regardless of whether it is idle or not. Connection recreation incurs additional overhead when processing requests. The overhead tends to be nominal for plaintext (HTTP) connections within the same cluster, but may be more significant for secure HTTPS connections or upstreams with high latency. For this reason, it is generally recommended to set this value to at least 10000 ms to minimize the amortized cost of connection recreation while providing a reasonable bound for connection lifetime. - -If not set (or set to zero), then upstream connections may remain open for arbitrarily long. - -You can override this setting with [`cluster_max_connection_lifetime_ms` on a `Mapping`](../../using/timeouts/). - -##### Request timeout - -* `cluster_request_timeout_ms` sets the default end-to-end timeout for a single request. - -If set, this specifies the default end-to-end timeout for every request. - -If not set, the default is three seconds. - -You can override this setting with [`timeout_ms` on a `Mapping`](../../using/timeouts/). - -##### Readiness and liveness probes - -* `readiness_probe` sets whether `/ambassador/v0/check_ready` is automatically mapped -* `liveness_probe` sets whether `/ambassador/v0/check_alive` is automatically mapped - -By default, $productName$ creates `Mapping`s that support readiness and liveness checks at `/ambassador/v0/check_ready` and `/ambassador/v0/check_alive`. To disable the readiness `Mapping` entirely, set `readiness_probe.enabled` to `false`: - - -```yaml -readiness_probe: - enabled: false -``` - -Likewise, to disable the liveness `Mapping` entirely, set `liveness_probe.enabled` to `false`: - - -```yaml -liveness_probe: - enabled: false -``` - -A disabled probe endpoint will respond with 404; however, the service is still running, and will be accessible on localhost port 8877 from inside the $productName$ Pod. - -You can change these to route requests to some other service. For example, to have the readiness probe map to the `quote` application's health check: - -```yaml -readiness_probe: - enabled: true - service: quote - rewrite: /backend/health -``` - -The liveness and readiness probes both support `prefix` and `rewrite`, with the same meanings as for [Mappings](../../using/mappings). - -##### Retry policy - -This lets you add resilience to your services in case of request failures by performing automatic retries. - -```yaml -retry_policy: - retry_on: "5xx" -``` - ---- - -## Traffic management - -##### Circuit breaking - -* `circuit_breakers` sets the global circuit breaking configuration defaults - -You can override the circuit breaker settings for individual `Mapping`s. By default, $productName$ does not configure any circuit breakers. For more information, see the [circuit breaking reference](../../using/circuit-breakers). - -##### Default label domain and labels - -* `default_labels` sets default domains and labels to apply to every request. - -For more on how to use the default labels, , see the [Rate Limit reference](../../using/rate-limits/#attaching-labels-to-requests). - -##### Default load balancer - -* `load_balancer` sets the default load balancing type and policy - -For example, to set the default load balancer to `least_request`: - -```yaml -load_balancer: - policy: least_request -``` - -If not set, the default is to use round-robin load balancing. For more information, see the [load balancer reference](../load-balancer). diff --git a/content/en/docs/3.0/topics/running/custom-error-responses.md b/content/en/docs/3.0/topics/running/custom-error-responses.md deleted file mode 100644 index b0ad9877..00000000 --- a/content/en/docs/3.0/topics/running/custom-error-responses.md +++ /dev/null @@ -1,217 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Custom error responses - -Custom error responses set overrides for HTTP response statuses generated either -by $productName$ or upstream services. - -They can be configured either on the $productName$ -[`Module`](../ambassador) -or on an [`Mapping`](../../using/intro-mappings/), the schema is identical. See -below for more information on [rule precedence](#rule-precedence). - -- `on_status_code`: HTTP status code to match for this rewrite - rule. Only 4xx and 5xx classes are supported. -- `body`: Describes the response body contents and format. - + `content_type`: A string that sets the content type of the - response. - + `text_format`: A string whose value will be used as the new - response body. `Content-Type` will default to `text/plain` if - unspecified. - + `json_format`: A config object whose keys and values will be - serialized as JSON and used as the new response body. - + `text_format_source`: Describes a file to be used as the - response. If used, `filename` must be set and the file must exist - on the $productName$ pod. - * `filename`: A file path on the $productName$ pod that will be used - as the new response body. - -Only one of `text_format`, `json_format`, or `text_format_source` may be provided. - -Custom response bodies are subject to Envoy's AccessLog substitution syntax -and variables, see [Envoy's documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#config-access-log-format-strings) for more information. - -Note that the AccessLog substitutions use `%` as a delimiter (for example, -`%RESPONSE_CODE%`). To include a literal `%` in a custom response body, use `%%`. -For example, - -``` -%%RESPONSE_CODE%% %RESPONSE_CODE% -``` - -would render as - -``` -%RESPONSE_CODE% 401 -``` - -for a request that resulted in a response code of 401. - - - If the % 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. - - -## Simple response bodies - -Simple responses can be be added quickly for convenience. They are inserted into -the manifest as either text or JSON: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador - namespace: ambassador -spec: - config: - error_response_overrides: - - on_status_code: 404 - body: - text_format: "File not found" - - on_status_code: 500 - body: - json_format: - error: "Application error" - status: "%RESPONSE_CODE%" - cluster: "%UPSTREAM_CLUSTER%" -``` -## File response bodies - -For more complex response bodies a file can be returned as the response. -This could be used for a customer friendly HTML document for example. Use -`text_format_source` with a `filename` set as a path on the $productName$ pod. -`content_type` should be used set the specific file type, such as `text/html`. - -First configure the $productName$ module: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador - namespace: ambassador -spec: - config: - error_response_overrides: - - on_status_code: 404 - body: - content_type: "text/html" - text_format_source: - filename: '/ambassador/ambassador-errorpages/404.html' -``` - -Then create the config map containing the HTML file: - -```yaml ---- -apiVersion: v1 -kind: ConfigMap -metadata: - name: ambassador-errorpages - namespace: ambassador -data: - 404.html: | - -

File not found

-

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/content/en/docs/3.0/topics/running/debugging.md b/content/en/docs/3.0/topics/running/debugging.md deleted file mode 100644 index bd376483..00000000 --- a/content/en/docs/3.0/topics/running/debugging.md +++ /dev/null @@ -1,192 +0,0 @@ -# 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. - - - Enabling debug-level logging can produce a lot of log output — enough to - potentially impact the performance of $productName$. We don't recommend running with debug - logging enabled as a matter of course; it's usually better to enable it only when needed, - then reset logging to normal once you're finished debugging. - - -### $productName$ debug logging - -Much of $productName$'s logging is concerned with the business of noticing changes to -Kubernetes resources that specify the $productName$ configuration, and generating new -Envoy configuration in response to those changes. Enabling debug logging for this part -of the system is under the control of two environment variables: - -- Set `AES_LOG_LEVEL=debug` to debug the early boot sequence and $productName$'s interactions - with the Kubernetes cluster (finding changed resources, etc.). -- Set `AMBASSADOR_DEBUG=diagd` to debug the process of generating an Envoy configuration from - the input resources. - -### $productName$ Envoy logging - -Envoy logging is concerned with the actions Envoy is taking for incoming requests. -Typically, Envoy will only output access logs, and certain errors, but enabling Envoy -debug logging will show very verbose information about the actions Envoy is actually -taking. It can be useful for understanding why connections are being closed, or whether -an error status is coming from Envoy or from the upstream service. - -It is possible to enable Envoy logging at boot, but for the most part, it's safer to -enable it at runtime, right before sending a request that is known to have problems. -To enable Envoy debug logging, use `kubectl exec` to get a shell on the $productName$ -pod, then: - - ``` - curl -XPOST http://localhost:8001/logging?level=trace && \ - sleep 10 && \ - curl -XPOST http://localhost:8001/logging?level=warning - ``` - -This will turn on Envoy debug logging for ten seconds, then turn it off again. - -### Viewing logs - -To view the logs from $productName$: - -1. Use the following command to target an individual $productName$ Pod: `kubectl get pods -n $productNamespace$` - - The terminal will print something similar to the following: - - ``` - $ kubectl get pods -n $productNamespace$ - NAME READY STATUS RESTARTS AGE - $productDeploymentName$-85c4cf67b-4pfj2 1/1 Running 0 3m - ``` - -2. Then, run the following: `kubectl logs -n $productNamespace$ <$productDeploymentName$-pod-name>` - -The terminal will print something similar to the following: - - ``` - $ kubectl logs -n $productNamespace$ $productDeploymentName$-85c4cf67b-4pfj2 - 2018-10-10 12:26:50 kubewatch 0.40.0 INFO: generating config with gencount 1 (0 changes) - /usr/lib/python3.6/site-packages/pkg_resources/__init__.py:1235: UserWarning: /ambassador is writable by group/others and vulnerable to attack when used with get_resource_filename. Consider a more secure location (set with .set_extraction_path or the PYTHON_EGG_CACHE environment variable). - warnings.warn(msg, UserWarning) - 2018-10-10 12:26:51 kubewatch 0.40.0 INFO: Scout reports {"latest_version": "0.40.0", "application": "ambassador", "notices": [], "cached": false, "timestamp": 1539606411.061929} - - 2018-10-10 12:26:54 diagd 0.40.0 [P15TMainThread] INFO: thread count 3, listening on 0.0.0.0:8877 - [2018-10-10 12:26:54 +0000] [15] [INFO] Starting gunicorn 19.8.1 - [2018-10-10 12:26:54 +0000] [15] [INFO] Listening at: http://0.0.0.0:8877 (15) - [2018-10-10 12:26:54 +0000] [15] [INFO] Using worker: threads - [2018-10-10 12:26:54 +0000] [42] [INFO] Booting worker with pid: 42 - 2018-10-10 12:26:54 diagd 0.40.0 [P42TMainThread] INFO: Starting periodic updates - [2018-10-10 12:27:01.977][21][info][main] source/server/drain_manager_impl.cc:63] shutting down parent after drain - ``` - -Note that many deployments will have multiple logs, and the logs are independent for each Pod. - -## Examine Pod and container contents - -You can examine the contents of the $productName$ Pod for issues, such as if volume mounts are correct and TLS certificates are present in the required directory, to determine if the Pod has the latest $productName$ configuration, or if the generated Envoy configuration is correct or as expected. In these instructions, we will look for problems related to the Envoy configuration. - -1. To look into an $productName$ Pod, get a shell on the Pod using `kubectl exec`. For example, - - ``` - kubectl exec -it -n $productNamespace$ <$productDeploymentName$-pod-name> -- bash - ``` - -2. Determine the latest configuration. If you haven't overridden the configuration directory, the latest configuration will be in `/ambassador/snapshots`. If you have overridden it, $productName$ saves configurations in `$AMBASSADOR_CONFIG_BASE_DIR/snapshots`. - - In the snapshots directory: - - * `snapshot.yaml` contains the full input configuration that $productName$ has found; - * `aconf.json` contains the $productName$ configuration extracted from the snapshot; - * `ir.json` contains the IR constructed from the $productName$ configuration; and - * `econf.json` contains the Envoy configuration generated from the IR. - - In the snapshots directory, the current configuration will be stored in files with no digit suffix, and older configurations have increasing numbers. For example, `ir.json` is current, `ir-1.json` is the next oldest, then `ir-2.json`, etc. - -3. If something is wrong with `snapshot` or `aconf`, there is an issue with your configuration. If something is wrong with `ir` or `econf`, you should [open an issue on Github](https://github.com/emissary-ingress/emissary/issues/new/choose). - -4. The actual input provided to Envoy is split into `$AMBASSADOR_CONFIG_BASE_DIR/bootstrap-ads.json` and `$AMBASSADOR_CONFIG_BASE_DIR/envoy/envoy.json`. - - - The `bootstrap-ads.json` file contains details about Envoy statistics, logging, authentication, etc. - - The `envoy.json` file contains information about request routing. - - You may generally find it simplest to just look at the `econf.json` files in the `snapshot` - directory, which includes both kinds of configuration. diff --git a/content/en/docs/3.0/topics/running/diagnostics.md b/content/en/docs/3.0/topics/running/diagnostics.md deleted file mode 100644 index a0a5f712..00000000 --- a/content/en/docs/3.0/topics/running/diagnostics.md +++ /dev/null @@ -1,42 +0,0 @@ -# Diagnostics - -If you're experiencing issues with $productName$, log in to your Edge Policy Console and choose from the left menu whether you want to: - -* Debug issues from the Debugging tab -* Check the health status of your services from the Mappings tab - -## Debugging - -If $productName$ is not routing your services as you'd expect, your first step should be $productName$ Diagnostics in the Edge Policy Console. Login to your Edge Policy Console and select the "Debugging" tab from the left menu. - -Some of the most important information (your $productName$ version, how recently $productName$'s configuration was updated, and how recently Envoy last reported status to $productName$) is right at the top. See [Debugging](../debugging) for more information. - -## Health status - -$productName$ displays the health of your services on the Dashboard of your Edge Policy Console. Health is computed as successful requests / total requests and expressed as a percentage. The "total requests" comes from Envoy `upstream_rq_pending_total` stat. "Successful requests" is calculated by substracting `upstream_rq_4xx` and `upstream_rq_5xx` from the total. - -* Red is used when the success rate ranges from 0% - 70%. -* Yellow is used when the success rate ranges from 70% - 90%. -* Green is used when the success rate is > 90%. -* Grey is used when a service is "waiting". This means the success rate cannot be determined because the service has not recieved any requests yet. - - Health status - - -The LEFT image shows what a list of services under the `Debugging tab` in the Edge Policy Consul will look like for each level of health. - -The RIGHT image shows the dial on the hompage of the Edge Policy Console, this will display the ratio of services that are healthy according to these measurements. - - -## Troubleshooting - -If the diagnostics service does not provide sufficient information, Kubernetes and Envoy provide additional debugging information. - -If $productName$ isn't working at all, start by looking at the data from the following: - -* `kubectl describe pod ` will give you a list of all events on the $productName$ pod -* `kubectl logs ambassador` will give you a log from $productName$ itself - -If you need additional help, feel free to join our [Slack channel](http://a8r.io/slack) with the above information (along with your Kubernetes manifest). - -You can also increase the debug of Envoy through the button in the diagnostics panel. Turn on debug logging, issue a request, and capture the log output from the $productName$ pod using `kubectl logs` as described above. diff --git a/content/en/docs/3.0/topics/running/environment.md b/content/en/docs/3.0/topics/running/environment.md deleted file mode 100644 index 879c0425..00000000 --- a/content/en/docs/3.0/topics/running/environment.md +++ /dev/null @@ -1,63 +0,0 @@ -# The $productName$ container - -To give you flexibility and independence from a hosting platform's uptime, you can pull the `ambassador` and `aes` images from any of the following registries: -- `docker.io/datawire/` - * **Note**: In rare occasions, you may experience rate limits when using Docker Hub. See [this page](https://www.docker.com/increase-rate-limits) to learn how to deal with them. -- `quay.io/datawire/` -- `gcr.io/datawire/` - -For an even more robust installation, consider using a [local registry as a pull through cache](https://docs.docker.com/registry/recipes/mirror/) or configure a [publicly accessible mirror](https://cloud.google.com/container-registry/docs/using-dockerhub-mirroring). - -## Environment variables - -Use the following variables for the environment of your $productName$ container: - -| Purpose | Variable | Default value | Value type | -|-----------------------------------|----------------------------------------------------------------------------------------- |-----------------------------------------------------|-------------------------------------------------------------------------------| -| Core | `AMBASSADOR_ID` | `[ "default" ]` | List of strings | -| Core | `AMBASSADOR_NAMESPACE` | `default` ([^1]) | Kubernetes namespace | -| Core | `AMBASSADOR_SINGLE_NAMESPACE` | Empty | Boolean; non-empty=true, empty=false | -| Core | `AMBASSADOR_ENVOY_BASE_ID` | `0` | Integer | -| Core | `AMBASSADOR_LEGACY_MODE` | `false` | Boolean; [Go `strconv.ParseBool`][] | -| Core | `AMBASSADOR_FAST_RECONFIGURE` | `false` | EXPERIMENTAL -- Boolean; `true`=true, any other value=false | -| Core | `AMBASSADOR_UPDATE_MAPPING_STATUS` | `false` | Boolean; `true`=true, any other value=false | -| Core | `AMBASSADOR_DISABLE_SNAPSHOT_SERVER` | `false` | Boolean; non-empty=true, empty=false | -| Core | `AMBASSADOR_JSON_LOGGING` | `false` | Boolean; non-empty=true, empty=false | -| Core | `AMBASSADOR_FORCE_SECRET_VALIDATION` | `false` | Boolean: `true`=true, any other value=false | -| $AESproductName$ | `AES_LOG_LEVEL` | `warn` | Log level | -| Developer Portal | `DEVPORTAL_CONTENT_URL` | `https://github.com/datawire/devportal-content` | git-remote URL | -| Developer Portal | `DEVPORTAL_CONTENT_DIR` | `/` | Rooted Git directory | -| Developer Portal | `DEVPORTAL_CONTENT_BRANCH` | `master` | Git branch name | -| Developer Portal | `POLL_EVERY_SECS` | `60` | Integer | -| Envoy | `STATSD_ENABLED` | `false` | Boolean; Python `value.lower() == "true"` | -| Envoy | `DOGSTATSD` | `false` | Boolean; Python `value.lower() == "true"` | -| Envoy | `DD_ENTITY_ID` | Empty | String | -| Envoy | `ENVOY_CONCURRENCY` | Empty | Integer - -Log level names are case-insensitive. From least verbose to most -verbose, valid log levels are `error`, `warn`/`warning`, `info`, -`debug`, and `trace`. - -## 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 when `AMBASSADOR_FAST_RECONFIGURE` is set; 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` when `AMBASSADOR_FAST_RECONFIGURE` is set | - -[^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/content/en/docs/3.0/topics/running/gzip.md b/content/en/docs/3.0/topics/running/gzip.md deleted file mode 100644 index e3005c83..00000000 --- a/content/en/docs/3.0/topics/running/gzip.md +++ /dev/null @@ -1,55 +0,0 @@ -# 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/content/en/docs/3.0/topics/running/host-crd.md b/content/en/docs/3.0/topics/running/host-crd.md deleted file mode 100644 index db561ee1..00000000 --- a/content/en/docs/3.0/topics/running/host-crd.md +++ /dev/null @@ -1,262 +0,0 @@ -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` - - - Remember that Listener resources are required for a functioning - $productName$ installation!
- Learn more about Listener. - - - - Remember than $productName$ does not make sure that a wildcard Host exists! If the - wildcard behavior is needed, a Host with a hostname of "*" - must be defined by the user. - - -A minimal `Host` resource, assuming no TLS configuration, would be: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: minimal-host -spec: - hostname: host.example.com -``` - -This `Host` tells $productName$ to expect to be reached at `host.example.com`, -with no TLS termination, and only associating with `Mapping`s that also set a -`hostname` that matches `host.example.com`. - -Remember that a 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. - -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 `selector` is a Kubernetes [label selector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#labelselector-v1-meta), but **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. - -## 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/content/en/docs/3.0/topics/running/http3.md b/content/en/docs/3.0/topics/running/http3.md deleted file mode 100644 index 9aeb6cac..00000000 --- a/content/en/docs/3.0/topics/running/http3.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -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`. - - -The protocolStack elements need to be entered in the specific order of TLS, HTTP, UDP. - - -The `Listener` configured for HTTP/3 can be bound to the same address and port (`0.0.0.0:8443`) as the `Listener` that supports HTTP/2 and HTTP/1.1. This is not required, but it allows $productName$ to inject the default `alt-svc: h3=":443"; ma=86400, h3-29=":443"; ma=86400` header into the responses returned over the TCP connection with no additional configuration needed. **Most clients such as browsers require the `alt-svc` header to upgrade to HTTP/3**. - - -The current default of 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. - - -```yaml -# This is a standard Listener that leverages TCP to serve HTTP/2 and HTTP/1.1 traffic. -# It is bound to the same address and port (0.0.0.0:8443) as the UDP listener. -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: $productDeploymentName$-https-listener - namespace: $productNamespace$ -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: - namespace: - from: ALL ---- -# This is a Listener that leverages UDP and HTTP to serve HTTP/3 traffic. -# NOTE: Raw UDP traffic is not supported. UDP and HTTP must be used together. -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: $productDeploymentName$-https-listener-udp - namespace: $productNamespace$ -spec: - port: 8443 - # Order is important here. HTTP is required. - protocolStack: - - TLS - - HTTP - - UDP - securityModel: XFP - hostBinding: - namespace: - from: ALL -``` - -### Configuring the Host resource - -Because the QUIC network requires TLS, the certificate needs to be valid so the client can upgrade a connection to HTTP/3. See the [Host documentation](./host-crd.md) for more information on how to configure TLS for a `Host`. - -### Certificate verification - -Clients can only upgrade to an HTTP/3 connection with a valid certificate. If the client won’t upgrade to HTTP/3, verify that you have a valid TLS certificate and that your client can speak **TLS v1.3**. Your `Host` resource should be configured similar to the following: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: my-domain-host -spec: - hostname: your-hostname - # acme isn't required but just shown as an example of how to manage a valid TLS cert - acmeProvider: - email: your-email@example.com - authority: https://acme-v02.api.letsencrypt.org/directory - tls: - # QUIC requires TLS v1.3 version. Verify your client supports it. - min_tls_version: v1.3 - # Either protocol can be upgraded, but http/2 is recommended. - alpn_protocols: h2,http/1.1 -``` - -### External load balancers - -The two most common service types to expose traffic outside of a Kubernetes cluster are: - -- `LoadBalancer`: A load balancer controller generates and manages the cloud provider-specific external load balancer. -- `NodePort`: The platform administrator has to manually set up things like the external load balancer, firewall rules, and health checks. - -#### LoadBalancer setup - -The ideal setup would be to configure a single service of type `LoadBalancer`, but this comes with some current restrictions: -- You need version 1.24 or later of Kubernetes with the [`MixedProtocolLBService` feature enabled](https://kubernetes.io/docs/concepts/services-networking/service/#load-balancers-with-mixed-protocol-types). -- Your cloud service provider needs to support the creation of an external load balancer with mixed protocol types (TCP/UDP), port reuse, and port forwarding. Support for Kubernetes feature flags may vary between cloud service providers. Refer to your provider’s documentation to see if they support this scenario. - -An example `LoadBalancer` configuration that fits the criteria listed above: - -```yaml - -# note: extra fields such as labels and selectors removed for clarity -apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$ - namespace: $productNamespace$ -spec: - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - - name: http3 - port: 443 - targetPort: 8443 - protocol: UDP - type: LoadBalancer -``` - -## Cloud service provider setup - -Once you've completed the steps above, you need to configure HTTP/3 support through your cloud service provider. The configuration processes for each provider can be found here: - -- HTTP/3 setup for [Amazon Elastic Kubernetes Service (EKS)](../../../howtos/http3-eks) -- HTTP/3 setup for [Azure Kubernetes Service (AKS)](../../../howtos/http3-aks) -- HTTP/3 setup for [Google Kubernetes Engine (GKE)](../../../howtos/http3-gke) diff --git a/content/en/docs/3.0/topics/running/index.md b/content/en/docs/3.0/topics/running/index.md deleted file mode 100644 index c196e969..00000000 --- a/content/en/docs/3.0/topics/running/index.md +++ /dev/null @@ -1,16 +0,0 @@ -# Running $productName$ in production - -This section of the documentation is designed for operators and site reliability engineers who are managing the deployment of $productName$. Learn more below: - -* *Global Configuration:* The [Ambassador module](ambassador) is used to set system-wide configuration. -* *Exposing $productName$ to the Internet:* The [`Listener` CRD](listener) defines which ports are exposed, including their protocols and security models. The [`Host` CRD](host-crd) defines how $productName$ manages TLS, domains, and such. -* *Load Balancing:* $productName$ supports a number of different [load balancing strategies](load-balancer) as well as different ways to configure [service discovery](resolvers) -* [Gzip Compression](gzip) -* *Deploying $productName$:* On [Amazon Web Services](ambassador-with-aws) | [Google Cloud](ambassador-with-gke) | [general security and operational notes](running), including running multiple $productNamePlural$ on a cluster -* *TLS/SSL:* [Simultaneously Routing HTTP and HTTPS](tls/cleartext-redirection#cleartext-routing) | [HTTP -> HTTPS Redirection](tls/cleartext-redirection#http-https-redirection) | [Mutual TLS](tls/mtls) | [TLS origination](tls/origination) -* *Statistics and Monitoring:* [Integrating with Prometheus, DataDog, and other monitoring systems](statistics) -* *Extending $productName$* $productName$ can be extended with custom plug-ins that connect via HTTP/gRPC interfaces. [Custom Authentication](services/auth-service) | [The External Auth protocol](services/ext_authz) | [Custom Logging](services/log-service) | [Rate Limiting](services/rate-limit-service) | [Distributed Tracing](services/tracing-service) -* *Troubleshooting:* [Diagnostics](diagnostics) | [Debugging](debugging) -* *Scaling $productName$:* [Scaling $productName$](scaling) -* *Ingress:* $productName$ can function as an [Ingress Controller](ingress-controller) -* *Error Response Overrides:* $productName$ can override 4xx and 5xx responses with [custom response bodies](custom-error-responses) diff --git a/content/en/docs/3.0/topics/running/ingress-controller.md b/content/en/docs/3.0/topics/running/ingress-controller.md deleted file mode 100644 index 9b7afb82..00000000 --- a/content/en/docs/3.0/topics/running/ingress-controller.md +++ /dev/null @@ -1,325 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Ingress controller - -
-

Contents

- -- [When and how to use the Ingress resource](#when-and-how-to-use-the-ingress-resource) -- [What is required to use the Ingress resource?](#what-is-required-to-use-the-ingress-resource) -- [When to use an Ingress instead of annotations or CRDs](#when-to-use-an-ingress-instead-of-annotations-or-crds) -- [Ingress support](#ingress-support) -- [Examples of Ingress configs vs Mapping configs](#examples-of-ingress-configs-vs-mapping-configs) -- [Ingress routes and mappings](#ingress-routes-and-mappings) -- [The Minimal Ingress](#the-minimal-ingress) -- [Name based virtual hosting with an Ambassador ID](#name-based-virtual-hosting-with-an-ambassador-id) -- [TLS Termination](#tls-termination) - -
- -An Ingress resource is a popular way to expose Kubernetes services to the Internet. In order to use Ingress resources, you need to install an [ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/). $productName$ can function as a fully-fledged Ingress controller, making it easy to work with other Ingress-oriented tools within the Kubernetes ecosystem. - -## When and how to use the Ingress resource - -If you're new to $productName$ and to Kubernetes, we'd recommend you start with our [quickstart](../../../tutorials/getting-started/) instead of this Ingress guide. If you're a power user and need to integrate with other software that leverages the Ingress resource, read on. The Ingress specification is very basic and does not support many of the features of $productName$, so you'll be using both the Ingress resource and $productName$'s Mapping resource to manage your Kubernetes services. - -### What is required to use the Ingress resource? - -- Know what version of Kubernetes you are using. - - - In Kubernetes 1.13 and below, the Ingress was only included in the `extensions` API. - - - Starting in Kubernetes 1.14, the Ingress was added to the new `networking.k8s.io` API. - - - Kubernetes 1.18 introduced the IngressClass resource to the existing `networking.k8s.io/v1beta1` API. - - If you are using 1.14 and above, it is recommended to use 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. - - -- You will need RBAC permissions to create Ingress resources in either - the `extensions` `apiGroup` (present in all supported versions of - Kubernetes) or the `networking.k8s.io` `apiGroup` (introduced in - Kubernetes 1.14). - -- $productName$ will need RBAC permissions to get, list, watch, and update Ingress resources. - - You can see this in the [`aes-crds.yaml`](https://app.getambassador.io/yaml/ambassador-docs/latest/aes.yaml) - file, but this is the critical rule to add to $productName$'s `Role` or `ClusterRole`: - - ```yaml - - apiGroups: ['extensions', 'networking.k8s.io'] - resources: ['ingresses', 'ingressclasses'] - verbs: ['get', 'list', 'watch'] - - apiGroups: ['extensions', 'networking.k8s.io'] - resources: ['ingresses/status'] - verbs: ['update'] - ``` - - - This is included by default in all $productName$ installations. - - -- You must create your Ingress resource with the correct `ingress.class`. - - $productName$ will automatically read Ingress resources with the annotation - `kubernetes.io/ingress.class: ambassador`. - -- You may need to set your Ingress resource's `ambassador-id`. - - If you are [using `amabssador-id` on your Module](../running/#ambassador_id), you'll need to add the `getambassador.io/ambassador-id` - annotation to your Ingress. See the [examples below](#name-based-virtual-hosting-with-an-ambassador-id). - -- You must create a Service resource with the correct `app.kubernetes.io/component` label. - - $productName$ will automatically load balance Ingress resources using the endpoint exposed - from the Service with the annotation `app.kubernetes.io/component: ambassador-service`. - - ```yaml - --- - kind: Service - apiVersion: v1 - metadata: - name: ingress-ambassador - labels: - app.kubernetes.io/component: ambassador-service - spec: - externalTrafficPolicy: Local - type: LoadBalancer - selector: - service: ambassador - ports: - - name: http - port: 80 - targetPort: http - - name: https - port: 443 - targetPort: https - ``` - -### When to use an Ingress instead of annotations or CRDs - -We recommend that $productName$ be configured using CRDs. The Ingress resource is available to users who need it for integration with other ecosystem tools, or who feel that it more closely matches their workflows. However, it is important to recognize that the Ingress resource is rather more limited than the $productName$ Mapping is (for example, the Ingress spec has no support for rewriting or for TLS origination). **When in doubt, use CRDs.** - -## Ingress support - -$productName$ supports basic core functionality of the Ingress resource, as defined by the [Ingress resource](https://kubernetes.io/docs/concepts/services-networking/ingress/) itself: - -- Basic routing is supported, including the `route` specification and the default backend functionality. It's particularly easy to use a minimal Ingress to the $productName$ diagnostic UI. -- [TLS termination](../tls/) is supported. You can use multiple Ingress resources for SNI. -- Using the Ingress resource in concert with $productName$ CRDs or annotations is supported. This includes $productName$ annotations on the Ingress resource itself. - -$productName$ does **not** extend the basic Ingress specification with the following exceptions: - -- The `getambassador.io/ambassador-id` annotation allows you to set [the Ambassador ID](../running/#ambassador_id) for the Ingress itself. - -- The `getambassador.io/config` annotation can be provided on the Ingress resource, just as on a Service. - -Note that if you need to set `getambassador.io/ambassador-id` on the Ingress, you will also need to set `ambassador-id` on resources within the annotation. - -## Examples of Ingress configs vs Mapping configs - -### Ingress routes and Mappings - -$productName$ actually creates Mapping objects from the Ingress route rules. These Mapping objects interact with Mappings defined in CRDs **exactly** as they would if the Ingress route rules had been specified with CRDs originally. - -For example, this Ingress resource routes traffic to `/foo/` to `service1`: - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: test-ingress -spec: - rules: - - http: - paths: - - path: /foo/ - backend: - serviceName: service1 - servicePort: 80 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: test-ingress-0-0 -spec: - hostname: '*' - prefix: /foo/ - service: service1:80 -``` - -This YAML will set up $productName$ to do canary routing where 50% of the traffic will go to `service1` and 50% will go to `service2`. - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: test-ingress -spec: - rules: - - http: - paths: - - path: /foo/ - backend: - serviceName: service1 - servicePort: 80 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: my-mapping -spec: - hostname: '*' - prefix: /foo/ - service: service2 -``` - -### The minimal Ingress - -An Ingress resource must provide at least some routes or a [default backend](https://kubernetes.io/docs/concepts/services-networking/ingress/#default-backend). The default backend provides for a simple way to direct all traffic to some upstream service: - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: test-ingress -spec: - backend: - serviceName: exampleservice - servicePort: 8080 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: test-ingress -spec: - hostname: '*' - prefix: / - service: exampleservice:8080 -``` - -### Name based virtual hosting with an Ambassador ID - -This Ingress resource will result in all requests to `foo.bar.com` going to `service1`, and requests to `bar.foo.com` going to `service2`: - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - getambassador.io/ambassador-id: externalid - name: name-virtual-host-ingress -spec: - rules: - - host: foo.bar.com - http: - paths: - - backend: - serviceName: service1 - servicePort: 80 - - host: bar.foo.com - http: - paths: - - backend: - serviceName: service2 - servicePort: 80 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: host-foo-mapping -spec: - ambassador_id: ['externalid'] - prefix: / - host: foo.bar.com - service: service1 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: host-bar-mapping -spec: - ambassador_id: ['externalid'] - prefix: / - host: bar.foo.com - service: service2 -``` - -Read more on the [Kubernetes documentation on name based virtual routing](https://kubernetes.io/docs/concepts/services-networking/ingress/#name-based-virtual-hosting). - -### TLS termination - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: tls-example-ingress -spec: - tls: - - hosts: - - sslexample.foo.com - secretName: testsecret-tls - rules: - - host: sslexample.foo.com - http: - paths: - - path: / - backend: - serviceName: service1 - servicePort: 80 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: sslexample-termination-context -spec: - hosts: - - sslexample.foo.com - secret: testsecret-tls ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: sslexample-mapping -spec: - host: sslexample.foo.com - prefix: / - service: service1 -``` - -Note that this shows TLS termination, not origination: the Ingress spec does not support origination. Read more on the [Kubernetes docs on TLS termination](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls). diff --git a/content/en/docs/3.0/topics/running/listener.md b/content/en/docs/3.0/topics/running/listener.md deleted file mode 100644 index 152e1b74..00000000 --- a/content/en/docs/3.0/topics/running/listener.md +++ /dev/null @@ -1,218 +0,0 @@ -# The `Listener` CRD - -The `Listener` CRD defines where, and how, $productName$ should listen for requests from the network, and which `Host` definitions should be used to process those requests. For further examples of how to use `Listener`, see [Configuring $productName$ Communications](../../../howtos/configure-communications). - -**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. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 # int32, port number on which to listen - protocol: HTTPS # HTTP, HTTPS, HTTPPROXY, HTTPSPROXY, TCP - securityModel: XFP # XFP (for X-Forwarded-Proto), SECURE, INSECURE - statsPrefix: example-listener # default depends on protocol; see below - l7Depth: 0 # int32 - hostBinding: - namespace: - from: SELF # SELF, ALL - selector: ... # Kubernetes label selector -``` - -| Element | Type | Definition | -| :------ | :--- | :--------- | -| `port` | `int32` | The network port on which $productName$ should listen. *Required.* | -| `protocol` | `enum`; see below | A high-level protocol type, like "HTTPS". *Exactly one of `protocol` and `protocolStack` must be supplied.* | -| `protocolStack` | array of `enum`; see below | A sequence of low-level protocols to layer together. *Exactly one of `protocol` and `protocolStack` must be supplied.* | -| `securityModel` | `enum`; see below | How does $productName$ decide whether requests here are secure? *Required.* | -| `statsPrefix` | `string`; see below | Under what name do statistics for this `Listener` appear? *Optional; default depends on protocol.* | -| `l7Depth` | `int32` | How many layer 7 load balancers are between the edge of the network and $productName$? *Optional; default is 0.*| -| `hostBinding` | `struct`, see below | Mechanism for determining which `Host`s will be associated with this `Listener`. *Required* | - -### `protocol` and `protocolStack` - -`protocol` is the **recommended** way to tell $productName$ that a `Listener` expects connections using a well-known protocol. When using `protocol`, `protocolStack` may not also be supplied. - -Valid `protocol` values are: - -| `protocol` | Description | -| :--------- | :---------- | -| `HTTP` | Cleartext-only HTTP. HTTPS is not allowed. | -| `HTTPS` | Either HTTPS or HTTP -- Envoy's TLS support can tell whether or not TLS is in use, and it will set `X-Forwarded-Proto` correctly for later decision-making. | -| `HTTPPROXY` | Cleartext-only HTTP, using the HAProxy `PROXY` protocol. | -| `HTTPSPROXY` | Either HTTPS or HTTP, using the HAProxy `PROXY` protocol. | -| `TCP` | TCP sessions without HTTP at all. You will need to use `TCPMapping`s to route requests for this `Listener`. | -| `TLS` | TLS sessions without HTTP at all. You will need to use `TCPMapping`s to route requests for this `Listener`. | - -### `securityModel` - -`securityModel` defines how the `Listener` will decide whether a request is secure or insecure: - -| `securityModel` | Description | -| :--------- | :---------- | -| `XFP` | Requests are secure if, and only if, `X-Forwarded-Proto` indicates HTTPS. This is common; see below. | -| `SECURE` | Requests are always secure. You might set this if your load balancer always terminates TLS for you, and you can trust the clients. | -| `INSECURE` | Requests are always insecure. You might set this for an HTTP-only `Listener`, or a `Listener` for clients that are expected to be hostile. | - -The `X-Forwarded-Proto` header mentioned above is meant to reflect the protocol the _original client_ -used to contact $productName$. When no layer 7 proxies are in use, Envoy will make certain that the -`X-Forwarded-Proto` header matches the wire protocol of the connection the client made to Envoy, -which allows $productName$ to trust `X-Forwarded-Proto` for routing decisions such as deciding to -redirect requests made using HTTP over to HTTPS for greater security. When using $productName$ as an -edge proxy or a typical API gateway, this is a desirable configuration; setting `securityModel` to -`XFP` makes this easy. - -When layer proxies _are_ in use, the `XFP` setting is often still desirable; however, you will also -need to set `l7Depth` to allow it to function. See below. - -`SECURE` and `INSECURE` are helpful for cases where something downstream of $productName$ should be -allowing only one kind of request to reach $productName$. For example, a `Listener` behind a load -balancer that terminates TLS and checks client certificates might use -`SecurityModel: SECURE`, then use `Host`s to reject insecure requests if one somehow -arrives. - -### `l7Depth` - -When layer 7 (L7) proxies are in use, the connection to $productName$ comes from the L7 proxy itself -rather than from the client. Examining the protocol and IP address of that connection is useless, and -instead you need to configure the L7 proxy to pass extra information about the client to $productName$ -using the `X-Forwarded-Proto` and `X-Forwarded-For` headers. - -However, if $productName$ always trusted `X-Forwarded-Proto` and `X-Forwarded-For`, any client could -use them to lie about itself to $productName$. As a security mechanism, therefore, you must _also_ -set `l7Depth` in the `Listener` to the number of trusted L7 proxies in front of $productName$. If -`l7Depth` is not set in the `Listener`, the `xff_num_trusted_hops` value from the `ambassador` `Module` -will be used. If neither is set, the default `l7Depth` is 0. - -When `l7Depth` is 0, any incoming `X-Forwarded-Proto` is stripped: Envoy always provides an -`X-Forwarded-Proto` matching the wire protocol of the incoming connection, so that `X-Forwarded-Proto` -can be trusted. When `l7Depth` is non-zero, `X-Forwarded-Proto` is accepted from the L7 proxy, and -trusted. The actual wire protocol in use from the L7 proxy to $productName$ is ignored. - -`l7Depth` also affects $productName$'s view of the client's source IP address, which is used as the -`remote_address` field when rate limiting, and for the `X-Envoy-External-Address` header: - -- When `l7Depth` is 0, $productName$ uses the IP address of the incoming connection. -- When `l7Depth` is some value N that is non-zero, the behavior is determined by the value of - `use_remote_address` in the `ambassador` `Module`: - - - When `use_remote_address` is true (the default) then the trusted client address will be the Nth - address from the right end of the `X-Forwarded-For` header. (If the XFF contains fewer than N - addresses, Envoy falls back to using the immediate downstream connection’s source address as a - trusted client address.) - - - When `use_remote_address` is false, the trusted client address is the (N+1)th address from the - right end of XFF. (If the XFF contains fewer than N+1 addresses, Envoy falls back to using the - immediate downstream connection’s source address as a trusted client address.) - - For more detailed examples of this interaction, refer to [Envoy's documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers.html#x-forwarded-for). - - -### `hostBinding` - -`hostBinding` specifies how this `Listener` should determine which `Host`s are associated with it: - -- `namespace.from` allows filtering `Host`s by the namespace of the `Host`: - - `namespace.from: SELF` accepts only `Host`s in the same namespace as the `Listener`. - - `namespace.from: ALL` accepts `Host`s in any namespace. -- `selector` accepts only `Host`s that has labels matching the selector. - -`hostBinding` is mandatory, and at least one of `namespace.from` and `selector` must be set. If both are set, both must match for a `Host` to be accepted. - -### `statsPrefix` - -$productName$ produces detailed [statistics](../statistics) which can be monitored in a variety of ways. Statistics have hierarchical names, and the `Listener` will cause a set of statistics to be logged under the name specified by `statsPrefix`. - -The default `statsPrefix` depends on the protocol for this `Listener`: - -- If the `Listener` speaks HTTPS, the default is `ingress-https`. -- Otherwise, if the `Listener` speaks HTTP, the default is `ingress-http`. -- Otherwise, if the `Listener` speaks TLS, the default is `ingress-tls-$port`. -- Otherwise, the default is `ingress-$port`. - -Note that it doesn't matter whether you use `protocol` or `protocolStack`: what matters is what protocol is actually configured. Also note that the default doesn't take the HAProxy `PROXY` protocol into account. - -Some examples: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 - protocol: HTTPS - ... -``` - -will use a `statsPrefix` of `ingress-https`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 - protocol: TCP - ... -``` - -will use `statsPrefix` of `ingress-8080`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 - protocol: HTTPSPROXY - statsPrefix: proxy-8080 - ... -``` - -would also use `ingress-https`, but it explicitly overrides `statsPrefix` to `proxy-8080`. - -For complete information on which statistics will appear for the `Listener`, see [the Envoy listener statistics documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/listeners/stats.html). Some important statistics include - -| Statistic name | Type | Description | -| :-----------------------------------------------| :-------- | :-------------------------------- | -| `listener.$statsPrefix.downstream_cx_total` | Counter | Total connections | -| `listener.$statsPrefix.downstream_cx_active` | Gauge | Total active connections | -| `listener.$statsPrefix.downstream_cx_length_ms` | Histogram | Connection length in milliseconds | - -### `protocolStack` - -**`protocolStack` is not recommended if you can instead use `protocol`.** - -Where `protocol` allows configuring the `Listener` to use well-known protocol stacks, `protocolStack` allows configuring exactly which protocols will be layered together. If `protocol` allows what you need, it is safer to use `Protocol` than to risk having the stack broken with an incorrect `protocolStack`. - -The possible stack elements are: - -| `ProtocolStack` Element | Description | -| :---------------------- | :---------- | -| `HTTP` | Cleartext-only HTTP; must be layered with `TLS` for HTTPS | -| `PROXY` | The HAProxy `PROXY` protocol | -| `TLS` | TLS | -| `TCP` | Raw TCP | - -`protocolStack` supplies a list of these elements to describe the protocol stack. **Order matters.** Some examples: - -| `protocolStack` | Description | -| :-------------- | :---------- | -| [ `HTTP`, `TCP` ] | Cleartext-only HTTP, exactly equivalent to `protocol: HTTP`. | -| [ `TLS`, `HTTP`, `TCP` ] | HTTPS or HTTP, exactly equivalent to `protocol: HTTPS`. | -| [ `PROXY`, `TLS`, `TCP` ] | The `PROXY` protocol, wrapping `TLS` _afterward_, wrapping raw TCP. This isn't equivalent to any `protocol` setting, and may be nonsensical. | - -## Examples - -For further examples of how to use `Listener`, see [Configuring $productName$ to Communicate](../../../howtos/configure-communications). diff --git a/content/en/docs/3.0/topics/running/load-balancer.md b/content/en/docs/3.0/topics/running/load-balancer.md deleted file mode 100644 index 987a910b..00000000 --- a/content/en/docs/3.0/topics/running/load-balancer.md +++ /dev/null @@ -1,209 +0,0 @@ -# Load balancing - -Load balancing configuration can be set for all $productName$ mappings in the [`ambassador` `Module`](../ambassador), or set per [`Mapping`](../../using/mappings). If nothing is set, simple round robin balancing is used via Kubernetes services. - -To use advanced load balancing, you must first configure a [resolver](../resolvers) that supports advanced load balancing (e.g., the Kubernetes Endpoint Resolver or Consul Resolver). Once a resolver is configured, you can use the `load_balancer` attribute. The following fields are supported: - -```yaml -load_balancer: - policy: -``` - -Supported load balancer policies: - -- `round_robin` -- `least_request` -- `ring_hash` -- `maglev` - -For more information on the different policies and the implications, see [load balancing strategies in Kubernetes](https://blog.getambassador.io/load-balancing-strategies-in-kubernetes-l4-round-robin-l7-round-robin-ring-hash-and-more-6a5b81595d6c). - -## Round robin -When `policy` is set to `round_robin`, $productName$ discovers healthy endpoints for the given mapping, and load balances the incoming L7 requests with round robin scheduling. To specify this: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - resolver: my-resolver - load_balancer: - policy: round_robin -``` - -or, per mapping: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - resolver: my-resolver - hostname: '*' - load_balancer: - policy: round_robin -``` - -Note that load balancing may not appear to be "even" due to Envoy's threading model. For more details, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/faq/load_balancing/concurrency_lb). - -## Least request - -When `policy` is set to `least_request`, $productName$ discovers healthy endpoints for the given mapping, and load balances the incoming L7 requests to the endpoint with the fewest active requests. To specify this: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - resolver: my-resolver - load_balancer: - policy: least_request -``` - -or, per mapping: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend/ -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: least_request -``` - -## Sticky sessions / session affinity - -Configuring sticky sessions makes $productName$ route requests to a specific pod providing your service in a given session. One pod serves all requests from a given session, eliminating the need for session data to be transferred between pods. $productName$ lets you configure session affinity based on the following parameters in an incoming request: - -- Cookie -- Header -- Source IP - -**NOTE:** $productName$ supports sticky sessions using two load balancing policies, `ring_hash` and `maglev`. - -### Cookie - -```yaml -load_balancer: - policy: ring_hash - cookie: - name: - ttl: - path: -``` - -If the cookie you wish to set affinity on is already present in incoming requests, then you only need the `cookie.name` field. However, if you want $productName$ to generate and set a cookie in response to the first request, then you need to specify a value for the `cookie.ttl` field which generates a cookie with the given expiration time. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - hostname: '*' - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - cookie: - name: sticky-cookie - ttl: 60s -``` - -### Header - -```yaml -load_balancer: - policy: ring_hash - header:
-``` - -$productName$ allows header based session affinity if the given header is present on incoming requests. - -Example: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - header: STICKY_HEADER -``` - -#### Source IP - -```yaml -load_balancer: - policy: ring_hash - source_ip: -``` - -$productName$ allows session affinity based on the source IP of incoming requests. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - source_ip: true -``` - -Load balancing can be configured both globally, and overridden on a per mapping basis. The following example configures the default load balancing policy to be round robin, while using header-based session affinity for requests to the `/backend/` endpoint of the quote application: - -Load balancing can be configured both globally, and overridden on a per mapping basis. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - resolver: my-resolver - load_balancer: - policy: round_robin -``` - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - header: STICKY_HEADER -``` diff --git a/content/en/docs/3.0/topics/running/resolvers.md b/content/en/docs/3.0/topics/running/resolvers.md deleted file mode 100644 index 1ace9a86..00000000 --- a/content/en/docs/3.0/topics/running/resolvers.md +++ /dev/null @@ -1,128 +0,0 @@ -# Service discovery and resolvers - -Service discovery is how cloud applications and their microservices are located on the network. In a cloud environment, services are ephemeral, existing only as long as they are needed and in use, so a real-time service discovery mechanism is required. $productName$ uses information from service discovery to determine where to route incoming requests. - -## $productName$ support for service discovery - -$productName$ supports different mechanisms for service discovery. These mechanisms are: - -* Kubernetes service-level discovery (default). -* Kubernetes endpoint-level discovery. -* Consul endpoint-level discovery. - -### Kubernetes service-level discovery - -By default, $productName$ uses Kubernetes DNS and service-level discovery. In a `Mapping` resource, specifying `service: foo` will prompt $productName$ to look up the DNS address of the `foo` Kubernetes service. Traffic will be routed to the `foo` service. Kubernetes will then load balance that traffic between multiple pods. For more details on Kubernetes networking and how this works, see our blog post on [Session affinity, load balancing controls, gRPC-Web, and $productName$](https://blog.getambassador.io/session-affinity-load-balancing-controls-grpc-web-and-ambassador-0-52-2b916b396d0c). - -### Kubernetes endpoint-level discovery - -$productName$ can also watch Kubernetes endpoints. This bypasses the Kubernetes service routing layer and enables the use of advanced load balancing controls such as session affinity and maglev. For more details, see the [load balancing reference](../load-balancer). - -### Consul endpoint-level discovery - -$productName$ natively integrates with [Consul](https://www.consul.io) for endpoint-level service discovery. In this mode, $productName$ obtains endpoint information from Consul. One of the primary use cases for this architecture is in hybrid cloud environments that run a mixture of Kubernetes services as well as VMs, as Consul can serve as the single global registry for all services. - -## The Resolver resource - -The `Resolver` resource is used to configure the discovery service strategy for $productName$. - -### The Kubernetes service resolver - -The Kubernetes Service Resolver configures $productName$ to use Kubernetes services. If no resolver is specified, this behavior is the default. When this resolver is used, the `service.namespace` value from a `Mapping` is handed to the Kubernetes cluster's DNS resolver to determine where requests are sent. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: KubernetesServiceResolver -metadata: - name: kubernetes-service -``` - -### The Kubernetes endpoint resolver - -The Kubernetes Endpoint Resolver configures $productName$ to resolve Kubernetes endpoints. This enables the use of more a [advanced load balancing configuration](../load-balancer). When this resolver is used, the endpoints for the `service` defined in a `Mapping` are resolved and used to determine where requests are sent. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: KubernetesEndpointResolver -metadata: - name: endpoint -``` - -### The Consul resolver - -The Consul Resolver configures $productName$ to use Consul for service discovery. When this resolver is used, the `service` defined in a `Mapping` is passed to Consul, along with the datacenter specified, to determine where requests are sent. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: ConsulResolver -metadata: - name: consul-dc1 -spec: - address: consul-server.default.svc.cluster.local:8500 - datacenter: dc1 -``` -- `address`: The fully-qualified domain name or IP address of your Consul server. This field also supports environment variable substitution. -- `datacenter`: The Consul data center where your services are registered - -You may want to use an environment variable if you're running a Consul agent on each node in your cluster. In this setup, you could do the following: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: ConsulResolver -metadata: - name: consul-dc1 -spec: - address: "${HOST_IP}" - datacenter: dc1 -``` - -and then add the `HOST_IP` environment variable to your Kubernetes deployment: - -```yaml -containers: - - name: example - image: docker.io/datawire/ambassador:$version$ - env: - - name: HOST_IP - valueFrom: - fieldRef: - fieldPath: status.hostIP -``` - -## Using resolvers - -Once a resolver is defined, you can use them in a given `Mapping`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: "*" - prefix: /backend/ - service: quote - resolver: endpoint - load_balancer: - policy: round_robin ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: bar -spec: - hostname: "*" - prefix: /bar/ - service: https://bar:9000 - tls: client-context - resolver: consul-dc1 - load_balancer: - policy: round_robin -``` - -The YAML configuration above will configure $productName$ to use Kubernetes Service Discovery to route to the Consul Service Discovery to route to the `bar` service on requests with `prefix: /bar/`. diff --git a/content/en/docs/3.0/topics/running/running.md b/content/en/docs/3.0/topics/running/running.md deleted file mode 100644 index a28b0cb5..00000000 --- a/content/en/docs/3.0/topics/running/running.md +++ /dev/null @@ -1,338 +0,0 @@ -# Running and deployment - -This section is intended for operators running $productName$, and covers various aspects of deploying and configuring the $productName$ in production. - -## $productName$ and Kubernetes - -$productName$ relies on Kubernetes for reliability, availability, and scalability. This means that features such as Kubernetes readiness and liveness probes, rolling updates, and the Horizontal Pod Autoscaling should be utilized to manage $productName$. - -## Default configuration - -The default configuration of $productName$ includes default [resource limits](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-requests-and-limits-of-pod-and-container), as well as [readiness and liveness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/). These values should be adjusted for your specific environment. - -## Running as non-root - -Starting with $productName$ 0.35, we support running $productName$ as non-root. This is the recommended configuration, and will be the default configuration in future releases. We recommend you configure $productName$ to run as non-root as follows: - -* Have Kubernetes run $productName$ as non-root. This may happen by default (e.g., OpenShift) or you can set a `securityContext` in your Deployment as shown below in this abbreviated example: - -```yaml ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: ambassador -spec: - replicas: 1 - selector: - matchLabels: - service: ambassador - template: - metadata: - labels: - service: ambassador - spec: - containers: - image: docker.io/datawire/aes:$version$ - name: ambassador - restartPolicy: Always - securityContext: - runAsUser: 8888 - serviceAccountName: ambassador -``` - -* Set the `service_port` element in the `ambassador Module` to 8080 (cleartext) or 8443 (TLS). This is the port that $productName$ will use to listen to incoming traffic. Note that any port number above 1024 will work; $productName$ will use 8080/8443 as its defaults in the future. - -* Make sure that incoming traffic to $productName$ is configured to route to the `service_port`. If you're using the default $productName$ configuration, this means configuring the `targetPort` to point to the `service_port` above. - -* If you are using `redirect_cleartext_from`, change the value of this field to point to your cleartext port (e.g., 8080) and set `service_port` to be your TLS port (e.g., 8443). - -## Changing the configuration directory - -While running, $productName$ needs to use a directory within its container for generated configuration data. Normally this is `/ambassador`, but in some situations - especially if running as non-root - it may be necessary to change to a different directory. To do so, set the environment variable `AMBASSADOR_CONFIG_BASE_DIR` to the full pathname of the directory to use, as shown below in this abbreviated example: - -```yaml -env: -- name: AMBASSADOR_CONFIG_BASE_DIR - value: /tmp/ambassador-config -``` - -With `AMBASSADOR_CONFIG_BASE_DIR` set as above, $productName$ will create and use the directory `/tmp/ambassador-config` for its generated data. (Note that, while the directory will be created if it does not exist, attempts to turn an existing file into a directory will fail.) - -## Running as DaemonSet - -$productName$ can be deployed as a DaemonSet to have one pod per node in a Kubernetes cluster. This setup is especially helpful when you have a Kubernetes cluster running on a private cloud. - -* In an ideal example scenario, you are running containers on Kubernetes alongside with your non-containerized applications running exposed via VIP using BIG-IP or similar products. In such cases, east-west traffic is routed based on iRules to certain a set of application pools consisting of application or web servers. In this setup, alongside traditional application servers, two or more $productName$ pods can also be part of the application pools. In case of failure there is at least one $productName$ pod available to BIG-IP that can take care of routing traffic to the Kubernetes cluster. - -* In manifest files `kind: Deployment` needs to be updated to `kind: DaemonSet` and `replicas` should be removed in `spec` section. - -## Namespaces - -$productName$ supports multiple namespaces within Kubernetes. To make this work correctly, you need to set the `AMBASSADOR_NAMESPACE` environment variable in $productName$'s container. By far the easiest way to do this is using Kubernetes' downward API (this is included in the YAML files from `getambassador.io`): - -```yaml -env: -- name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace -``` - -Given that `AMBASSADOR_NAMESPACE` is set, $productName$ [`Mappings`](../../using/mappings) can operate within the same namespace, or across namespaces. **Note well** that `Mappings` will have to explicitly include the namespace with the service to cross namespaces; see the [`Mapping`](../../using/mappings) documentation for more information. - -If you want $productName$ to only work within a single namespace, set `AMBASSADOR_SINGLE_NAMESPACE` as an environment variable. - -```yaml -env: -- name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace -- name: AMBASSADOR_SINGLE_NAMESPACE - value: "true" -``` - -With $productName$, if you set `AMBASSADOR_NAMESPACE` or `AMBASSADOR_SINGLE_NAMESPACE`, set it in the deployment container. - -If you want to set a certificate for your `TLScontext` from another namespace, you can use the following: - -```yaml -env: -- name: AMBASSADOR_SINGLE_NAMESPACE - value: "YES" -- name: AMBASSADOR_CERTS_SINGLE_NAMESPACE - value: "YES" -- name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - apiVersion: v1 - fieldPath: metadata.namespace -``` - -## `AMBASSADOR_ID` - -$productName$ supports running multiple $productNamePlural$ in the same cluster, without restricting a given $productName$ to a single namespace. This is done with the `AMBASSADOR_ID` setting. In the `ambassador Module`, set the `ambassador_id`, e.g., - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - ambassador_id: [ "ambassador-1" ] - config: - ... -``` - -Then, assign each $productName$ pod a unique `AMBASSADOR_ID` with the environment variable as part of your deployment: - -```yaml -env: -- name: AMBASSADOR_ID - value: ambassador-1 -``` - -With $productName$, if you set `AMBASSADOR_ID`, you will need to set it in the deployment container. - -$productName$ will then only use YAML objects that include an appropriate `ambassador_id` attribute. For example, if $productName$ is given the ID `ambassador-1` as above, only the first two YAML objects below will be used: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-used -spec: - ambassador_id: [ "ambassador-1" ] - prefix: /demo1/ - service: demo1 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-used-2 -spec: - ambassador_id: [ "ambassador-1", "ambassador-2" ] - prefix: /demo2/ - service: demo2 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-skipped -spec: - prefix: /demo3/ - service: demo3 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-skipped-2 -spec: - ambassador_id: [ "ambassador-2" ] - prefix: /demo4/ - service: demo4 -``` - -`ambassador_id` is always a list, and may (as shown in `mapping-used-2` above) include multiple IDs to allow a given object in the configuration for multiple $productName$ instances. In this case, `mapping-used-2` will be included in the configuration for `ambassador-1` and also for `ambassador-2`. - -**Note well that _any_ $productName$ configuration resource can have an `ambassador_id` included** so, for example, it is _fully supported_ to use `ambassador_id` to qualify the `ambassador Module`, `TLSContext`, and `AuthService` objects. You will need to set `ambassador_id` in all resources you want to use for $productName$. - -If no `AMBASSADOR_ID` is assigned to an $productName$, it will use the ID `default`. If no `ambassador_id` is present in a YAML object, it will also use the ID `default`. - -## `AMBASSADOR_ENVOY_BASE_ID` - -$productName$ supports running side-by-side with other envoy-based projects in a single pod. An example of this is running with an `istio` sidecar. This is done with the `AMBASSADOR_ENVOY_BASE_ID` environment variable as part of your deployment: - -```yaml -env: -- name: AMBASSADOR_ENVOY_BASE_ID - value: 1 -``` - -If no `AMBASSADOR_ENVOY_BASE_ID` is provided then it will use the ID `0`. For more information on the Envoy base-id option please see the [Envoy command line documentation](https://www.envoyproxy.io/docs/envoy/latest/operations/cli.html?highlight=base%20id#cmdoption-base-id). - -## `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. - -## `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. - -## `AMBASSADOR_LEGACY_MODE` - -Setting `AMBASSADOR_LEGACY_MODE` to `true` will result in $productName$ disabling certain features -and reverting to older codepaths which may be better preserve certain older behaviors. Legacy mode -currently has the following effects: - -- $productName$ will switch back to the $productName$ 1.6 input-resource validator (which can significantly -increase configuration latency for $productName$ installations with many resources). -- $productName$ will use the shell boot sequence that was the default up through 1.9.1, rather than the Golang boot sequence that became the default in 1.10.0. -- `AMBASSADOR_FAST_RECONFIGURE` (see below) is not supported in legacy mode. - -## `AMBASSADOR_FAST_RECONFIGURE` - -Setting `AMBASSADOR_FAST_RECONFIGURE` to "true" enables incremental reconfiguration. When enabled, $productName$ will track deltas from one configuration to the next and recalculate only what is necessary to follow the change. When disabled (the default), $productName$ will recompute the entire configuration at every change. - -**`AMBASSADOR_FAST_RECONFIGURE` is not supported when `AMBASSADOR_LEGACY_MODE` is active.** - -## Configuration from the filesystem - -If desired, $productName$ can be configured from YAML files in the directory `$AMBASSADOR_CONFIG_BASE_DIR/ambassador-config` (by default, `/ambassador/ambassador-config`, which is empty in the images built by Datawire). You could volume mount an external configuration directory here, for example, or use a custom Dockerfile to build configuration directly into a Docker image. - -Note well that while $productName$ will read its initial configuration from this directory, configuration loaded from Kubernetes annotations will _replace_ this initial configuration. If this is not what you want, you will need to set the environment variable `AMBASSADOR_NO_KUBEWATCH` so that $productName$ will not try to update its configuration from Kubernetes resources. - -Also note that the YAML files in the configuration directory must contain the $productName$ resources, not Kubernetes resources with annotations. - -## Log levels and debugging - -The $OSSproductName$ and $AESproductName$ support more verbose debugging levels. If using $OSSproductName$, the [diagnostics](../diagnostics) service has a button to enable debug logging. Be aware that if you're running $productName$ on multiple pods, the debug log levels are not enabled for all pods -- they are configured on a per-pod basis. - -If using $AESproductName$, you can 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 format - -By default, $productName$ writes its own logs in a plain text format. To produce logs as JSON instead, set the `AMBASSADOR_JSON_LOGGING` environment variable: - -```yaml -env: -- name: AMBASSADOR_JSON_LOGGING - value: "true" -``` - -## Port assignments - -$productName$ uses some TCP ports in the range 8000-8499 internally, as well as port 8877. Third-party software integrating with $productName$ should not use ports in this range on the $productName$ pod. - -## $productName$ update checks (Scout) - -$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 $productName$ will run regardless of the status of Scout (i.e., our uptime has zero impact on your uptime.) - -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. - -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. - -Unless disabled, $productName$ will also report the following anonymized information back to Datawire: - -| Attribute | Type | Description | -| :------------------------ | :---- | :------------------------ | -| `cluster_count` | int | total count of clusters in use | -| `cluster_grpc_count` | int | count of clusters using GRPC upstream | -| `cluster_http_count` | int | count of clusters using HTTP or HTTPS upstream | -| `cluster_routing_envoy_rh_count` | int | count of clusters routing using Envoy `ring_hash` | -| `cluster_routing_envoy_maglev_count` | int | count of clusters routing using Envoy `maglev` | -| `cluster_routing_envoy_lr_count` | int | count of clusters routing using Envoy `least_request` | -| `cluster_routing_envoy_rr_count` | int | count of clusters routing using Envoy `round_robin` | -| `cluster_routing_kube_count` | int | count of clusters routing using Kubernetes | -| `cluster_tls_count` | int | count of clusters originating TLS | -| `custom_ambassador_id` | bool | has the `ambassador_id` been changed from 'default'? | -| `custom_listener_port` | bool | has the listener port been changed from 80/443? | -| `diagnostics` | bool | is the diagnostics service enabled? | -| `endpoint_grpc_count` | int | count of endpoints to which $productName$ will originate GRPC | -| `endpoint_http_count` | int | count of endpoints to which $productName$ will originate HTTP or HTTPS | -| `endpoint_routing` | bool | is endpoint routing enabled? | -| `endpoint_routing_envoy_rh_count` | int | count of endpoints being routed using Envoy `ring_hash` | -| `endpoint_routing_envoy_maglev_count` | int | count of endpoints being routed using Envoy `maglev` | -| `endpoint_routing_envoy_lr_count` | int | count of endpoints being routed using Envoy `least_request` | -| `endpoint_routing_envoy_rr_count` | int | count of endpoints being routed using Envoy `round_robin` | -| `endpoint_routing_kube_count` | int | count of endpoints being routed using Kubernetes | -| `endpoint_tls_count` | int | count of endpoints to which $productName$ will originate TLS | -| `extauth` | bool | is extauth enabled? | -| `extauth_allow_body` | bool | will $productName$ send the body to extauth? | -| `extauth_host_count` | int | count of extauth hosts in use | -| `extauth_proto` | str | extauth protocol in use ('http', 'grpc', or `null` if not active) | -| `group_canary_count` | int | count of Mapping groups that include more than one Mapping | -| `group_count` | int | total count of Mapping groups in use (length of the route table) | -| `group_header_match_count` | int | count of groups using header matching (including `host` and `method`) | -| `group_host_redirect_count` | int | count of groups using host_redirect | -| `group_host_rewrite_count` | int | count of groups using host_rewrite | -| `group_http_count` | int | count of HTTP Mapping groups | -| `group_precedence_count` | int | count of groups that explicitly set the precedence of the group | -| `group_regex_header_count` | int | count of groups using regex header matching | -| `group_regex_prefix_count` | int | count of groups using regex prefix matching | -| `group_resolver_consul` | int | count of groups using the Consul resolver | -| `group_resolver_kube_endpoint` | int | count of groups using the Kubernetes endpoint resolver | -| `group_resolver_kube_service` | int | count of groups using the Kubernetes service resolver | -| `group_shadow_count` | int | count of groups using shadows | -| `group_shadow_weighted_count` | int | count of groups using shadows but not shadowing all traffic | -| `group_tcp_count` | int | count of TCP Mapping groups | -| `host_count` | int | count of Host resources in use | -| `k8s_ingress_class_count` | int | count of IngressClass resources in use | -| `k8s_ingress_count` | int | count of Ingress resources in use | -| `listener_count` | int | count of active listeners (1 unless `redirect_cleartext_from` or TCP Mappings are in use) | -| `liveness_probe` | bool | are liveness probes enabled? | -| `managed_by` | string | tool that manages the $productName$ deployment, if any (e.g. helm, edgectl, etc.) | -| `mapping_count` | int | count of Mapping resources in use | -| `ratelimit` | bool | is rate limiting in use? | -| `ratelimit_custom_domain` | bool | has the rate limiting domain been changed from 'ambassador'? | -| `ratelimit_data_plane_proto` | bool | is rate limiting using the data plane proto? | -| `readiness_probe` | bool | are readiness probes enabled? | -| `request_4xx_count` | int | lower bound for how many requests have gotten a 4xx response | -| `request_5xx_count` | int | lower bound for how many requests have gotten a 5xx response | -| `request_bad_count` | int | lower bound for how many requests have failed (either 4xx or 5xx) | -| `request_elapsed` | float | seconds over which the request_ counts are valid | -| `request_hr_elapsed` | string | human-readable version of `request_elapsed` (e.g. "3 hours 35 minutes 20 seconds" | -| `request_ok_count` | int | lower bound for how many requests have succeeded (not a 4xx or 5xx) | -| `request_total_count` | int | lower bound for how many requests were handled in total | -| `statsd` | bool | is StatsD enabled? | -| `server_name` | bool | is the `server_name` response header overridden? | -| `service_resource_total` | int | total count of service resources loaded from all discovery sources | -| `tls_origination_count` | int | count of TLS origination contexts | -| `tls_termination_count` | int | count of TLS termination contexts | -| `tls_using_contexts` | bool | are new TLSContext resources in use? ? | -| `tls_using_module` | bool |is the old TLS module in use | -| `tracing` | bool | is tracing in use? | -| `tracing_driver` | str | tracing driver in use ('zipkin', 'lightstep', 'datadog', or `null` if not active) | -| `use_proxy_proto` | bool | is the `PROXY` protocol in use? | -| `use_remote_address` | bool | is $productName$ honoring remote addresses? | -| `x_forwarded_proto_redirect` | bool | is $productName$ redirecting based on `X-Forwarded-Proto`? | -| `xff_num_trusted_hops` | int | what is the count of trusted hops for `X-Forwarded-For`? | - -The `request_*` counts are always incremental: they contain only information about the last `request_elapsed` seconds. Additionally, they only provide a lower bound -- notably, if an $productName$ pod crashes or exits, no effort is made to ship out a final update, so it's very easy for counts to never be reported. - -To completely disable feature reporting, set the environment variable `AMBASSADOR_DISABLE_FEATURES` to any non-empty value. diff --git a/content/en/docs/3.0/topics/running/scaling.md b/content/en/docs/3.0/topics/running/scaling.md deleted file mode 100644 index 1406e30f..00000000 --- a/content/en/docs/3.0/topics/running/scaling.md +++ /dev/null @@ -1,191 +0,0 @@ -# Performance and scaling $productName$ - -Scaling any cloud native application is inherently domain specific, however the content here -reflects common issues, tips, and tricks that come up frequently. - -## Performance dimensions - -The performance of $productName$'s control plane can be characterized along a number of -different dimensions: - - - The number of `TLSContext` resources. - - The number of `Host` resources. - - The number of `Mapping` resources per `Host` resource. - - The number of `Mapping` resources that will span all `Host` resources (either because they're using `host_regex`, or because they're using `hostname: "*"`). - -If your application involves a larger than average number of any of the above resources, you may -find yourself in need of some of the content in this section. - -## Mysterious pod restarts (aka pushing the edge of the envelope) - -Whether your application is growing organically or whether you are deliberately scale testing, it's -helpful to recognize how $productName$ behaves as it reaches the edge of its performance -envelope along any of these dimensions. - -As $productName$ approaches the edge of its performance envelope, it will often manifest as -mysterious pod restarts triggered by Kubernetes. This does not always mean there is a problem, it -could just mean you need to tune some of the resource limits set in your deployment. When it comes -to scaling, Kubernetes will generally kill an $productName$ pod for one of two reasons: exceeding -memory limits or failed liveness/readiness probes. See the [Memory Limits](#memory-limits), -[Liveness Probes](#liveness-probes), and [Readiness Probes](#readiness-probes) -sections for more on how to cope with these situations. - -## Memory limits - -$productName$ can grow in memory usage and be killed by Kubernetes if it exceeds the limits -defined in its pod spec. When this happens it is confusing and difficult to catch because the only -indication that this has occurred is the pod transitioning momentarily into the `OOMKilled` -state. The only way to actually observe this is if you are lucky enough to be running the following -command (or have similar monitoring configured) when $productName$ gets `OOMKilled`: - -``` - kubectl get pods -n ambassador -w -``` - -In order to take the luck out of the equation, $productName$ will periodically log its -memory usage so you can see in the logs if memory limits might be a problem and require adjustment: - -``` -2020/11/26 22:35:20 Memory Usage 0.56Gi (28%) - PID 1, 0.22Gi: busyambassador entrypoint - PID 14, 0.04Gi: /usr/bin/python /usr/bin/diagd /ambassador/snapshots /ambassador/bootstrap-ads.json /ambassador/envoy/envoy.json --notices /ambassador/notices.json --port 8004 --kick kill -HUP 1 - PID 16, 0.12Gi: /ambassador/sidecars/amb-sidecar - PID 37, 0.07Gi: /usr/bin/python /usr/bin/diagd /ambassador/snapshots /ambassador/bootstrap-ads.json /ambassador/envoy/envoy.json --notices /ambassador/notices.json --port 8004 --kick kill -HUP 1 - PID 48, 0.08Gi: envoy -c /ambassador/bootstrap-ads.json --base-id 0 --drain-time-s 600 -l error -``` - -In general you should try to keep $productName$'s memory usage below 50% of the pod's limit. This may -seem like a generous safety margin, but when reconfiguration occurs, $productName$ requires additional -memory to avoid disrupting active connections. At each reconfiguration, $productName$ keeps around the -old version for the duration of the configured drain time. See -[AMBASSADOR_DRAIN_TIME](#ambassador_drain_time) for more details on how to tune this -behavior. - -$productName$'s exact memory usage depends on (among other things) how many `Host` and -`Mapping` resources are defined in your cluster. If this number has grown over time, you may need to -increase the memory limit defined in your deployment. - -## Liveness probes - -$productName$ defines the `/ambassador/v0/check_alive` endpoint on port `8877` for use with Kubernetes -liveness probes. See the Kubernetes documentation for more details on [HTTP liveness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-a-liveness-http-request). - -Kubernetes will restart the $productName$ pod if it fails to get a 200 result from the endpoint. If -this happens it won't necessarily show up in an easily recognizable way in the pod logs. You can -look for Kubernetes events to see if this is happening. Use `kubectl describe pod -n ambassador` or -`kubectl get events -n ambassador` or equivalent. - -The purpose of liveness probes is to rescue an $productName$ instance that is wedged, however if -liveness probes are too sensitive they can take out $productName$ instances that are functioning -normally. This is more prone to happen as the number of $productName$ inputs increase. The -`timeoutSeconds` and `failureThreshold` fields of the $productName$ deployment's liveness Probe -determines how tolerant Kubernetes is with its probes. If you observe pod restarts along with -`Unhealthy` events, try tuning these fields upwards from their default values. See the Kubernetes documentation for more details on [tuning probes](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#probe-v1-core). - -Note that whatever changes you make to $productName$'s liveness probes should most likely be made to -its readiness probes also. - -## Readiness probes - -$productName$ defines the `/ambassador/v0/check_ready` endpoint on port `8877` for use with Kubernetes -readiness probes. See the Kubernetes documentation for more details on [readiness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-readiness-probes). - -Kubernetes uses readiness checks to prevent traffic from going to pods that are not ready to handle -requests. The only time $productName$ cannot usefully handle requests is during initial startup when it -has not yet loaded all the routing information from Kubernetes and/or consul. During this bootstrap -period there is no guarantee $productName$ would know where to send a given request. The `check_ready` -endpoint will only return 200 when all routing information has been loaded. After the initial -bootstrap period it behaves identically to the `check_alive` endpoint. - -Generally $productName$'s readiness probes should be configured with the same settings as its liveness -probes. - -## `AMBASSADOR_FAST_RECONFIGURE` and `AMBASSADOR_LEGACY_MODE` flags - -`AMBASSADOR_FAST_RECONFIGURE` is a feature flag that enables a higher performance implementation of -the code $productName$ uses to validate and generate envoy configuration. It will eventually be enabled -by default, but if you are experiencing performance problems you should try setting -`AMBASSADOR_FAST_RECONFIGURE` to `true` to see if this helps. - -`AMBASSADOR_LEGACY_MODE` is **not** recommended when performance is critical. - -## `AMBASSADOR_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. - -## Unconstrained Mappings with many hosts - -When working with a large number of `Host` resources, it's important to understand the impact of -unconstrained `Mapping`s. An unconstrained `Mapping` is one that is not restricted to a specific -`Host`. Such a `Mapping` will create a route for all of your `Host`s. If this is what you want then -it is the appropriate thing to do, however if you do not intend to do this, then you can end up with -many more routes than you had intended and this can adversely impact performance. - -## Inspecting $productName$ performance - -$productName$ internally tracks a number of key performance indicators. You can inspect these via the -debug endpoint at `localhost:8877/debug`. Note that the `AMBASSADOR_FAST_RECONFIGURE` flag needs to -be set to `"true"` for this endpoint to be present: - -``` -$ kubectl exec -n ambassador -it ${POD} curl localhost:8877/debug -{ - "timers": { - # These two timers track how long it takes to respond to liveness and readiness probes. - "check_alive": "7, 45.411495ms/61.85999ms/81.358927ms", - "check_ready": "7, 49.951304ms/61.976205ms/86.279038ms", - - # These two timers track how long we spend updating our in-memory snapshot when our Kubernetes - # watches tell us something has changed. - "consulUpdate": "0, 0s/0s/0s", - "katesUpdate": "3382, 28.662µs/102.784µs/95.220222ms", - - # These timers tell us how long we spend notifying the sidecars if changed input. This - # includes how long the sidecars take to process that input. - "notifyWebhook:diagd": "2, 1.206967947s/1.3298432s/1.452718454s", - "notifyWebhooks": "2, 1.207007216s/1.329901037s/1.452794859s", - - # This timer tells us how long we spend parsing annotations. - "parseAnnotations": "2, 21.944µs/22.541µs/23.138µs", - - # This timer tells us how long we spend reconciling changes to consul inputs. - "reconcileConsul": "2, 50.104µs/55.499µs/60.894µs", - - # This timer tells us how long we spend reconciling secrets related changes to $productName$ - # inputs. - "reconcileSecrets": "2, 18.704µs/20.786µs/22.868µs" - }, - "values": { - "envoyReconfigs": { - "times": [ - "2020-11-06T13:13:24.218707995-05:00", - "2020-11-06T13:13:27.185754494-05:00", - "2020-11-06T13:13:28.612279777-05:00" - ], - "staleCount": 2, - "staleMax": 0, - "synced": true - }, - "memory": "39.73Gi of Unlimited (0%)" - } -} -``` - -## Running profiles - -$productName$ exposes endpoints at `localhost:8877/debug/pprof` to run Golang profiles to aid in live debugging. The endpoints are equivalent to those found in the [http/pprof](https://pkg.go.dev/net/http/pprof) package. `/debug/pprof/` returns an HTML page listing the available profiles. - -The following are the different types of profiles you can run: - -| Profile | Function | -| :------- | :-------- | -| /debug/pprof/allocs | Returns a sampling of all past memory allocations. | -| /debug/pprof/block | Returns stack traces of goroutines that led to blocking on sychronization primitives. | -| /debug/pprof/goroutine | Returns stack traces of all current goroutines. | -| /debug/pprof/heap | Returns a sampling of memory allocations of live objects. | -| /debug/pprof/mutex | Returns stack traces of goroutines holding contended mutexes. | -| /debug/pprof/symbol | Returns the program counters listed in the request. | -| /debug/pprof/threadcreate | Returns stack traces that led to creation of new OS threads. | diff --git a/content/en/docs/3.0/topics/running/services/auth-service.md b/content/en/docs/3.0/topics/running/services/auth-service.md deleted file mode 100644 index cb598161..00000000 --- a/content/en/docs/3.0/topics/running/services/auth-service.md +++ /dev/null @@ -1,150 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Authentication service - -$productName$ provides a highly flexible mechanism for authentication, -via the `AuthService` resource. An `AuthService` configures -$productName$ to use an external service to check authentication and -authorization for incoming requests. Each incoming request is -authenticated before routing to its destination. - -All requests are validated by the `AuthService` (unless the `Mapping` -applied to the request sets `bypass_auth`). It is not possible to -combine multiple `AuthServices`. While it is possible to create -multiple `AuthService` resources, $productName$ load-balances between -them in a round-robin fashion. This is useful for canarying an -`AuthService` change, but is not useful for deploying multiple -distinct `AuthServices`. In order to combine multiple external -services (either having multiple services apply to the same request, -or selecting between different services for the different requests), -instead of using an `AuthService`, use an [$AESproductName$ `External` -`Filter`](/docs/edge-stack/latest/topics/using/filters/). - - - -Because of the limitations described above, **$AESproductName$ does -not support `AuthService` resources, and you should instead use an -[`External` -`Filter`](/docs/edge-stack/latest/topics/using/filters/external),** -which is mostly a drop-in replacement for an `AuthService`. The -`External` `Filter` relies on the $AESproductName$ `AuthService`. -Make sure the $AESproductName$ `AuthService` is deployed before -configuring `External` `Filters`. - - - -The currently supported version of the `AuthService` resource is -`getambassador.io/v3alpha1`. Earlier versions are deprecated. - -## Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: AuthService -metadata: - name: authentication -spec: - ambassador_id: [ "ambassador-1" ] - auth_service: "example-auth.authentication:3000" - tls: true - proto: http - timeout_ms: 5000 - include_body: - max_bytes: 4096 - allow_partial: true - status_on_error: - code: 403 - failure_mode_allow: false - - # proto: grpc only, default is v2. If upgrading from 2.x then you must set this to v3. - protocol_version: v3 - - # proto: http only - path_prefix: "/path" - allowed_request_headers: - - "x-example-header" - allowed_authorization_headers: - - "x-qotm-session" - add_auth_headers: - x-added-auth: auth-added - add_linkerd_headers: false -``` - -## Fields - -`auth_service` is the only required field, all others are optional. - -| Attribute | Default value | Description | -| ---------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `ambassador_id` | `[ "default" ]` | Which [Ambassador ID](../../running/#ambassador_id) the `AuthService` should apply to. | -| `auth_service` | (none; a value is required) | Identifies the external auth service to talk to. The format of this field is `scheme://host:port` where `scheme://` and `:port` are optional. The scheme-part, if present, must be either `http://` or `https://`; if the scheme-part is not present, it behaves as if `http://` is given. The scheme-part controls whether TLS or plaintext is used and influences the default value of the port-part. The host-part must be the [namespace-qualified DNS name](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#namespaces-of-services) of the service you want to use for authentication. | -| `tls` | `""` | This field is populated with the name of the defined TLSContext, which determines the TLS certificate presented to external auth services. | -| `proto` | `http` | Specifies which variant of the [`ext_authz` protocol](../ext_authz/) to use when communicating with the external auth service. Valid options are `http` or `grpc`. | -| `timeout_ms` | `5000` | The total maximum duration in milliseconds for the request to the external auth service, before triggering `status_on_error` or `failure_mode_allow`. | -| `include_body` | `null` | Controls how much to buffer the request body to pass to the external auth service, for use cases such as computing an HMAC or request signature. If `include_body` is `null` or unset, then the request body is not buffered at all, and an empty body is passed to the external auth service. If `include_body` is not `null`, the `max_bytes` and `allow_partial` subfields are required. | -| `include_body.max_bytes` | (none; a value is required if `include_body` is not `null`) | Controls the amount of body data that is passed to the external auth service. | -| `include_body.allow_partial` | (none; a value is required if `include_body` is not `null`) | Controls what happens to requests with bodies larger than `max_bytes`. If `allow_partial` is `true`, the first `max_bytes` of the body are sent to the external auth service. If `false`, the message is rejected with HTTP 413 ("Payload Too Large"). | -| `status_on_error.code` | `403` | Controls the status code returned when unable to communicate with external auth service. This is ignored if `failure_mode_allow: true`. | -| `failure_mode_allow` | `false` | Controls whether to allow or reject requests when there is an error communicating with the external auth service; a value of `true` allows the request through to the upstream backend service, a value of `false` returns a `status_on_error.code` response to the client. | -| `stats_name` | the `auth_service` value with non-alphanumeric characters replaced with underscores | See [Overriding Statistics Names](../../statistics/#overriding-statistics-names). | -| `circuit_breakers` | the value set in the [`ambassador` `Module`](../../../using/defaults) | See [Circuit Breakers](../../../using/circuit-breakers/). | - -The following field is only used if `proto` is set to `grpc`. It is -ignored if `proto` is `http`. - -| Attribute | Default value | Description | -| ------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `protocol_version` | `v3` | Allowed values are `v3` and `v2`(defualt). `protocol_version` was used in previous versions of $productName$ to control the protocol used by the gRPC service. $productName$ 3.x is running an updated version of Envoy that has dropped support for the `v2` protocol, so starting in 3.x, if `protocol_version` is not specified, 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. | - -The following fields are only used if `proto` is set to `http`. They -are ignored if `proto` is `grpc`. - -| Attribute | Default value | Description | -| ------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `path_prefix` | `""` | Prepends a string to the request path of the request when sending it to the external auth service. By default this is empty, and nothing is prepended. For example, if the client makes a request to `/foo`, and `path_prefix: /bar`, then the path in the request made to the external auth service will be `/foo/bar`. | -| `allowed_request_headers` | `[]` | Lists the headers (case-insensitive) that are copied from the incoming request to the request made to the external auth service. In addition to the headers listed in this field, the following headers are always included: `Authorization`, `Cookie`, `From`, `Proxy-Authorization`, `User-Agent`, `X-Forwarded-For`, `X-Forwarded-Host`, and `X-Forwarded-Proto`. | -| `allowed_authorization_headers` | `[]` | Lists the headers (case-insensitive) that are copied from the response from the external auth service to the request sent to the upstream backend service (if the external auth service indicates that the request to the upstream backend service should be allowed). In addition to the headers listed in this field, the following headers are always included: `Authorization`, `Location`, `Proxy-Authenticate`, `Set-cookie`, `WWW-Authenticate` | -| `add_auth_headers` | `{}` | A dictionary of `header: value` pairs that are added to the request made to the external auth service. | -| `add_linkerd_headers` | Defaults to the value set in the [`ambassador` `Module`](../../ambassador) | When true, in the request to the external auth service, adds an `l5d-dst-override` HTTP header that is set to the hostname and port number of the external auth service. | - -## Canarying multiple `AuthServices` - -You may create multiple `AuthService` manifests to round-robin -authentication requests among multiple services. **All services must -use the same `path_prefix` and header definitions.** If you try to -have different values, you'll see an error in the [diagnostics -service](../../ambassador/#diagnostics), telling you which value is -being used. - -## Configuring public `Mappings` - -An `AuthService` can be disabled for a `Mapping` by setting -`bypass_auth` to `true`. This will tell $productName$ to allow all -requests for that `Mapping` through without interacting with the -external auth service. - - - -## Transport Protocol Migration - - -> **Note:** The following information is only applicable to `AuthServices` using `proto: grpc` -As of $productName$ version 2.3, the `v2` transport protocol is deprecated and any AuthServices making use -of it should migrate to `v3` before support for `v2` is removed in a future release. - -The following imports simply need to be updated to migrate an AuthService - -`v2` Imports: -``` - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" -``` - -`v3` Imports: -``` - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" -``` diff --git a/content/en/docs/3.0/topics/running/services/ext_authz.md b/content/en/docs/3.0/topics/running/services/ext_authz.md deleted file mode 100644 index 250154f6..00000000 --- a/content/en/docs/3.0/topics/running/services/ext_authz.md +++ /dev/null @@ -1,85 +0,0 @@ -# ExtAuth protocol - -By design, the ExtAuth protocol used by [the AuthService](../auth-service) and by [External Filters](/docs/edge-stack/latest/topics/using/filters/external) is highly flexible. The authentication service is the first external service invoked on an incoming request (e.g., it runs before the rate limit filter). Because the logic of authentication is encapsulated in an external service, you can use this to support a wide variety of use cases. For example: - -* Supporting traditional SSO authentication protocols, e.g., OAuth, OpenID Connect, etc. -* Supporting HTTP basic authentication ([see a sample implementation](https://github.com/datawire/ambassador-auth-httpbasic)). -* Only authenticating requests that are under a rate limit and rejecting authentication requests above the rate limit. -* Authenticating specific services (URLs), and not others. - -For each request, the ExtAuth service may either: - 1. return a direct HTTP *response*, intended to be sent back to the requesting HTTP client (normally *denying* the request from being forwarded to the upstream backend service) or - 2. return a modification to make to the HTTP *request* before sending it to the upstream backend service (normally *allowing* the request to be forwarded to the upstream backend service with modifications). - -The ExtAuth service receives information about every request through $productName$ and must indicate whether the request is to be allowed or not. If not, the ExtAuth service provides the HTTP response which is to be handed back to the client. A potential control flow for Authentication is shown in the image below. - -Giving the ExtAuth service the ability to control the response allows many different types of auth mechanisms, for example: - -- The ExtAuth service can simply return an error page with an HTTP 401 response. -- The ExtAuth service can choose to include a `WWW-Authenticate` header in the 401 response, to ask the client to perform HTTP Basic Auth. -- The ExtAuth service can issue a 301 `Redirect` to divert the client into an OAuth or OIDC authentication sequence. The control flow of this is shown below. - -Authentication flow - -There are two variants of the ExtAuth: gRPC and plain HTTP. - -### The gRPC protocol - -When `proto: grpc` is set, the ExtAuth service must implement the `Authorization` gRPC interface, defined in [Envoy's `external_auth.proto`](https://github.com/emissary-ingress/emissary/blob/master/api/envoy/service/auth/v3/external_auth.proto). - -### The HTTP protocol - -External services for `proto: http` are often easier to implement, but have several limitations compared to `proto: grpc`. - - The list of headers that the ExtAuth service is interested in reading must be known ahead of time, in order to set `allow_request_headers`. Inspecting headers that are not known ahead of time requires instead using `proto: grpc`. - - The list of headers that the ExtAuth service would like to set or modify must be known ahead of time, in order to set `allow_authorization_headers`. Setting headers that are not known ahead of time requires instead using `proto: grpc`. - - When returning a direct HTTP response, the HTTP status code cannot be 200 or in the 5XX range. Intercepting with a 200 or 5XX response requires instead using `proto: grpc`. - -#### The request From $productName$ to the ExtAuth service - -For every incoming request, a similar request is made to the ExtAuth service that mimics the: - - HTTP request method - - HTTP request path, potentially modified by `path_prefix` - - HTTP request headers that are either named in `allowed_request_headers` or in the fixed list of headers that are always included - - first `include_body.max_bytes` of the HTTP request body. - -The `Content-Length` HTTP header is set to the number of bytes in the body of the request sent to the ExtAuth service (`0` if `include_body` is not set). - -**ALL** request methods will be proxied, which implies that the ExtAuth service must be able to handle any request that any client could make. - -Take this incoming request for example: - -``` -PUT /path/to/service HTTP/1.1 -Host: myservice.example.com:8080 -User-Agent: curl/7.54.0 -Accept: */* -Content-Type: application/json -Content-Length: 27 - -{ "greeting": "hello world!", "spiders": "OMG no" } -``` - -The request $productName$ will make of the auth service is: - -``` -PUT /path/to/service HTTP/1.1 -Host: extauth.example.com:8080 -User-Agent: curl/7.54.0 -Accept: */* -Content-Type: application/json -Content-Length: 0 -``` - -#### The response returned from the ExtAuth service to $productName$ - - - If the HTTP response returned from the ExtAuth service to $productName$ has an HTTP status code of 200, then the request is allowed through to the upstream backend service. **Only** 200 indicates this; other 2XX status codes will prevent the request from being allowed through. - - The 200 response should not contain anything in the body, but may contain arbitrary headers. Any header present in the ExtAuth service' response that is also either listed in the `allow_authorization_headers` attribute of the AuthService resource or in the fixed list of headers that are always included will be copied from the ExtAuth service's response into the request going to the upstream backend service. This allows the ExtAuth service to inject tokens or other information into the request, or to modify headers coming from the client. - - The big limitation here is that the list of headers to be set must be known ahead of time, in order to set `allow_request_headers`. Setting headers that are not known ahead of time requires instead using `proto: grpc`. - - - If $productName$ cannot reach the ExtAuth service at all, if the ExtAuth service does not return a valid HTTP response, or if the HTTP response has an HTTP status code in the 5XX range, then the communication with the ExtAuth service is considered to have failed, and the `status_on_error` or `failure_mode_allow` behavior is triggered. - - - Any HTTP status code other than 200 or 5XX from the ExtAuth service tells $productName$ to **not** allow the request to continue to the upstream backend service, but that the ExtAuth service is instead intercepting the request. The entire HTTP response from the ExtAuth service--including the status code, the headers, and the body--is handed back to the client verbatim. This gives the ExtAuth service **complete** control over the entire response presented to the client. - - The big limitation here is that you cannot directly return a 200 or 5XX response. Intercepting with a 200 of 5XX response requires instead using `proto: grpc`. diff --git a/content/en/docs/3.0/topics/running/services/index.md b/content/en/docs/3.0/topics/running/services/index.md deleted file mode 100644 index 1646aa5a..00000000 --- a/content/en/docs/3.0/topics/running/services/index.md +++ /dev/null @@ -1,11 +0,0 @@ -# Available plugins - -You may need an API Gateway to enforce policies specific to your organization. $productName$ supports custom policies through external service plugins. The policy logic specific to your organization is implemented in the external service, and $productName$ is configured to send RPC requests to your service. - -Currently, $productName$ supports plugins for authentication, -access logging, rate limiting, and tracing. - -* [AuthService](auth-service) Plugin -* [LogService](log-service) Plugin -* [RateLimitService](rate-limit-service) Plugin -* [TracingService](tracing-service) Plugin diff --git a/content/en/docs/3.0/topics/running/services/log-service.md b/content/en/docs/3.0/topics/running/services/log-service.md deleted file mode 100644 index b3e90c7c..00000000 --- a/content/en/docs/3.0/topics/running/services/log-service.md +++ /dev/null @@ -1,116 +0,0 @@ -# Log service - -By default, $productName$ puts the access logs on stdout; such -that the can be read using `kubectl logs`. The format of those logs, -and the local destination of them, can be configured using the -[`envoy_log_` settings in the `ambassador -Module`](../../ambassador). However, the -options there only allow for logging local to $productName$'s Pod. By -configuring a `LogService`, you can configure $productName$ to -report its access logs to a remote service, in addition to the usual -`ambassador Module` configured logging. - -The remote access log service (or ALS) must implement the -`AccessLogService` gRPC interface, defined in [Envoy's `als.proto`][als.proto]. - -[als.proto]: https://github.com/emissary-ingress/emissary/blob/master/api/envoy/service/accesslog/v3/als.proto - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: LogService -metadata: - name: example-log-service -spec: - # Common to all $productName$ resources - ambassador_id: []string # optional; default is ["default"] - - # LogService specific - service: "string" # required - driver: "enum-string:[tcp, http]" # required - driver_config: # required - additional_log_headers: # optional; default is [] (only for `driver: http`) - - header_name: string # required - during_request: boolean # optional; default is true - during_response: boolean # optional; default is true - during_trailer: boolean # optional; default is true - flush_interval_time: int-seconds # optional; default is 1 - flush_interval_byte_size: integer # optional; default is 16384 - grpc: boolean # optional; default is false - protocol_version: enum # optional; default is v2 -``` - - - `service` is where to route the access log gRPC requests to - - - `driver` identifies which type of accesses to log; HTTP requests (`"http"`) or - TLS connections (`"tcp"`). - - - `driver_config` stores the configuration that is specific to the `driver`: - - * `driver: tcp` has no additional configuration; the config must - be set as `driver_config: {}`. - - * `driver: http` - - - `additional_log_headers` identifies HTTP headers to include in - the access log, and when in the logged-request's lifecycle to - include them. - - - `flush_interval_time` is the maximum number of seconds to buffer - accesses for before sending them to the ALS. The logs will be - flushed to the ALS every time this duration is reached, or when the - buffered data reaches `flush_interval_byte_size`, whichever comes - first. See the [Envoy documentation on - `buffer_flush_interval`][buffer_flush_interval] for more - information. - - - `flush_interval_byte_size` is a soft size limit for the access log - buffer. The logs will be flushed to the ALS every time the - buffered data reaches this size, or whenever `flush_interval_time` - elapses, whichever comes first. See the [Envoy documentation on - `buffer_size_bytes`][buffer_size_bytes] for more information. - - - `grpc` must be `true`. - -[buffer_flush_interval]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/access_loggers/grpc/v3/als.proto.html#extensions-access-loggers-grpc-v3-commongrpcaccesslogconfig -[buffer_size_bytes]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/access_loggers/grpc/v3/als.proto.html#extensions-access-loggers-grpc-v3-commongrpcaccesslogconfig - - - `protocol_version` was used in previous versions of $productName$ to control the gRPC service name used to communicate with the `LogService`. $productName$ 3.x is running an updated version of Envoy that has dropped support for the `v2` protocol, so starting in 3.x, if `protocol_version` is not specified, 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. - -## Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: LogService -metadata: - name: als -spec: - service: "als.default:3000" - driver: http - driver_config: {} # NB: driver_config must be set, even if it's empty - grpc: true # NB: grpc must be true and it will use the V3 transport protocol -``` - -## Transport Protocol Migration - - -> **Note:** The following information is only applicable to `AuthServices` using `proto: grpc` -As of $productName$ version 2.3, the `v2` transport protocol is deprecated and any AuthServices making use -of it should migrate to `v3` before support for `v2` is removed in a future release. - -The following imports simply need to be updated to migrate an AuthService - -`v2` Imports: -``` - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" -``` - -`v3` Imports: -``` - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" -``` diff --git a/content/en/docs/3.0/topics/running/services/rate-limit-service.md b/content/en/docs/3.0/topics/running/services/rate-limit-service.md deleted file mode 100644 index 8301b862..00000000 --- a/content/en/docs/3.0/topics/running/services/rate-limit-service.md +++ /dev/null @@ -1,116 +0,0 @@ -# Rate limit service - -Rate limiting is a powerful technique to improve the [availability and -resilience of your -services](https://blog.getambassador.io/rate-limiting-a-useful-tool-with-distributed-systems-6be2b1a4f5f4). -In $productName$, each request can have one or more _labels_. These labels are -exposed to a third-party service via a gRPC API. The third-party service can -then rate limit requests based on the request labels. - -**Note that `RateLimitService` is only applicable to $OSSproductName$, -and not $AESproductName$, as $AESproductName$ includes a -built-in rate limit service.** - -## Request labels - -See [Attaching labels to -requests](../../../using/rate-limits#attaching-labels-to-requests) -for how to configure the labels that are attached to a request. - -## Domains - -In $productName$, each engineer (or team) can be assigned its own _domain_. A -domain is a separate namespace for labels. By creating individual domains, each -team can assign their own labels to a given request, and independently set the -rate limits based on their own labels. - -See [Attaching labels to -requests](../../../using/rate-limits/#attaching-labels-to-requests) -for how to labels under different domains. - -## External rate limit service - -In order for $productName$ to rate limit, you need to implement a -gRPC `RateLimitService`, as defined in [Envoy's `v3/rls.proto`] -interface. If you do not have the time or resources to implement your own rate -limit service, $AESproductName$ integrates a high-performance rate -limiting service. - -[envoy's `v3/rls.proto`]: https://github.com/emissary-ingress/emissary/tree/master/api/envoy/service/ratelimit/v3/rls.proto - -$productName$ generates a gRPC request to the external rate limit -service and provides a list of labels on which the rate limit service can base -its decision to accept or reject the request: - -``` -[ - {"source_cluster", ""}, - {"destination_cluster", ""}, - {"remote_address", ""}, - {"generic_key", ""}, - {"", ""} -] -``` - -If $productName$ cannot contact the rate limit service, it will -allow the request to be processed as if there were no rate limit service -configuration. - -It is the external rate limit service's responsibility to determine whether rate -limiting should take place, depending on custom business logic. The rate limit -service must simply respond to the request with an `OK` or `OVER_LIMIT` code: - -- If Envoy receives an `OK` response from the rate limit service, then $productName$ allows the client request to resume being processed by - the normal flow. -- If Envoy receives an `OVER_LIMIT` response, then $productName$ - will return an HTTP 429 response to the client and will end the transaction - flow, preventing the request from reaching the backing service. - -The headers injected by the [AuthService](../auth-service) can also be passed to -the rate limit service since the `AuthService` is invoked before the -`RateLimitService`. - -## Configuring the rate limit service - -A `RateLimitService` manifest configures $productName$ to use an -external service to check and enforce rate limits for incoming requests: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: RateLimitService -metadata: - name: ratelimit -spec: - service: 'example-rate-limit.default:5000' - protocol_version: # default is v2, if upgrading from 2.x then you must set this to v3. -``` - -- `service` gives the URL of the rate limit service. If using a Kubernetes service, this should be the [namespace-qualified DNS name](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#namespaces-of-services) of that service. -- `protocol_version` Allowed values are `v3` and `v2`(defualt). `protocol_version` was used in previous versions of $productName$ to control the protocol used by the gRPC service to communicate with the `RateLimitService`. $productName$ 3.x is running an updated version of Envoy that has dropped support for the `v2` protocol, so starting in 3.x, if `protocol_version` is not specified, 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. - -You may only use a single `RateLimitService` manifest. - -## Rate limit service and TLS - -You can tell $productName$ to use TLS to talk to your service by -using a `RateLimitService` with an `https://` prefix. However, you may also -provide a `tls` attribute: if `tls` is present and `true`, $productName$ will originate TLS even if the `service` does not have the `https://` -prefix. - -If `tls` is present with a value that is not `true`, the value is assumed to be the name of a defined TLS context, which will determine the certificate presented to the upstream service. - -## Example - -The [$OSSproductName$ Rate Limiting -Tutorial](../../../../howtos/rate-limiting-tutorial) has a simple rate limiting -example. For a more advanced example, read the [advanced rate limiting -tutorial](../../../../../2.0/howtos/advanced-rate-limiting), which uses the rate limit -service that is integrated with $AESproductName$. - -## Further reading - -- [Rate limiting: a useful tool with distributed systems](https://blog.getambassador.io/rate-limiting-a-useful-tool-with-distributed-systems-6be2b1a4f5f4) -- [Rate limiting for API Gateways](https://blog.getambassador.io/rate-limiting-for-api-gateways-892310a2da02) -- [Implementing a Java Rate Limiting Service for $productName$](https://blog.getambassador.io/implementing-a-java-rate-limiting-service-for-the-ambassador-api-gateway-e09d542455da) -- [Designing a Rate Limit Service for $productName$](https://blog.getambassador.io/designing-a-rate-limiting-service-for-ambassador-f460e9fabedb) diff --git a/content/en/docs/3.0/topics/running/services/tracing-service.md b/content/en/docs/3.0/topics/running/services/tracing-service.md deleted file mode 100644 index 044f4f4c..00000000 --- a/content/en/docs/3.0/topics/running/services/tracing-service.md +++ /dev/null @@ -1,69 +0,0 @@ -# Tracing service - -Applications that consist of multiple services can be difficult to debug, as a single request can span multiple services. Distributed tracing tells the story of your request as it is processed through your system. Distributed tracing is a powerful tool to debug and analyze your system in addition to request logging and metrics. - -When enabled, the `TracingService` will instruct $productName$ to initiate a trace on requests by generating and populating an `x-request-id` HTTP header. Services can make use of this `x-request-id` header in logging and forward it in downstream requests for tracing. $productName$ also integrates with external trace visualization services, including [LightStep](https://lightstep.com/) and Zipkin-compatible APIs such as [Zipkin](https://zipkin.io/) and [Jaeger](https://github.com/jaegertracing/) to allow you to store and visualize traces. You can read further on [Envoy's Tracing capabilities](https://www.envoyproxy.io/docs/envoy/v1.10.0/intro/arch_overview/tracing). - -A `TracingService` manifest configures $productName$ to use an external trace visualization service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TracingService -metadata: - name: tracing -spec: - service: "example-zipkin:9411" - driver: zipkin - config: {} - tag_headers: - - ":authority" - - ":path" - sampling: - overall: 100 -``` - -- `service` gives the URL of the external HTTP trace service. -- `driver` provides the driver information that handles communicating with the `service`. Supported values are `lightstep`, `zipkin`, and `datadog`. -- `config` provides additional configuration options for the selected `driver`. -- `tag_headers` (optional) if present, specifies a list of other HTTP request headers which will be used as tags in the trace's span. -- `propagation_modes` (optional) if present, specifies a list of the propogation modes to be used. Possible values: - - `ENVOY` - - `LIGHTSTEP` - - `B3` - - `TRACE_CONTEXT` -- `sampling` (optional) if present, specifies some target percentages of requests that will be traced. - - `client`: percentage of requests that will be force traced if the `x-client-trace-id` header is set. Defaults to 100. - - `random`: percentage of requests that will be randomly traced. Defaults to 100. - - `overall`: percentage of requests that will be traced after all other checks have been applied (force tracing, sampling, etc.). - This field functions as an upper limit on the total configured sampling rate. For instance, setting `client` - to `100%` but `overall` to `1%` will result in only `1%` of client requests with the appropriate headers to be force - traced. Defaults to 100. - - -Please note that you must use the HTTP/2 pseudo-header names. For example: - -- the `host` header should be specified as the `:authority` header; and -- the `method` header should be specified as the `:method` header. - -### Lightstep driver configurations - -- `access_token_file` provides the location of the file containing the access token to the LightStep API. - -### Zipkin driver configurations - -- `collector_endpoint` gives the API endpoint of the Zipkin service where the spans will be sent. The default value is `/api/v2/spans` -- `collector_endpoint_version` gives the transport version used when sending data to your Zipkin collector. The default value is `HTTP_JSON` and it must be one of `HTTP_JSON` or `HTTP_PROTO`. -- `collector_endpoint_hostname` sets the hostname Envoy will use when sending data to your Zipkin collector. The default value is the name of the underlying Envoy cluster. -- `trace_id_128bit` whether a 128-bit `trace id` will be used when creating a new trace instance. Defaults to `true`. Setting to `false` will result in a 64-bit trace id being used. -- `shared_span_context` whether client and server spans will share the same `span id`. The default value is `true`. - -### Datadog Driver Configurations - -- `service_name` the name of the service which is attached to the traces. The default value is `ambassador`. - -You may only use a single `TracingService` manifest per $productName$ deployment. Ensure [ambassador_id](../../running#ambassador_id) is set correctly in the `TracingService` manifest. - -## Example - -Check out the [DataDog](../../../../howtos/tracing-datadog) and [Zipkin](../../../../howtos/tracing-zipkin) HOWTOs. diff --git a/content/en/docs/3.0/topics/running/statistics/8877-metrics-grafana.json b/content/en/docs/3.0/topics/running/statistics/8877-metrics-grafana.json deleted file mode 100644 index b2b19b37..00000000 --- a/content/en/docs/3.0/topics/running/statistics/8877-metrics-grafana.json +++ /dev/null @@ -1,943 +0,0 @@ -{ - "annotations": { - "list": [ - { - "builtIn": 1, - "datasource": "Prometheus", - "enable": true, - "hide": true, - "iconColor": "rgba(0, 211, 255, 1)", - "name": "Annotations & Alerts", - "type": "dashboard" - } - ] - }, - "description": "Ambassador dashboard for Prometheus", - "editable": true, - "gnetId": 4698, - "graphTooltip": 0, - "id": 1, - "iteration": 1595611060519, - "links": [], - "panels": [ - { - "collapsed": false, - "datasource": null, - "gridPos": { - "h": 1, - "w": 24, - "x": 0, - "y": 0 - }, - "id": 34, - "panels": [], - "title": "Ambassador - Control Plane", - "type": "row" - }, - { - "cacheTimeout": null, - "colorBackground": false, - "colorValue": false, - "colors": [ - "#299c46", - "rgba(237, 129, 40, 0.89)", - "#d44a3a" - ], - "datasource": null, - "format": "none", - "gauge": { - "maxValue": 100, - "minValue": 0, - "show": false, - "thresholdLabels": false, - "thresholdMarkers": true - }, - "gridPos": { - "h": 5, - "w": 5, - "x": 0, - "y": 1 - }, - "id": 36, - "interval": "", - "links": [], - "mappingType": 1, - "mappingTypes": [ - { - "name": "value to text", - "value": 1 - }, - { - "name": "range to text", - "value": 2 - } - ], - "maxDataPoints": 100, - "maxPerRow": 3, - "nullPointMode": "connected", - "nullText": null, - "options": {}, - "postfix": "", - "postfixFontSize": "50%", - "prefix": "", - "prefixFontSize": "50%", - "rangeMaps": [ - { - "from": "null", - "text": "N/A", - "to": "null" - } - ], - "repeat": null, - "repeatDirection": "h", - "sparkline": { - "fillColor": "rgba(31, 118, 189, 0.18)", - "full": false, - "lineColor": "rgb(31, 120, 193)", - "show": false, - "ymax": null, - "ymin": null - }, - "tableColumn": "", - "targets": [ - { - "expr": "ambassador_diagnostics_info{namespace=~\"$namespace\"}", - "format": "time_series", - "hide": false, - "instant": true, - "intervalFactor": 1, - "legendFormat": "{{version}}", - "refId": "A" - } - ], - "thresholds": "", - "timeFrom": null, - "timeShift": null, - "title": "Version", - "type": "singlestat", - "valueFontSize": "80%", - "valueMaps": [], - "valueName": "name" - }, - { - "cacheTimeout": null, - "datasource": null, - "gridPos": { - "h": 5, - "w": 19, - "x": 5, - "y": 1 - }, - "id": 42, - "links": [], - "options": { - "displayMode": "lcd", - "fieldOptions": { - "calcs": [ - "lastNotNull" - ], - "defaults": { - "mappings": [], - "max": 2.5, - "min": 0, - "nullValueMode": "connected", - "thresholds": [ - { - "color": "green", - "value": null - }, - { - "color": "#EAB839", - "value": 1 - }, - { - "color": "red", - "value": 2 - } - ], - "title": "", - "unit": "s" - }, - "override": {}, - "values": false - }, - "orientation": "vertical" - }, - "pluginVersion": "6.4.3", - "repeat": "pod", - "repeatDirection": "v", - "scopedVars": { - "pod": { - "selected": false, - "text": "ambassador-x", - "value": "ambassador-x" - } - }, - "targets": [ - { - "expr": "ambassador_reconfiguration_time_seconds{namespace=~\"$namespace\", pod=~\"$pod\"}", - "instant": false, - "legendFormat": "Reconfiguration", - "refId": "C" - }, - { - "expr": "ambassador_fetcher_time_seconds{namespace=~\"$namespace\", pod=~\"$pod\"}", - "instant": false, - "legendFormat": "Fetcher", - "refId": "E" - }, - { - "expr": "ambassador_aconf_time_seconds{namespace=~\"$namespace\", pod=~\"$pod\"}", - "instant": false, - "legendFormat": "AConf", - "refId": "A" - }, - { - "expr": "ambassador_ir_time_seconds{namespace=~\"$namespace\", pod=~\"$pod\"}", - "instant": false, - "legendFormat": "IR", - "refId": "F" - }, - { - "expr": "ambassador_econf_time_seconds{namespace=~\"$namespace\", pod=~\"$pod\"}", - "instant": false, - "legendFormat": "EConf", - "refId": "B" - }, - { - "expr": "ambassador_diagnostics_time_seconds{namespace=~\"$namespace\", pod=~\"$pod\"}", - "instant": false, - "legendFormat": "Diagnostics", - "refId": "D" - } - ], - "timeFrom": null, - "timeShift": null, - "title": "Last control plane operation time ($pod)", - "type": "bargauge" - }, - { - "collapsed": true, - "datasource": null, - "gridPos": { - "h": 1, - "w": 24, - "x": 0, - "y": 6 - }, - "id": 38, - "panels": [ - { - "aliasColors": {}, - "bars": false, - "dashLength": 10, - "dashes": false, - "datasource": null, - "fill": 1, - "fillGradient": 0, - "gridPos": { - "h": 7, - "w": 24, - "x": 0, - "y": 2 - }, - "id": 40, - "legend": { - "avg": false, - "current": false, - "max": false, - "min": false, - "show": true, - "total": false, - "values": false - }, - "lines": true, - "linewidth": 1, - "nullPointMode": "null", - "options": { - "dataLinks": [] - }, - "percentage": false, - "pointradius": 2, - "points": false, - "renderer": "flot", - "seriesOverrides": [], - "spaceLength": 10, - "stack": false, - "steppedLine": false, - "targets": [ - { - "expr": " ambassador_edge_stack_go_memstats_alloc_bytes{namespace=~\"$namespace\", pod=~\"$pod\"}", - "legendFormat": "{{pod}}", - "refId": "A" - } - ], - "thresholds": [], - "timeFrom": null, - "timeRegions": [], - "timeShift": null, - "title": "amb-sidecar memory usage", - "tooltip": { - "shared": true, - "sort": 0, - "value_type": "individual" - }, - "type": "graph", - "xaxis": { - "buckets": null, - "mode": "time", - "name": null, - "show": true, - "values": [] - }, - "yaxes": [ - { - "format": "decbytes", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": true - }, - { - "format": "none", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": false - } - ], - "yaxis": { - "align": false, - "alignLevel": null - } - } - ], - "title": "Ambassador", - "type": "row" - }, - { - "collapsed": false, - "datasource": null, - "gridPos": { - "h": 1, - "w": 24, - "x": 0, - "y": 7 - }, - "id": 22, - "panels": [], - "repeat": null, - "title": "Ambassador - Envoy Data Plane", - "type": "row" - }, - { - "aliasColors": {}, - "bars": false, - "dashLength": 10, - "dashes": false, - "datasource": null, - "fill": 1, - "fillGradient": 0, - "gridPos": { - "h": 8, - "w": 24, - "x": 0, - "y": 8 - }, - "id": 30, - "legend": { - "avg": false, - "current": false, - "max": false, - "min": false, - "show": true, - "total": false, - "values": false - }, - "lines": true, - "linewidth": 1, - "links": [], - "nullPointMode": "null", - "options": { - "dataLinks": [] - }, - "percentage": false, - "pointradius": 2, - "points": false, - "renderer": "flot", - "seriesOverrides": [], - "spaceLength": 10, - "stack": false, - "steppedLine": false, - "targets": [ - { - "expr": "sum(increase(envoy_http_downstream_rq_xx{envoy_response_code_class=\"2\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "2xx", - "refId": "A" - }, - { - "expr": "sum(increase(envoy_http_downstream_rq_xx{envoy_response_code_class=\"3\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "3xx", - "refId": "B" - }, - { - "expr": "sum(increase(envoy_http_downstream_rq_xx{envoy_response_code_class=\"4\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "4xx", - "refId": "C" - }, - { - "expr": "sum(increase(envoy_http_downstream_rq_xx{envoy_response_code_class=\"5\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "5xx", - "refId": "D" - } - ], - "thresholds": [], - "timeFrom": null, - "timeRegions": [], - "timeShift": null, - "title": "Ambassador Response Codes", - "tooltip": { - "shared": true, - "sort": 0, - "value_type": "individual" - }, - "type": "graph", - "xaxis": { - "buckets": null, - "mode": "time", - "name": null, - "show": true, - "values": [] - }, - "yaxes": [ - { - "format": "short", - "label": "RPM", - "logBase": 1, - "max": null, - "min": null, - "show": true - }, - { - "format": "short", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": true - } - ], - "yaxis": { - "align": false, - "alignLevel": null - } - }, - { - "aliasColors": {}, - "bars": false, - "dashLength": 10, - "dashes": false, - "datasource": null, - "fill": 1, - "fillGradient": 0, - "gridPos": { - "h": 8, - "w": 24, - "x": 0, - "y": 16 - }, - "id": 20, - "legend": { - "avg": false, - "current": false, - "max": false, - "min": false, - "show": true, - "total": false, - "values": false - }, - "lines": true, - "linewidth": 1, - "links": [], - "nullPointMode": "null", - "options": { - "dataLinks": [] - }, - "percentage": false, - "pointradius": 2, - "points": false, - "renderer": "flot", - "seriesOverrides": [], - "spaceLength": 10, - "stack": false, - "steppedLine": false, - "targets": [ - { - "expr": "sum(increase(envoy_cluster_upstream_rq_xx{envoy_response_code_class=\"2\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "2xx", - "refId": "A" - }, - { - "expr": "sum(increase(envoy_cluster_upstream_rq_xx{envoy_response_code_class=\"3\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "3xx", - "refId": "B" - }, - { - "expr": "sum(increase(envoy_cluster_upstream_rq_xx{envoy_response_code_class=\"4\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "4xx", - "refId": "C" - }, - { - "expr": "sum(increase(envoy_cluster_upstream_rq_xx{envoy_response_code_class=\"5\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "5xx", - "refId": "D" - } - ], - "thresholds": [], - "timeFrom": null, - "timeRegions": [], - "timeShift": null, - "title": "API Response Codes", - "tooltip": { - "shared": true, - "sort": 0, - "value_type": "individual" - }, - "type": "graph", - "xaxis": { - "buckets": null, - "mode": "time", - "name": null, - "show": true, - "values": [] - }, - "yaxes": [ - { - "format": "short", - "label": "RPM", - "logBase": 1, - "max": null, - "min": null, - "show": true - }, - { - "format": "short", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": true - } - ], - "yaxis": { - "align": false, - "alignLevel": null - } - }, - { - "aliasColors": {}, - "bars": false, - "dashLength": 10, - "dashes": false, - "datasource": null, - "fill": 1, - "fillGradient": 0, - "gridPos": { - "h": 8, - "w": 24, - "x": 0, - "y": 24 - }, - "id": 26, - "legend": { - "avg": false, - "current": false, - "max": false, - "min": false, - "show": true, - "total": false, - "values": false - }, - "lines": true, - "linewidth": 1, - "links": [], - "nullPointMode": "null", - "options": { - "dataLinks": [] - }, - "percentage": false, - "pointradius": 2, - "points": false, - "renderer": "flot", - "seriesOverrides": [], - "spaceLength": 10, - "stack": false, - "steppedLine": false, - "targets": [ - { - "expr": "histogram_quantile(0.95, sum(rate(envoy_http_downstream_cx_length_ms_bucket[5m])) by (le))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "95 percentile", - "refId": "A" - }, - { - "expr": "histogram_quantile(0.9, sum(rate(envoy_http_downstream_cx_length_ms_bucket[5m])) by (le))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "90th percentile", - "refId": "B" - }, - { - "expr": "histogram_quantile(0.5, sum(rate(envoy_http_downstream_cx_length_ms_bucket[5m])) by (le))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "50th percentile", - "refId": "C" - } - ], - "thresholds": [], - "timeFrom": null, - "timeRegions": [], - "timeShift": null, - "title": "Downstream Connections Length", - "tooltip": { - "shared": true, - "sort": 0, - "value_type": "individual" - }, - "type": "graph", - "xaxis": { - "buckets": null, - "mode": "time", - "name": null, - "show": true, - "values": [] - }, - "yaxes": [ - { - "format": "short", - "label": "Milliseconds", - "logBase": 1, - "max": null, - "min": null, - "show": true - }, - { - "format": "short", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": true - } - ], - "yaxis": { - "align": false, - "alignLevel": null - } - }, - { - "aliasColors": {}, - "bars": false, - "dashLength": 10, - "dashes": false, - "datasource": null, - "fill": 1, - "fillGradient": 0, - "gridPos": { - "h": 8, - "w": 18, - "x": 0, - "y": 32 - }, - "id": 28, - "legend": { - "avg": false, - "current": false, - "max": false, - "min": false, - "show": true, - "total": false, - "values": false - }, - "lines": true, - "linewidth": 1, - "links": [], - "nullPointMode": "null", - "options": { - "dataLinks": [] - }, - "percentage": false, - "pointradius": 2, - "points": false, - "renderer": "flot", - "seriesOverrides": [], - "spaceLength": 10, - "stack": false, - "steppedLine": false, - "targets": [ - { - "expr": "sum(increase(envoy_http_downstream_cx_http1_active[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "HTTP/1", - "refId": "A" - }, - { - "expr": "sum(increase(envoy_http_downstream_cx_http2_active_active[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "HTTP/2", - "refId": "B" - }, - { - "expr": "sum(increase(envoy_http_downstream_cx_upgrades_active[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "Websocket", - "refId": "C" - } - ], - "thresholds": [], - "timeFrom": null, - "timeRegions": [], - "timeShift": null, - "title": "Active Connections", - "tooltip": { - "shared": true, - "sort": 0, - "value_type": "individual" - }, - "type": "graph", - "xaxis": { - "buckets": null, - "mode": "time", - "name": null, - "show": true, - "values": [] - }, - "yaxes": [ - { - "format": "short", - "label": "RPM", - "logBase": 1, - "max": null, - "min": null, - "show": true - }, - { - "format": "short", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": true - } - ], - "yaxis": { - "align": false, - "alignLevel": null - } - }, - { - "cacheTimeout": null, - "colorBackground": false, - "colorValue": false, - "colors": [ - "#299c46", - "rgba(237, 129, 40, 0.89)", - "#d44a3a" - ], - "datasource": null, - "format": "none", - "gauge": { - "maxValue": 100, - "minValue": 0, - "show": false, - "thresholdLabels": false, - "thresholdMarkers": true - }, - "gridPos": { - "h": 8, - "w": 6, - "x": 18, - "y": 32 - }, - "id": 32, - "interval": null, - "links": [], - "mappingType": 1, - "mappingTypes": [ - { - "name": "value to text", - "value": 1 - }, - { - "name": "range to text", - "value": 2 - } - ], - "maxDataPoints": 100, - "nullPointMode": "connected", - "nullText": null, - "options": {}, - "postfix": "", - "postfixFontSize": "50%", - "prefix": "", - "prefixFontSize": "50%", - "rangeMaps": [ - { - "from": "null", - "text": "N/A", - "to": "null" - } - ], - "sparkline": { - "fillColor": "rgba(31, 118, 189, 0.18)", - "full": false, - "lineColor": "rgb(31, 120, 193)", - "show": false - }, - "tableColumn": "", - "targets": [ - { - "expr": "avg(envoy_cluster_manager_active_clusters)", - "format": "time_series", - "intervalFactor": 1, - "refId": "A" - } - ], - "thresholds": "", - "timeFrom": null, - "timeShift": null, - "title": "Registered Services", - "type": "singlestat", - "valueFontSize": "80%", - "valueMaps": [ - { - "op": "=", - "text": "N/A", - "value": "null" - } - ], - "valueName": "avg" - } - ], - "refresh": "5s", - "schemaVersion": 20, - "style": "dark", - "tags": [ - "ambassador" - ], - "templating": { - "list": [ - { - "allValue": null, - "current": { - "text": "All", - "value": [ - "$__all" - ] - }, - "datasource": "Prometheus", - "definition": "label_values(ambassador_diagnostics_info, namespace)", - "hide": 0, - "includeAll": true, - "label": "Namespace", - "multi": true, - "name": "namespace", - "options": [], - "query": "label_values(ambassador_diagnostics_info, namespace)", - "refresh": 1, - "regex": "", - "skipUrlSync": false, - "sort": 5, - "tagValuesQuery": "", - "tags": [], - "tagsQuery": "", - "type": "query", - "useTags": false - }, - { - "allValue": null, - "current": { - "tags": [], - "text": "All", - "value": [ - "$__all" - ] - }, - "datasource": "Prometheus", - "definition": "label_values(ambassador_diagnostics_info{namespace=\"$namespace\"}, pod)", - "hide": 0, - "includeAll": true, - "label": "Pod", - "multi": true, - "name": "pod", - "options": [], - "query": "label_values(ambassador_diagnostics_info{namespace=\"$namespace\"}, pod)", - "refresh": 1, - "regex": "", - "skipUrlSync": false, - "sort": 5, - "tagValuesQuery": "", - "tags": [], - "tagsQuery": "", - "type": "query", - "useTags": false - } - ] - }, - "time": { - "from": "now-15m", - "to": "now" - }, - "timepicker": { - "refresh_intervals": [ - "5s", - "10s", - "30s", - "1m", - "5m", - "15m", - "30m", - "1h", - "2h", - "1d" - ], - "time_options": [ - "5m", - "15m", - "1h", - "6h", - "12h", - "24h", - "2d", - "7d", - "30d" - ] - }, - "timezone": "", - "title": "Ambassador", - "uid": "AJieHz4Mz", - "version": 16 -} diff --git a/content/en/docs/3.0/topics/running/statistics/8877-metrics.md b/content/en/docs/3.0/topics/running/statistics/8877-metrics.md deleted file mode 100644 index 09e7da34..00000000 --- a/content/en/docs/3.0/topics/running/statistics/8877-metrics.md +++ /dev/null @@ -1,79 +0,0 @@ -# The metrics endpoint - -> For an overview of other options for gathering statistics on -> $productName$, see the [Statistics and Monitoring](../) overview. - -Each $productName$ pod exposes statistics and metrics for that pod at -`http://{POD}:8877/metrics`. The response is in the text-based -Prometheus [exposition format][]. - -[exposition format]: https://prometheus.io/docs/instrumenting/exposition_formats/ - -## Understanding the statistics - -The Prometheus exposition format includes special "HELP" lines that -make the file self-documenting as to what specific statistics mean. - - - -- `envoy_*`: See the [Envoy documentation][`GET /stats/prometheus`]. -- `ambassador_*` (new in 1.7.0): - - `ambassador_edge_stack_*` (not present in $OSSproductName$): - - `ambassador_edge_stack_go_*`: See [`promethus.NewGoCollector()`][]. - - `ambassador_edge_stack_promhttp_*` See [`promhttp.Handler()`][]. - - `ambassador_edge_stack_process_*`: See [`promethus.NewProcessCollector()`][].. - - `ambassador_*_time_seconds` (for `*` = one of `aconf`, `diagnostics`, `econf`, `fetcher`, `ir`, or `reconfiguration`): - Gauges of how long the various core operations take in the diagd - process. - - `ambassador_diagnostics_(errors|notices)`: The number of - diagnostics errors and notices that would be shown in the - diagnostics UI or the Edge Policy Console. - - `ambassador_diagnostics_info`: [Info][`prometheus_client.Info`] - about the $productName$ install; all information is presented in - labels; the value of the Gauge is always "1". - - `ambassador_process_*`: See [`prometheus_client.ProcessCollector`][]. - -[`GET /stats/prometheus`]: https://www.envoyproxy.io/docs/envoy/v1.15.0/operations/admin.html#get--stats-prometheus -[`prometheus.NewProcessCollector`]: https://godoc.org/github.com/prometheus/client_golang/prometheus#NewProcessCollector -[`prometheus.NewGoCollector`]: https://godoc.org/github.com/prometheus/client_golang/prometheus#NewGoCollector -[`promhttp.Handler()`]: https://godoc.org/github.com/prometheus/client_golang/prometheus/promhttp#Handler -[`prometheus_client.Info`]: https://github.com/prometheus/client_python#info -[`prometheus_client.ProcessCollector`]: https://github.com/prometheus/client_python#process-collector - -## Polling the `:8877/metrics` endpoint with Prometheus - -To scrape metrics directly, follow the instructions for [Monitoring -with Prometheus and Grafana](../../../../howtos/prometheus). - -### Using Grafana to visualize statistics gathered by Prometheus - -#### Sample dashboard - -We provide a [sample Grafana dashboard](https://grafana.com/dashboards/13758) -that displays information collected by Prometheus from the -`:8877/metrics` endpoint. - - -#### Just Envoy information - -Screenshot of a Grafana dashboard that displays just information from Envoy - -[Alex Gervais][] has written a template [$productName$ dashboard for -Grafana][] that displays information collected by Prometheus either -from the `:8877/metrics` endpoint, or from [Envoy over -StatsD][envoy-statsd-prometheus]. Because it is designed to work with -the Envoy StatsD set up, it does not include any of the `ambassador_*` -statistics; because of this, we recommend using the other sample -dashboard above. - -[Alex Gervais]: https://twitter.com/alex_gervais -[$productName$ dashboard for Grafana]: https://grafana.com/dashboards/4698 -[envoy-statsd-prometheus]: ../envoy-statsd#using-prometheus-statsd-exporter-as-the-statsd-sink diff --git a/content/en/docs/3.0/topics/running/statistics/envoy-statsd.md b/content/en/docs/3.0/topics/running/statistics/envoy-statsd.md deleted file mode 100644 index 70795b50..00000000 --- a/content/en/docs/3.0/topics/running/statistics/envoy-statsd.md +++ /dev/null @@ -1,254 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Envoy statistics with StatsD - -> For an overview of other options for gathering statistics on -> $productName$, see the [Statistics and Monitoring](../) overview. - -At the core of $productName$ is [Envoy Proxy], which has built-in -support for exporting a multitude of statistics about its own -operations to StatsD (or to the modified DogStatsD used by Datadog). - -[Envoy Proxy]: https://www.envoyproxy.io - -If enabled, then $productName$ has Envoy expose this 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: - -```diff - spec: - containers: - - env: -+ - name: STATSD_ENABLED -+ value: "true" - - name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: -``` - -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. - -We have included a few example configurations in the -[`statsd-sink/`] directory to help you get started. Clone the -repository to get local, editable copies. - -[`statsd-sink/`]: https://github.com/emissary-ingress/emissary/tree/master/deployments/statsd-sink - -## Using Graphite as the StatsD sink - -[Graphite] is a web-based real-time graphing system. Spin up an -example Graphite setup: - -[Graphite]: http://graphite.readthedocs.org/ - -``` -kubectl apply -f statsd-sink/graphite/graphite-statsd-sink.yaml -``` - -This sets up the `statsd-sink` service and a deployment that contains -Graphite and its related infrastructure. Graphite's web interface is -available at `http://statsd-sink/` from within the cluster. Use port -forwarding to access the interface from your local machine: - -``` -SINKPOD=$(kubectl get pod -l service=statsd-sink -o jsonpath="{.items[0].metadata.name}") -kubectl port-forward $SINKPOD 8080:80 -``` - -This sets up Graphite access at `http://localhost:8080/`. - -## Using Prometheus StatsD Exporter as the StatsD sink - - - $productName$ $version$ has an endpoint that has exposes statistics in - a format that Prometheus understands natively. If you're using Prometheus, - we recommend configuring Prometheus to talk to  - the :8877/metrics endpoint  - directly, instead of instead of going through StatsD and a translator. - - -[Prometheus] is an open-source monitoring and alerting system. -Prometheus does not natively understand the StatsD protocol, but you -can deploy the [Prometheus StatsD Exporter] to act as the StatsD -sink, and it will translate from StatsD to the [exposition format] -that Prometheus requires. An example of how deploying Prometheus -StatsD Exporter is available in [`prom-statsd-sink.yaml`]. - -[Prometheus]: https://prometheus.io/ -[Prometheus StatsD Exporter]: https://github.com/prometheus/statsd_exporter -[exposition format]: https://prometheus.io/docs/instrumenting/exposition_formats/ -[`prom-statsd-sink.yaml`]: https://github.com/emissary-ingress/emissary/blob/master/deployments/statsd-sink/prometheus/prom-statsd-sink.yaml - -To finally get the statistics to Prometheus, you then configure a -Prometheus target to read from `statsd-sink` on port 9102. - -You could instead also add the `statsd-sink` service and Prometheus StatsD -Exporter as a sidecar on the $productName$ pod. If you do this, make -sure to set `STATSD_HOST=localhost` so that UDP packets are routed to -the sidecar. - -### Configuring how Prometheus StatsD Exporter translates from StatsD to the Prometheus format - -It may be desirable to change how metrics produced by the -`statsd-sink` are named, labeled and grouped when they finally make it -to Prometheus. - -For example, by default, each service that $productName$ serves will -create a new metric using its name. For the service called `usersvc` -you will see this metric -`envoy.cluster.usersvc_cluster.upstream_rq_total`. This may lead to -problems if you are trying to create a single aggregate that is the -sum of all similar metrics from different services. In this case, it -is common to differentiate the metrics for an individual service with -a `label`. This can be done by configuring a Prometheus StatsD -Exporter "mapping" (not to be confused with an [$productName$ -`Mapping`][Mappings]). See [Metric Mapping and Configuration] in -the Prometheus StatsD Exporter documentation to learn how to modify -its mappings. - -[Mappings]: ../../../using/mappings -[Metric Mapping and Configuration]: https://github.com/prometheus/statsd_exporter/#user-content-metric-mapping-and-configuration - -#### Configuring Prometheus StatsD Exporter with Helm - -If you deploy Prometheus using Helm the value that you should change -in order to add a mapping is `prometheusExporter.configuration`. Set -it to something like this: - -```yaml - configuration: | - --- - mappings: - - match: 'envoy.cluster.*.upstream_rq_total' - name: "envoy_cluster_upstream_rq_total" - timer_type: 'histogram' - labels: - cluster_name: "$1" -``` - -#### Configuring Prometheus StatsD Exporter in `prom-statsd-sink.yaml` - -If you are using the [`prom-statsd-sink.yaml`] example, edit its `ambassador-config` -ConfigMap with your Prometheus mappings, for example: - -```yaml ---- -apiVersion: v1 -kind: ConfigMap -metadata: - name: ambassador-config -data: - exporterConfiguration: | - --- - mappings: - - match: 'envoy.cluster.*.upstream_rq_total' - name: "envoy_cluster_upstream_rq_total" - timer_type: 'histogram' - labels: - cluster_name: "$1" -``` - -### Using the Prometheus Operator to configure Prometheus for use with the Prometheus StatsD Exporter - -If you don't already have a Prometheus setup, the [Prometheus -Operator] is a powerful way to create and deploy Prometheus -instances. Use the following YAML to quickly configure the Prometheus -Operator with $productName$: - -- [`statsd-sink.yaml`] Creates the Prometheus Stats Exporter - deployment and `statsd-sink` service that receives the statistics - from $productName$ and translates them to Prometheus metrics. It also - creates a `ServiceMonitor` resource that tells the Prometheus - Operator to configure Prometheus to fetch those metrics from the - StatsD Exporter. -- [`prometheus.yaml`] Deploys the Prometheus Operator and creates - `Prometheus` resource that tells the Prometheus Operator to create - the actual Prometheus deployment. - -[Prometheus operator]: https://github.com/coreos/prometheus-operator -[`statsd-sink.yaml`]: https://github.com/emissary-ingress/emissary/blob/master/deployments/statsd-sink/prometheus/statsd-sink.yaml -[`prometheus.yaml`]: https://github.com/emissary-ingress/emissary/blob/master/deployments/statsd-sink/prometheus/prometheus.yaml - -Make sure that the `ServiceMonitor` is in the same namespace as -$productName$. A walk-through of the basics of configuring the -Prometheus Operator with $productName$ is available -[here](http://www.datawire.io/faster/ambassador-prometheus/). - -Ensure `STATSD_ENABLED` is set to `"true"` and apply the YAML with -`kubectl`: - -``` -kubectl apply -f statsd-sink.yaml -kubectl apply -f prometheus.yaml -``` - -Wait for a minute after the pods spin up and then access the -Prometheus dashboard by port-forwarding the Prometheus pod and going -to `http://localhost:9090/` on a web-browser. - -``` -kubectl port-forward prometheus-prometheus-0 9090 -``` - -### Using Grafana to visualize statistics gathered by Prometheus -
-Screenshot of a Grafana dashboard that displays just information from Envoy - -If you're using Grafana, [Alex Gervais] has written a template -[$productName$ dashboard for Grafana] that works with either the -metrics exposed by the Prometheus StatsD Exporter, or by [the -`:8877/metrics` endpoint]. - -[Alex Gervais]: https://twitter.com/alex_gervais -[$productName$ dashboard for Grafana]: https://grafana.com/dashboards/4698 - -## Using Datadog DogStatsD as the StatsD sink - -If you are a user of the [Datadog] monitoring system, pulling in the -Envoy statistics from $productName$ is very easy. - -[Datadog]: https://www.datadoghq.com/ - -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: - -```diff - spec: - containers: - - env: -+ - name: STATSD_ENABLED -+ value: "true" -+ - name: DOGSTATSD -+ value: "true" - - name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: -``` - -Then, you will need to deploy the DogStatsD agent in to your cluster -to act as the StatsD sink. To do this, replace the sample API key in -our [sample YAML file][`dd-statsd-sink.yaml`] with your own, then -apply that YAML: - -[`dd-statsd-sink.yaml`]: https://github.com/emissary-ingress/emissary/blob/master/deployments/statsd-sink/datadog/dd-statsd-sink.yaml - -``` -kubectl apply -f statsd-sink/datadog/dd-statsd-sink.yaml -``` - -This sets up the `statsd-sink` service and a deployment of the -DogStatsD agent that forwards the $productName$ statistics to your -Datadog account. - -Additionally, $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). diff --git a/content/en/docs/3.0/topics/running/statistics/index.md b/content/en/docs/3.0/topics/running/statistics/index.md deleted file mode 100644 index 04033002..00000000 --- a/content/en/docs/3.0/topics/running/statistics/index.md +++ /dev/null @@ -1,79 +0,0 @@ -# Statistics and monitoring - -$productName$ collects many statistics internally, and makes it easy to -direct this information to a statistics and monitoring tool of your -choice. As an example, for a given service `usersvc`, here are some -interesting statistics to investigate: - -- `envoy.cluster.usersvc.upstream_rq_total` is the total - number of requests that `usersvc` has received via $productName$. The rate of change of this value is one basic measure of - service utilization, i.e. requests per second. -- `envoy.cluster.usersvc.upstream_rq_2xx` is the total number - of requests to which `usersvc` responded with an HTTP response - indicating success. This value divided by the prior one, taken on - an rolling window basis, represents the recent success rate of the - service. There are corresponding `4xx` and `5xx` counters that can - help clarify the nature of unsuccessful requests. -- `envoy.cluster.usersvc.upstream_rq_time` is a StatsD timer - that tracks the latency in milliseconds of `usersvc` from $productName$'s perspective. StatsD timers include information about - means, standard deviations, and decile values. - -## Overriding Statistics Names - -The optional `stats_name` element of every CRD that references a service (`Mapping`, `TCPMapping`, -`AuthService`, `LogService`, `RateLimitService`, and `TracingService`) can override the name under which cluster statistics -are logged (`usersvc` above). If not set, the default is the `service` value, with non-alphanumeric characters replaced by -underscores: - -- `service: foo` will just use `foo` -- `service: foo:8080` will use `foo_8080` -- `service: http://foo:8080` will use `http___foo_8080` -- `service: foo.othernamespace` will use `foo_othernamespace` - -The last example is worth special mention: a resource in a different namespace than the one in which $productName$ is running will automatically be qualified with the namespace of the resource itself. So, for example, if $productName$ is running in the `ambassador` namespace, and this `Mapping` is present in the `default` namespace: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: default-mapping - namespace: default -spec: - prefix: /default/ - service: default-service -``` - -then the `service` will be qualified to `default-service.default`, so the `stats_name` will be `default_service_default` rather than simply `default_service`. To change this behavior, set `stats_name` explicitly. - -## Monitoring Statistics - -There are several ways to get different statistics out of $productName$: - -- [The `:8877/metrics` endpoint](./8877-metrics) can be polled for - aggregated statistics (in a Prometheus-compatible format). This is - our recommended method. -- $productName$ can push [Envoy statistics](./envoy-statsd) over the - StatsD or DogStatsD protocol. -- $productName$ can push [RateLimiting - statistics](../environment) over the StatsD protocol. - -## The Four Golden Signals - -The [Four Golden Signals](https://sre.google/sre-book/monitoring-distributed-systems/) are four generally-accepted metrics -that are important to monitor for good information about service health: - -### Latency - -The time it takes to service a request. `cluster.$name.upstream_rq_time` is a histogram of time taken by individual requests, which can be an effective latency metric. - -### Traffic - -The amount of demand being placed on your system. `cluster.$name.upstream_rq_active` is a gauge that shows the number of active outstanding requests, which can be a good proxy for traffic. - -### Errors - -The number of failing requests. Some errors (e.g. a request succeeds, but gives the wrong answer) can only be detected by application-specific monitoring; however, many errors can be spotted simply by looking at the HTTP status code of requests. `cluster.$name.upstream_rq_5xx` is a counter of HTTP `5xx` responses, so monitoring it over time can show error rates. (Likewise, `cluster.$name.upstream_rq_4xx` exists.) - -### Saturation - -The hardest metric to measure, saturation describes how much of the total capability of the system to respond to requests is being used. Fully measuring saturation often requires application-specific monitoring, but looking at the 99th percentile of latency over a short window - perhaps a a minute - can often give an early indication of saturation problems. diff --git a/content/en/docs/3.0/topics/running/tls/cleartext-redirection.md b/content/en/docs/3.0/topics/running/tls/cleartext-redirection.md deleted file mode 100644 index c2ffb427..00000000 --- a/content/en/docs/3.0/topics/running/tls/cleartext-redirection.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -description: "Cleartext support - Emissary-ingress supports both forcing automatic redirection to HTTPS and serving cleartext traffic on a Host." ---- - -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`. - - - The 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. - - -## Cleartext Routing - -To allow cleartext to be routed, set the `requestPolicy.insecure.action` of a `Host` to `Route`: - -```yaml -requestPolicy: - insecure: - action: Redirect -``` - -This allows routing for either HTTP and HTTPS, or _only_ HTTP, depending on `tlsSecret` configuration: - -- If the `Host` does not specify a `tlsSecret`, it will only route HTTP, not terminating TLS at all. -- If the `Host` does specify a `tlsSecret`, it will route both HTTP and HTTPS. - - - The 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. - - -## HTTP->HTTPS redirection - -Most websites that force HTTPS will also automatically redirect any -requests that come into it over HTTP: - -``` -Client $productName$ -| | -| http:///api | -| --------------------------> | -| | -| 301: https:///api | -| <-------------------------- | -| | -| https:///api | -| --------------------------> | -| | -``` - -In $productName$, this is configured by setting the `insecure.action` in a `Host` to `Redirect`. - -```yaml -requestPolicy: - insecure: - action: Redirect -``` - -$productName$ determines which requests are secure and which are insecure using the -`securityModel` of the [`Listener`] that accepts the request. - -[`Listener`]: ../../listener - - - The 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. - diff --git a/content/en/docs/3.0/topics/running/tls/index.md b/content/en/docs/3.0/topics/running/tls/index.md deleted file mode 100644 index 93427bc5..00000000 --- a/content/en/docs/3.0/topics/running/tls/index.md +++ /dev/null @@ -1,465 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Transport Layer Security (TLS) - -$productName$'s robust TLS support exposes configuration options -for many different TLS use cases, using the [`Host`](#host) and -[`TLSContext`](#host-and-tlscontext) resources in concert. - -## Certificates and Secrets - -Properly-functioning TLS requires the use of [TLS certificates] to prove that the -various systems communicating are who they say they are. At minimum, $productName$ -must have a server certificate that identifies it to clients; when [mTLS] or -[client certificate authentication] are in use, additional certificates are needed. - -You supply certificates to $productName$ in Kubernetes [TLS Secrets]. These Secrets -_must_ contain valid X.509 certificates with valid PKCS1, PKCS8, or Elliptic Curve private -keys. If a Secret does not contain a valid certificate, an error message will be logged, for -example: - -``` -tls-broken-cert.default.1 2 errors:; 1. K8sSecret secret tls-broken-cert.default tls.key cannot be parsed as PKCS1 or PKCS8: asn1: syntax error: data truncated; 2. K8sSecret secret tls-broken-cert.default tls.crt cannot be parsed as x.509: x509: malformed certificate -``` - -If you set the `AMBASSADOR_FORCE_SECRET_VALIDATION` environment variable, the invalid -Secret will be rejected, and a `Host` or `TLSContext` resource attempting to use an invalid -certificate will be disabled entirely. **Note** that in $productName$ $version$, this -includes disabling cleartext communication for such a `Host`. - -[TLS Certificates]: https://protonmail.com/blog/tls-ssl-certificate/ -[mTLS]: mtls -[client certificate authentication]: ../../../howtos/client-cert-validation/ -[TLS Secrets]: https://kubernetes.io/docs/concepts/configuration/secret/#tls-secrets - -## `Host` - -A `Host` represents a domain in $productName$ and defines how the domain manages TLS. For more information on the Host resource, see [The Host CRD reference documentation](../host-crd). - -**If no `Host`s are present**, $productName$ synthesizes a `Host` that -allows only cleartext routing. You will need to explictly define `Host`s to enable -TLS termination. - - - The examples below do not define a requestPolicy; however, most real-world - usage of $productName$ will require defining the requestPolicy.
-
- For more information, please refer to the Host documentation. - - -### Bring your own certificate - -The `Host` can read a certificate from a Kubernetes Secret and use that certificate -to terminate TLS on a domain. - -The following example shows the certificate contained in the Kubernetes Secret named -`host-secret` configured to have $productName$ terminate TLS on the `host.example.com` -domain: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: host-secret -``` - - - - The Kubernetes Secret named by 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. - - - -### Advanced TLS configuration with the `Host` - -You can specify TLS configuration directly in the `Host` via the `tls` field. This is the -recommended method to do more advanced TLS configuration for a single `Host`. - -For example, the configuration to enforce a minimum TLS version on the `Host` looks as follows: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: min-secret - tls: - min_tls_version: v1.2 -``` - - - - The Kubernetes Secret named by 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. - - - -The following fields are accepted in the `tls` field: -```yaml -tls: - cert_chain_file: # string - private_key_file: # string - ca_secret: # string - cacert_chain_file: # string - alpn_protocols: # string - cert_required: # bool - min_tls_version: # string - max_tls_version: # string - cipher_suites: # array of strings - ecdh_curves: # array of strings - sni: # string - crl_secret: # string -``` - -These fields have the same function as in the [`TLSContext`](#tlscontext) resource, -as described below. - -### `Host` and `TLSContext` - -You can link a `Host` to a [`TLSContext`](#tlscontext) instead of defining `tls` -settings in the `Host` itself. This is primarily useful for sharing settings between -multiple `Host`s. - -#### Link a `TLSContext` to the `Host` - - - It is invalid to use both the 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. - - -To link a [`TLSContext`](#tlscontext) with a `Host`, create a [`TLSContext`](#tlscontext) -with the desired configuration and link it to the `Host` by setting the `tlsContext.name` -field in the `Host`. For example, to enforce a minimum TLS version on the `Host` above, -create a `TLSContext` with any name with the following configuration: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: min-tls-context -spec: - hosts: - - host.example.com - secret: min-secret - min_tls_version: v1.2 -``` - -Next, link it to the `Host` via the `tlsContext` field as shown: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: min-secret - tlsContext: - name: min-tls-context -``` - - - - The `Host` and the `TLSContext` must name the same Kubernetes Secret; if not, - $productName$ will disable TLS for the `Host`. - - - - - - The Kubernetes Secret named by 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. - - - - - - The `Host`'s `hostname` and the `TLSContext`'s `hosts` must have compatible settings. If - they do not, requests may not be accepted. - - - -See [`TLSContext`](#tlscontext) below to read more on the description of these fields. - -#### Create a `TLSContext` with the name `{{AMBASSADORHOST}}-context` (DEPRECATED) - - - This implicit 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. - - -The `Host` will implicitly link to the `TLSContext` when a `TLSContext` exists with the following: - -- the name `{{NAME_OF_AMBASSADORHOST}}-context` -- `hosts` in the `TLSContext` set to the same value as `hostname` in the `Host`, and -- `secret` in the `TLSContext` set to the same value as `tlsSecret` in the `Host` - -**As noted above, this implicit linking is deprecated.** - -For example, another way to enforce a minimum TLS version on the `Host` above would -be to simply create the `TLSContext` with the name `example-host-context` and then not modify the `Host`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-host-context -spec: - hosts: - - host.example.com - secret: host-secret - min_tls_version: v1.2 -``` - - - - The `Host` and the `TLSContext` must name the same Kubernetes Secret; if not, - $productName$ will disable TLS for the `Host`. - - - - - - The Kubernetes Secret named by 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. - - - - - - The `Host`'s `hostname` and the `TLSContext`'s `hosts` must have compatible settings. If - they do not, requests may not be accepted. - - - -Full reference for all options available to the `TLSContext` can be found [below](#tlscontext). - -## TLSContext - -The `TLSContext` is used to configure advanced TLS options in $productName$. -Remember, a `TLSContext` must always be paired with a `Host`. - -A full schema of the `TLSContext` can be found below with descriptions of the -different configuration options. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-host-context -spec: - # 'hosts' defines the hosts for which this TLSContext is relevant. - # It ties into SNI. A TLSContext without "hosts" is useful only for - # originating TLS. - # type: array of strings - # - # hosts: [] - - # 'sni' defines the SNI string to use on originated connections. - # type: string - # - # sni: None - - # 'secret' defines a Kubernetes Secret that contains the TLS certificate we - # use for origination or termination. If not specified, $productName$ will look - # at the value of cert_chain_file and private_key_file. - # type: string - # - # secret: None - - # 'ca_secret' defines a Kubernetes Secret that contains the TLS certificate we - # use for verifying incoming TLS client certificates. - # type: string - # - # ca_secret: None - - # Tells $productName$ whether to interpret a "." in the secret name as a "." or - # a namespace identifier. - # type: boolean - # - # secret_namespacing: true - - # 'cert_required' can be set to true to _require_ TLS client certificate - # authentication. - # type: boolean - # - # cert_required: false - - # 'alpn_protocols' is used to enable the TLS ALPN protocol. It is required - # if you want to do GRPC over TLS; typically it will be set to "h2" for that - # case. - # type: string (comma-separated list) - # - # alpn_protocols: None - - # 'min_tls_version' sets the minimum acceptable TLS version: v1.0, v1.1, - # v1.2, or v1.3. It defaults to v1.0. - # min_tls_version: v1.0 - - # 'max_tls_version' sets the maximum acceptable TLS version: v1.0, v1.1, - # v1.2, or v1.3. It defaults to v1.3. - # max_tls_version: v1.3 - - # Tells $productName$ to load TLS certificates from a file in its container. - # type: string - # - # cert_chain_file: None - # private_key_file: None - # cacert_chain_file: None -``` - - - - `secret` and (if used) `ca_secret` must specify Kubernetes Secrets containing valid TLS - certificates. If `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and either Secret contains - an invalid certificate, $productName$ will reject the Secret, which will also completely - disable any `Host` using the `TLSContext`; see [**Certificates and Secrets**](#certificates-and-secrets) - above. - - - -### ALPN protocols - -The `alpn_protocols` setting configures the TLS ALPN protocol. To use gRPC over -TLS, set `alpn_protocols: h2`. If you need to support HTTP/2 upgrade from -HTTP/1, set `alpn_protocols: h2,http/1.1` in the configuration. - -#### HTTP/2 support - -The `alpn_protocols` setting is also required for HTTP/2 support. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls -spec: - secret: ambassador-certs - hosts: ["*"] - alpn_protocols: h2[, http/1.1] -``` -Without setting alpn_protocols as shown above, HTTP2 will not be available via -negotiation and will have to be explicitly requested by the client. - -If you leave off http/1.1, only HTTP2 connections will be supported. - -### TLS parameters - -The `min_tls_version` setting configures the minimum TLS protocol version that -$productName$ will use to establish a secure connection. When a client -using a lower version attempts to connect to the server, the handshake will -result in the following error: `tls: protocol version not supported`. - -The `max_tls_version` setting configures the maximum TLS protocol version that -$productName$ will use to establish a secure connection. When a client -using a higher version attempts to connect to the server, the handshake will -result in the following error: -`tls: server selected unsupported protocol version`. - -The `cipher_suites` setting configures the supported ciphers found below using the -[configuration parameters for BoringSSL](https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#Cipher-suite-configuration) when negotiating a TLS 1.0-1.2 connection. -This setting has no effect when negotiating a TLS 1.3 connection. When a client does not -support a matching cipher a handshake error will result. - -The `ecdh_curves` setting configures the supported ECDH curves when negotiating -a TLS connection. When a client does not support a matching ECDH a handshake -error will result. - -``` - - AES128-SHA - - AES256-SHA - - AES128-GCM-SHA256 - - AES256-GCM-SHA384 - - ECDHE-RSA-AES128-SHA - - ECDHE-RSA-AES256-SHA - - ECDHE-RSA-AES128-GCM-SHA256 - - ECDHE-RSA-AES256-GCM-SHA384 - - ECDHE-RSA-CHACHA20-POLY1305 - - ECDHE-ECDSA-AES128-SHA - - ECDHE-ECDSA-AES256-SHA - - ECDHE-ECDSA-AES128-GCM-SHA256 - - ECDHE-ECDSA-AES256-GCM-SHA384 - - ECDHE-ECDSA-CHACHA20-POLY1305 - - ECDHE-PSK-AES128-CBC-SHA - - ECDHE-PSK-AES256-CBC-SHA - - ECDHE-PSK-CHACHA20-POLY1305 - - PSK-AES128-CBC-SHA - - PSK-AES256-CBC-SHA - - DES-CBC3-SHA -``` - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls -spec: - hosts: ["*"] - secret: ambassador-certs - min_tls_version: v1.0 - max_tls_version: v1.3 - cipher_suites: - - "[ECDHE-ECDSA-AES128-GCM-SHA256|ECDHE-ECDSA-CHACHA20-POLY1305]" - - "[ECDHE-RSA-AES128-GCM-SHA256|ECDHE-RSA-CHACHA20-POLY1305]" - ecdh_curves: - - X25519 - - P-256 -``` - - -The `crl_secret` field allows you to reference a Kubernetes Secret that contains a certificate revocation list. -If specified, $productName$ will verify that the presented peer certificate has not been revoked by this CRL even if they are otherwise valid. This provides a way to reject certificates before they expire or if they become compromised. -The `crl_secret` field takes a PEM-formatted [Certificate Revocation List](https://en.wikipedia.org/wiki/Certificate_revocation_list) in a `crl.pem` entry. - -Note that if a CRL is provided for any certificate authority in a trust chain, a CRL must be provided for all certificate authorities in that chain. Failure to do so will result in verification failure for both revoked and unrevoked certificates from that chain. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls-crl -spec: - hosts: ["*"] - secret: ambassador-certs - min_tls_version: v1.0 - max_tls_version: v1.3 - crl_secret: 'ambassador-crl' ---- -apiVersion: v1 -kind: Secret -metadata: - name: ambassador-crl - namespace: ambassador -type: Opaque -data: - crl.pem: | - {BASE64 CRL CONTENTS} ---- -``` diff --git a/content/en/docs/3.0/topics/running/tls/mtls.md b/content/en/docs/3.0/topics/running/tls/mtls.md deleted file mode 100644 index 1b039cf8..00000000 --- a/content/en/docs/3.0/topics/running/tls/mtls.md +++ /dev/null @@ -1,88 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Mutual TLS (mTLS) - -Many organizations have security concerns that require all network traffic -throughout their cluster be encrypted. With traditional architectures, -this was not that complicated of a requirement since internal network traffic -was fairly minimal. With microservices, we are making many more requests over -the network that must all be authenticated and secured. - -In order for services to authenticate with each other, they will each need to -provide a certificate and key that the other trusts before establishing a -connection. This action of both the client and server providing and validating -certificates is referred to as mutual TLS. - -## mTLS with $productName$ - -Since $productName$ is a reverse proxy acting as the entry point to your cluster, -$productName$ is acting as the client as it proxies requests to services upstream. - -It is trivial to configure $productName$ to simply originate TLS connections as -the client to upstream services by setting -`service: https://{{UPSTREAM_SERVICE}}` in the `Mapping` configuration. -However, in order to do mTLS with services upstream, $productName$ must also -have certificates to authenticate itself with the service. - -To do this, we can use the `TLSContext` object to get certificates from a -Kubernetes `Secret` and use those to authenticate with the upstream service. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: upstream-context -spec: - hosts: [] - secret: upstream-certs -``` - -We use `hosts: []` for this `TLSContext` since we do not want to use it to terminate -TLS connections from the client. We are just using this to load certificates for -requests upstream. - - - - The Kubernetes Secret must contain a valid TLS certificate. If the environment - variable `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) in the TLS overview. - - - -After loading the certificates, we can tell $productName$ when to use them by -setting the `tls` parameter in a `Mapping`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: upstream-mapping -spec: - hostname: "*" - prefix: /upstream/ - service: upstream-service - tls: upstream-context -``` - -Now, when $productName$ proxies a request to `upstream-service`, it will provide -the certificates in the `upstream-certs` secret for authentication when -encrypting traffic. - -## Service mesh - -As you can imagine, when you have many services in your cluster all -authenticating with each other, managing all of those certificates can become a -very big challenge. - -For this reason, many organizations rely on a service mesh for their -service-to-service authentication and encryption. - -$productName$ integrates with multiple service meshes and makes it easy to -configure mTLS to upstream services for all of them. Click the links below to -see how to configure $productName$ to do mTLS with any of these service meshes: - -- [Consul Connect](../../../../howtos/consul/) - -- [Istio](../../../../howtos/istio/) diff --git a/content/en/docs/3.0/topics/running/tls/origination.md b/content/en/docs/3.0/topics/running/tls/origination.md deleted file mode 100644 index b15dd5f8..00000000 --- a/content/en/docs/3.0/topics/running/tls/origination.md +++ /dev/null @@ -1,82 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# TLS origination - -Sometimes you may want traffic from $productName$ to your services to be encrypted. For the cases where terminating TLS at the ingress is not enough, $productName$ can be configured to originate TLS connections to your upstream services. - -## Basic configuration - -Telling $productName$ to talk to your services over HTTPS is easily configured in the `Mapping` definition by setting `https://` in the `service` field. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: basic-tls -spec: - hostname: "*" - prefix: / - service: https://example-service -``` - -## Advanced configuration using a `TLSContext` - -If your upstream services require more than basic HTTPS support (for example, providing a client certificate or -setting the minimum TLS version support) you must create a `TLSContext` for $productName$ to use when -originating TLS. For example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls-context -spec: - secret: self-signed-cert - min_tls_version: v1.3 - sni: some-sni-hostname -``` - - - - The Kubernetes Secret named by `secret` must contain a valid TLS certificate. If the - environment variable `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and the Secret contains - an invalid certificate, $productName$ will reject the `TLSContext` and prevent its use; - see [**Certificates and Secrets**](../#certificates-and-secrets) in the TLS overview. - - - -Configure $productName$ to use this `TLSContext` for connections to upstream services by setting the `tls` attribute of a `Mapping`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-with-tls-context -spec: - hostname: "*" - prefix: / - service: https://example-service - tls: tls-context -``` - -The `example-service` service must now support TLS v1.3 for $productName$ to connect. - - - - The Kubernetes Secret named by `secret` must contain a valid TLS certificate. If the - environment variable `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and the Secret contains - an invalid certificate, $productName$ will reject the `TLSContext` and prevent its use; - see [**Certificates and Secrets**](../#certificates-and-secrets) in the TLS overview. - - - - - - A `TLSContext` requires a certificate be provided, even in cases where the upstream - service does not require it (for origination) and the `TLSContext` is not being used - to terminate TLS. In this case, simply generate and provide a self-signed certificate. - - diff --git a/content/en/docs/3.0/topics/running/tls/sni.md b/content/en/docs/3.0/topics/running/tls/sni.md deleted file mode 100644 index 92e4992f..00000000 --- a/content/en/docs/3.0/topics/running/tls/sni.md +++ /dev/null @@ -1,103 +0,0 @@ -# Server Name Indication (SNI) - -$productName$ supports serving multiple `Host`s behind a single IP address, each -with their own certificate. - -This is as easy to do as creating a `Host` for each domain or subdomain you -want $productName$ to serve, getting a certificate for each, and telling -$productName$ which `Host` the route should be created for. - -The example below configures two `Host`s and assigns routes to them. - -## Configuring a `Host` - -The `Host` resources lets you separate configuration for each distinct domain -and subdomain you plan on serving behind $productName$. - -Let's start by creating a simple `Host` and providing our own certificate in -the `host-cert` secret. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: host-cert -``` - -Now let's create a second `Host` for a different domain we want to serve behind -$productName$. This second `Host` uses $AESproductName$'s automatic TLS -to get a certificate from Let's Encrypt. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: host.foo.com - acmeProvider: - email: julian@example.com -``` - -We now have two `Host`s with two different certificates. - - - A minimum version of TLS 1.1 is required to properly use SNI. When setting up your TLS configuration, be sure you are not using TLS 1.0 or older. - - -## Configuring routes - -Now that we have two domains behind $productName$, we can create routes for either -or both of them. - -We do this by setting the `hostname` attribute of a `Mapping` to the domain the -`Mapping` should be created for. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin -spec: - prefix: /httpbin/ - service: httpbin.org:80 - host_rewrite: httpbin.org - hostname: host.example.com -``` - -The above creates a `/httpbin/` endpoint for `host.example.com`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mockbin -spec: - prefix: /foo/ - service: foo-service - hostname: host.foo.com -``` - -The above creates a `/foo/` endpoint for `host.foo.com`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: frontend -spec: - hostname: "*" - prefix: /bar/ - service: bar-endpoint -``` - -The above creates a `/bar/` endpoint for all `Host`s. diff --git a/content/en/docs/3.0/topics/using/authservice.md b/content/en/docs/3.0/topics/using/authservice.md deleted file mode 100644 index 9bc2630f..00000000 --- a/content/en/docs/3.0/topics/using/authservice.md +++ /dev/null @@ -1,24 +0,0 @@ -# AuthService settings - -A Mapping can pass these settings along to an [AuthService](../../running/services/auth-service). This is helpful to allow these specific configurations to apply only to certain Mappings and not globally. - -## Bypass authentication - -An AuthService can be disabled for a specific Mapping with the `bypass_auth` attribute. This will tell $productName$ to allow all requests for that Mapping through without interacting with the external auth service. This could be helpful, for example, for a public API. - -```yaml -bypass_auth: true -``` - -## Context extensions (gRPC only) - -The `auth_context_extensions` attribute will pass the given values along to the AuthService when authentication happens. This is only supported when the `proto` of the AuthService is `grpc`, which is a restriction of the underlying Envoy implementation. -The values are arbitrary key value pairs formatted as strings. - -```yaml -auth_context_extensions: - foo: bar - baz: zing -``` - -More information is available on [the Envoy documentation on external authentication](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto.html#extensions-filters-http-ext-authz-v3-checksettings). diff --git a/content/en/docs/3.0/topics/using/canary.md b/content/en/docs/3.0/topics/using/canary.md deleted file mode 100644 index f99de1a3..00000000 --- a/content/en/docs/3.0/topics/using/canary.md +++ /dev/null @@ -1,41 +0,0 @@ -# Canary releases - -Canary releasing is a deployment pattern where a small percentage of traffic is diverted to an early ("canary") release of a particular service. This technique lets you test a release on a small subset of users, mitigating the impact of any given bug. Canary releasing also allows you to quickly roll back to a known good version in the event of an unexpected error. Detailed monitoring of core service metrics is an essential part of canary releasing, as monitoring enables the rapid detection of problems in the canary release. - -## Canary releases in Kubernetes - -Kubernetes supports a basic canary release workflow using its core objects. In this workflow, a service owner can create a Kubernetes [service](https://kubernetes.io/docs/concepts/services-networking/service/). This service can then be pointed to multiple [deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/). Each deployment can be a different version. By specifying the number of `replicas` in a given deployment, you can control how much traffic goes between different versions. For example, you could set `replicas: 3` for `v1`, and `replicas: 1` for `v2`, to ensure that 25% of traffic goes to `v2`. This approach works but is fairly coarse-grained unless you have lots of replicas. Moreover, auto-scaling doesn't work well with this strategy. - -## Canary releases in $productName$ - -$productName$ supports fine-grained canary releases. $productName$ uses a weighted round-robin scheme to route traffic between multiple services. Full metrics are collected for all services, making it easy to compare the relative performance of the canary and production. - -### The weight attribute - -The `weight` attribute specifies how much traffic for a given resource will be routed using a given mapping. Its value is an integer percentage between 0 and 100. $productName$ will balance weights to make sure that, for every resource, the mappings for that resource will have weights adding to 100%. (In the simplest case, a single mapping is guaranteed to receive 100% of the traffic no matter whether it's assigned a `weight` or not.) - -Specifying a weight only makes sense if you have multiple mappings for the same resource, and typically you would _not_ assign a weight to the "default" mapping (the mapping expected to handle most traffic): letting $productName$ assign that mapping all the traffic not otherwise spoken for tends to make life easier when updating weights. - -Here's an example, which might appear during a canary deployment: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - prefix: /backend/ - service: quotev2 - weight: 10 -``` - -In this case, the quote-backend2 will receive 10% of the requests for `/backend/`, and $productName$ will assign the remaining 90% to the quote-backend. diff --git a/content/en/docs/3.0/topics/using/circuit-breakers.md b/content/en/docs/3.0/topics/using/circuit-breakers.md deleted file mode 100644 index 97b40f57..00000000 --- a/content/en/docs/3.0/topics/using/circuit-breakers.md +++ /dev/null @@ -1,116 +0,0 @@ -# Circuit breakers - -Circuit breakers are a powerful technique to improve resilience. By preventing additional connections or requests to an overloaded service, circuit breakers limit the ["blast radius"](https://www.ibm.com/garage/method/practices/manage/practice_limited_blast_radius/) of an overloaded service. By design, $productName$ circuit breakers are distributed, i.e., different $productName$ instances do not coordinate circuit breaker information. - -## Circuit breaker configuration - -A default circuit breaking configuration can be set for all -$productName$ resources in the [`ambassador -Module`](../../running/ambassador), or set to a different value on a -per-resource basis for [`Mappings`](../mappings), -[`TCPMappings`](../tcpmappings/), and -[`AuthServices`](../../running/services/auth-service/). - -The `circuit_breakers` attribute configures circuit breaking. The following fields are supported: - -```yaml -circuit_breakers: -- priority: - max_connections: - max_pending_requests: - max_requests: - max_retries: -``` - -|Key|Default value|Description| -|---|---|---| -|`priority`|`default`|Specifies the priority to which the circuit breaker settings apply to; it can be set to either `default` or `high`.| -|`max_connections`|`1024`|Specifies the maximum number of connections that $productName$ will make to the services. In practice, this is more applicable to HTTP/1.1 than HTTP/2.| -|`max_pending_requests`|`1024`|Specifies the maximum number of requests that will be queued while waiting for a connection. In practice, this is more applicable to HTTP/1.1 than HTTP/2.| -|`max_requests`|`1024`|Specifies the maximum number of parallel outstanding requests to an upstream service. In practice, this is more applicable to HTTP/2 than HTTP/1.1.| -|`max_retries`|`3`|Specifies the maximum number of parallel retries allowed to an upstream service.| - -The `max_*` fields can be reduced to shrink the "blast radius," or -increased to enable $productName$ to handle a larger number of -concurrent requests. - -## Examples - -Circuit breakers defined on a single `Mapping`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - circuit_breakers: - - max_connections: 2048 - max_pending_requests: 2048 -``` - -Circuit breakers defined on a single `AuthService`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: AuthService -metadata: - name: dancing-walrus -spec: - auth_service: http://dancing-walrus:8500 - proto: grpc - circuit_breakers: - - max_requests: 4096 -``` - -A global circuit breaker: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - circuit_breakers: - - max_connections: 2048 - max_pending_requests: 2048 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote -``` - -## Circuit breakers and automatic retries - -Circuit breakers are best used in conjunction with [automatic retries](../retries). Here are some examples: - -* You've configured automatic retries for failed requests to a service. Your service is under heavy load, and starting to time out on servicing requests. In this case, automatic retries can exacerbate your problem, increasing the total request volume by 2x or more. By aggressively circuit breaking, you can mitigate failure in this scenario. -* To circuit break when services are slow, you can combine circuit breakers with retries. Reduce the time out for retries, and then set a circuit breaker that detects many retries. In this setup, if your service doesn't respond quickly, a flood of retries will occur, which can then trip the circuit breaker. - -Note that setting circuit breaker thresholds requires careful monitoring and experimentation. We recommend you start with conservative values for circuit breakers and adjust them over time. - -## More about circuit breakers - -Responses from a broken circuit contain the `x-envoy-overloaded` header. - -The following are the default values for circuit breaking if nothing is specified: - -```yaml -circuit_breakers: -- priority: default - max_connections: 1024 - max_pending_requests: 1024 - max_requests: 1024 - max_retries: 3 -``` - -Circuit breaker metrics are exposed in StatsD. For more information about the specific statistics, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/circuit_breaking.html). diff --git a/content/en/docs/3.0/topics/using/cors.md b/content/en/docs/3.0/topics/using/cors.md deleted file mode 100644 index 315e4694..00000000 --- a/content/en/docs/3.0/topics/using/cors.md +++ /dev/null @@ -1,155 +0,0 @@ -# Cross-Origin Resource Sharing (CORS) - -Cross-Origin resource sharing lets users request resources (e.g., images, fonts, videos) from domains outside the original domain. - -CORS configuration can be set for all $productName$ mappings in the [`ambassador Module`](../../running/ambassador), or set per [`Mapping`](../mappings). - -When the CORS attribute is set at either the `Mapping` or `Module` level, $productName$ will intercept the pre-flight `OPTIONS` request and respond with the appropriate CORS headers. This means you will not need to implement any logic in your upstreams to handle these CORS `OPTIONS` requests. - -The flow of the request will look similar to the following: -``` -Client $productName$ Upstream - | OPTIONS | | - | —————————————————> | | - | CORS_RESP | | - | <————————————————— | | - | GET /foo/ | | - | —————————————————> | ————————————> | - | | RESP | - | <————————————————————————————————— | -``` -## The `cors` attribute - -The `cors` attribute enables the CORS filter. The following settings are supported: - -- `origins`: Specifies a list of allowed domains for the `Access-Control-Allow-Origin` header. To allow all origins, use the wildcard `"*"` value. Format can be either of: - - comma-separated list, e.g. - ```yaml - origins: http://foo.example,http://bar.example - ``` - - YAML array, e.g. - ```yaml - origins: - - http://foo.example - - http://bar.example - ``` - -- `methods`: if present, specifies a list of allowed methods for the `Access-Control-Allow-Methods` header. Format can be either of: - - comma-separated list, e.g. - ```yaml - methods: POST, GET, OPTIONS - ``` - - YAML array, e.g. - ```yaml - methods: - - GET - - POST - - OPTIONS - ``` - -- `headers`: if present, specifies a list of allowed headers for the `Access-Control-Allow-Headers` header. Format can be either of: - - comma-separated list, e.g. - ```yaml - headers: Content-Type - ``` - - YAML array, e.g. - ```yaml - headers: - - Content-Type - ``` - -- `credentials`: if present with a true value (boolean), will send a `true` value for the `Access-Control-Allow-Credentials` header. - -- `exposed_headers`: if present, specifies a list of allowed headers for the `Access-Control-Expose-Headers` header. Format can be either of: - - comma-separated list, e.g. - ```yaml - exposed_headers: X-Custom-Header - ``` - - YAML array, e.g. - ```yaml - exposed_headers: - - X-Custom-Header - ``` - -- `max_age`: if present, indicated how long the results of the preflight request can be cached, in seconds. This value must be a string. - -## Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cors -spec: - prefix: /cors/ - service: cors-example - cors: - origins: http://foo.example,http://bar.example - methods: POST, GET, OPTIONS - headers: Content-Type - credentials: true - exposed_headers: X-Custom-Header - max_age: "86400" -``` - -## AuthService and Cross-Origin Resource Sharing - -When you use external authorization, each incoming request is authenticated before routing to its destination, including pre-flight `OPTIONS` requests. - -By default, many [`AuthService`](../../running/services/auth-service) implementations will deny these requests. If this is the case, you will need to add some logic to your `AuthService` to accept all CORS headers. - -For example, a possible configuration for Spring Boot 2.0.1: - -```java -@EnableWebSecurity -class SecurityConfig extends WebSecurityConfigurerAdapter { - - public void configure(final HttpSecurity http) throws Exception { - http - .cors().configurationSource(new PermissiveCorsConfigurationSource()).and() - .csrf().disable() - .authorizeRequests() - .antMatchers("**").permitAll(); - } - - private static class PermissiveCorsConfigurationSource implements CorsConfigurationSource { - /** - * Return a {@link CorsConfiguration} based on the incoming request. - * - * @param request - * @return the associated {@link CorsConfiguration}, or {@code null} if none - */ - @Override - public CorsConfiguration getCorsConfiguration(final HttpServletRequest request) { - final CorsConfiguration configuration = new CorsConfiguration(); - configuration.setAllowCredentials(true); - configuration.setAllowedHeaders(Collections.singletonList("*")); - configuration.setAllowedMethods(Collections.singletonList("*")); - configuration.setAllowedOrigins(Collections.singletonList("*")); - return configuration; - } - } -} -``` - -This is okay since CORS is being handled by $productName$ after authentication. - -The flow of this request will look similar to the following: - -``` -Client $productName$ Auth Upstream - | OPTIONS | | | - | —————————————————> | ————————————> | | - | | CORS_ACCEPT_* | | - | CORS_RESP |<——————————————| | - | <——————————————————| | | - | GET /foo/ | | | - | —————————————————> | ————————————> | | - | | AUTH_RESP | | - | | <———————————— | | - | | AUTH_ALLOW | | - | | ————————————————————————————> | - | | | RESP | - | <————————————————————————————————————————————————— | - ``` diff --git a/content/en/docs/3.0/topics/using/defaults.md b/content/en/docs/3.0/topics/using/defaults.md deleted file mode 100644 index 673a08be..00000000 --- a/content/en/docs/3.0/topics/using/defaults.md +++ /dev/null @@ -1,32 +0,0 @@ -# Using `ambassador` `Module` defaults - -## The defaults element - -If present, the `ambassador Module` can define a set of defaults that will automatically be applied to certain resources: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - class1: # This is a class. Different resource types will look in different classes. - key1: value1 # Within a class, you can set different keys. - key2: value2 - ... - class2: - ... - top_key1: value1 # If a key isn't found in a resource's class, the system will look in the - top_key2: value2 # toplevel defaults dictionary for it. -``` - -### Mapping - -Currently, only the `Mapping` resource uses the `defaults` mechanism. `Mapping` looks first for defaultable resources in the `httpmapping` class, including: - -- [`add_request_headers`](../../using/headers/add_request_headers) -- [`add_response_headers`](../../using/headers/add_response_headers) -- [`remove_request_headers`](../../using/headers/remove_request_headers) -- [`remove_response_headers`](../../using/headers/remove_response_headers) diff --git a/content/en/docs/3.0/topics/using/gateway-api.md b/content/en/docs/3.0/topics/using/gateway-api.md deleted file mode 100644 index 5e92cd0d..00000000 --- a/content/en/docs/3.0/topics/using/gateway-api.md +++ /dev/null @@ -1,19 +0,0 @@ -# Gateway API - -## Using the Gateway API - -$productName$ now supports a limited subset of the new `v1alpha1` [Gateway API](https://gateway-api.sigs.k8s.io/). -Note that the Gateway API is not supported when `AMBASSADOR_LEGACY_MODE` is set. - -Support is currently limited to the following fields, however this will expand in future releases: - - - `Gateway.spec.listeners.port` - - `HTTPRoute.spec.rules.matches.path.type` (`Exact`, `Prefix`, and `RegularExpression`) - - `HTTPRoute.spec.rules.matches.path.value` - - `HTTPRoute.spec.rules.matches.header.type` (`Exact` and `RegularExpression`) - - `HTTPRoute.spec.rules.matches.header.values` - - `HTTPRoute.spec.rules.forwardTo.serviceName` - - `HTTPRoute.spec.rules.forwardTo.port` - - `HTTPRoute.spec.rules.forwardTo.weight` - -Please see the [specification](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/) for more details. diff --git a/content/en/docs/3.0/topics/using/headers/add_request_headers.md b/content/en/docs/3.0/topics/using/headers/add_request_headers.md deleted file mode 100644 index c6ad4956..00000000 --- a/content/en/docs/3.0/topics/using/headers/add_request_headers.md +++ /dev/null @@ -1,77 +0,0 @@ -# Add request headers - -$productName$ can add a dictionary of HTTP headers that can be added to each request that is passed to a service. - -## The `add_request_headers` attribute - -The `add_request_headers` attribute is a dictionary of `header`: `value` pairs. The `value` can be a `string`, `bool` or `object`. When it is an `object`, the object should have a `value` property, which is the actual header value, and the remaining attributes are additional envoy properties. - -Envoy dynamic values `%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%` and `%PROTOCOL%` are supported, in addition to static values. - -`add_request_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -### Mapping example - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: "*" - prefix: /backend/ - add_request_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-static-2: - value: This the test header #same as above "x-test-static header" - x-test-object: - value: This the value - append: False #True by default - service: quote - ``` - -will add the protocol, client IP, and a static header to `/backend/`. - -### Defaults example - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - add_request_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-static-2: - value: This the test header #same as above "x-test-static header" - x-test-object: - value: This the value - append: False #True by default ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - hostname: "*" - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - hostname: "*" - prefix: /backend2/ - service: quote -``` - -This example will add the same headers for both mappings. diff --git a/content/en/docs/3.0/topics/using/headers/add_response_headers.md b/content/en/docs/3.0/topics/using/headers/add_response_headers.md deleted file mode 100644 index 236ace61..00000000 --- a/content/en/docs/3.0/topics/using/headers/add_response_headers.md +++ /dev/null @@ -1,73 +0,0 @@ -# Add response headers - -$productName$ can add a dictionary of HTTP headers that can be added to each response that is returned to the client. - -## The `add_response_headers` attribute - -The `add_response_headers` attribute is a dictionary of `header`: `value` pairs. The `value` can be a `string`, `bool` or `object`. When it is an `object`, the object should have a `value` property, which is the actual header value, and the remaining attributes are additional envoy properties. - -Envoy dynamic values `%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%` and `%PROTOCOL%` are supported, in addition to static values. - -`add_response_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -### Mapping example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - add_response_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-object: - append: False - value: this is from object header config - service: quote -``` - -will add the protocol, client IP, and a static header to the response returned to the client. - -### Defaults example - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - add_response_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-object: - append: False - value: this is from object header config ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - hostname: "*" - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - hostname: "*" - prefix: /backend2/ - service: quote -``` - -This example will add the same headers for both mappings. diff --git a/content/en/docs/3.0/topics/using/headers/headers.md b/content/en/docs/3.0/topics/using/headers/headers.md deleted file mode 100644 index 126653b0..00000000 --- a/content/en/docs/3.0/topics/using/headers/headers.md +++ /dev/null @@ -1,76 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Header-based routing - -$productName$ can route to target services based on HTTP headers with the `headers` and `regex_headers` specifications. Multiple mappings with different annotations can be applied to construct more complex routing rules. - -## The `headers` annotation - -The `headers` attribute is a dictionary of `header`: `value` pairs. $productName$ will only allow requests that match the specified `header`: `value` pairs to reach the target service. - -### Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - headers: - x-quote-mode: backend - x-random-header: datawire -``` - -will allow requests to /backend/ to succeed only if the x-quote-mode header has the value backend and the x-random-header has the value `datawire`. - - - 1.x versions of the Ambassador Edge Stack could test for the existence of a header using x-sample-header:true. Since 2.0, the same functionality is achieved by using regex_headers. - - -## Regex headers - -You can also set the `value` of a regex header to `".*"` to test for the existence of a header. - -### Conditional example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-mode -spec: - prefix: /backend/ - service: quote-mode - regex_headers: - x-quote-mode: ".*" - ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-regular -spec: - prefix: /backend/ - service: quote-regular -``` - -will send requests that contain the x-quote-mode header to the quote-mode target, while routing all other requests to the quote-regular target. - -The following mapping will route mobile requests from Android and iPhones to a mobile service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - regex_headers: - user-agent: ".*(iPhone|(a|A)ndroid).*" - prefix: /backend/ - service: quote -``` diff --git a/content/en/docs/3.0/topics/using/headers/host.md b/content/en/docs/3.0/topics/using/headers/host.md deleted file mode 100644 index 5a8dd02c..00000000 --- a/content/en/docs/3.0/topics/using/headers/host.md +++ /dev/null @@ -1,76 +0,0 @@ -# Host headers - -$productName$ supports several different methods for managing the HTTP `Host` header. - -## Using `host` and `host_regex` - -A mapping that specifies the `host` attribute will take effect _only_ if the HTTP `Host` header matches the value in the `host` attribute. If `host_regex` is `true`, the `host` value is taken to be a regular expression. Otherwise, an exact string match is required. - -You may have multiple mappings listing the same resource but different `host` attributes to effect `Host`-based routing. An example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote1 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend-2 -spec: - prefix: /backend/ - host: quote.datawire.io - service: quote2 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend-3 -spec: - prefix: /backend/ - host: "^quote[2-9]\\.datawire\\.io$" - host_regex: true - service: quote3 -``` - -will map requests for `/` to - -- the `quote2` service if the `Host` header is `quote.datawire.io`; -- the `quote3` service if the `Host` header matches `^quote[2-9]\\.datawire\\.io$`; and to -- the `quote1` service otherwise. - -Note that enclosing regular expressions in quotes can be important to prevent backslashes from being doubled. - -## Using `host_rewrite` - -By default, the `Host` header is not altered when talking to the service -- whatever `Host` header the client gave to $productName$ will be presented to the service. For many microservices, this will be fine, but if you use $productName$ to route to services that use the `Host` header for routing, it's likely to fail (legacy monoliths are particularly susceptible to this, as well as external services). You can use `host_rewrite` to force the `Host` header to whatever value that such target services need. - -An example: the default $productName$ configuration includes the following mapping for `httpbin.org`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin -spec: - prefix: /httpbin/ - service: httpbin.org:80 - host_rewrite: httpbin.org -``` - -As it happens, `httpbin.org` is virtually hosted, and it simply _will not_ function without a `Host` header of `httpbin.org`, which means that the `host_rewrite` attribute is necessary here. - -## `host` and `method` - -Internally: - -- the `host` attribute becomes a `header` match on the `:authority` header; and -- the `method` attribute becomes a `header` match on the `:method` header. - -You will see these headers in the diagnostic service if you use the `method` or `host` attributes. diff --git a/content/en/docs/3.0/topics/using/headers/remove_request_headers.md b/content/en/docs/3.0/topics/using/headers/remove_request_headers.md deleted file mode 100644 index 62603756..00000000 --- a/content/en/docs/3.0/topics/using/headers/remove_request_headers.md +++ /dev/null @@ -1,57 +0,0 @@ -# Remove request headers - -$productName$ can remove a list of HTTP headers that would be sent to the upstream from the request. - -## The `remove_request_headers` attribute - -The `remove_request_headers` attribute takes a list of keys used to match to the header. - -`remove_request_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -## Mapping example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - remove_request_headers: - - authorization - service: quote -``` - -will drop the header with key `authorization`. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - remove_request_headers: - - authorization ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - prefix: /backend2/ - service: quote -``` - -This is the same as the mapping example, but the headers will be removed for both mappings. diff --git a/content/en/docs/3.0/topics/using/headers/remove_response_headers.md b/content/en/docs/3.0/topics/using/headers/remove_response_headers.md deleted file mode 100644 index 16b18569..00000000 --- a/content/en/docs/3.0/topics/using/headers/remove_response_headers.md +++ /dev/null @@ -1,57 +0,0 @@ -# Remove response headers - -$productName$ can remove a list of HTTP headers that would be sent to the client in the response (e.g. default `x-envoy-upstream-service-time`). - -## The `remove_response_headers` attribute - -The `remove_response_headers` attribute takes a list of keys used to match to the header. - -`remove_request_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -## Mapping example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - remove_response_headers: - - x-envoy-upstream-service-time - service: quote -``` - -will drop the header with key `x-envoy-upstream-service-time`. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - remove_response_headers: - - x-envoy-upstream-service-time ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - prefix: /backend2/ - service: quote -``` - -This is the same as the mapping example, but the headers will be removed for both mappings. diff --git a/content/en/docs/3.0/topics/using/intro-mappings.md b/content/en/docs/3.0/topics/using/intro-mappings.md deleted file mode 100644 index 51656052..00000000 --- a/content/en/docs/3.0/topics/using/intro-mappings.md +++ /dev/null @@ -1,148 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Introduction to the Mapping resource - -$productName$ is designed around a [declarative, self-service management model](../../concepts/gitops-continuous-delivery). The core resource used to support application development teams who need to manage the edge with $productName$ is the `Mapping` resource. - - - Remember that Listener and Host resources are -  required for a functioning $productName$ installation that can route traffic!
- Learn more about Listener.
- Learn more about Host. - - -## Quick example - -At its core a `Mapping` resource maps a `resource` to a `service`: - -| Required attribute | Description | -| :------------------------ | :------------------------ | -| `name` | is a string identifying the `Mapping` (e.g. in diagnostics) | -| [`prefix`](#resources) | is the URL prefix identifying your [resource](#resources) | -| [`service`](#services) | is the name of the [service](#services) handling the resource; must include the namespace (e.g. `myservice.othernamespace`) if the service is in a different namespace than $productName$ | - -These resources are defined as Kubernetes Custom Resource Definitions. Here's a simple example that maps all requests to `/httpbin/` to the `httpbin.org` web service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin-mapping -spec: - prefix: /httpbin/ - service: http://httpbin.org -``` - -## Applying a Mapping resource - -A `Mapping` resource can be managed using the same workflow as any other Kubernetes resources (e.g., `service`, `deployment`). For example, if the above `Mapping` is saved into a file called `httpbin-mapping.yaml`, the following command will apply the configuration directly to $productName$: - -``` -kubectl apply -f httpbin-mapping.yaml -``` - -For production use, the general recommended best practice is to store the file in a version control system and apply the changes with a continuous deployment pipeline. For more detail, see [the Ambassador Operating Model](../../concepts/gitops-continuous-delivery). - -## Extending Mappings - -`Mapping` resources support a rich set of annotations to customize the specific routing behavior. Here's an example service for implementing the CQRS pattern (using HTTP): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-get -spec: - prefix: /cqrs/ - method: GET - service: getcqrs ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-put -spec: - prefix: /cqrs/ - method: PUT - service: putcqrs -``` - -More detail on each of the available annotations are discussed in subsequent sections. - -## Resources - -To $productName$, a `resource` is a group of one or more URLs that all share a common prefix in the URL path. For example: - -``` -https://ambassador.example.com/resource1/foo -https://ambassador.example.com/resource1/bar -https://ambassador.example.com/resource1/baz/zing -https://ambassador.example.com/resource1/baz/zung -``` - -all share the `/resource1/` path prefix, so it can be considered a single resource. On the other hand: - -``` -https://ambassador.example.com/resource1/foo -https://ambassador.example.com/resource2/bar -https://ambassador.example.com/resource3/baz/zing -https://ambassador.example.com/resource4/baz/zung -``` - -share only the prefix `/` -- you _could_ tell $productName$ to treat them as a single resource, but it's probably not terribly useful. - -Note that the length of the prefix doesn't matter: if you want to use prefixes like `/v1/this/is/my/very/long/resource/name/`, go right ahead, $productName$ can handle it. - -Also note that $productName$ does not actually require the prefix to start and end with `/` -- however, in practice, it's a good idea. Specifying a prefix of - -``` -/man -``` - -would match all of the following: - -``` -https://ambassador.example.com/man/foo -https://ambassador.example.com/mankind -https://ambassador.example.com/man-it-is/really-hot-today -https://ambassador.example.com/manohmanohman -``` - -which is probably not what was intended. - -## Services - -$productName$ routes traffic to a `service`. A `service` is defined as: - -``` -[scheme://]service[.namespace][:port] -``` - -Where everything except for the `service` is optional. - -- `scheme` can be either `http` or `https`; if not present, the default is `http`. -- `service` is the name of a service (typically the service name in Kubernetes or Consul); it is not allowed to contain the `.` character. -- `namespace` is the namespace in which the service is running. Starting with $productName$ 1.0.0, if not supplied, it defaults to the namespace in which the Mapping resource is defined. The default behavior can be configured using the [`ambassador` Module](../../running/ambassador). When using a Consul resolver, `namespace` is not allowed. -- `port` is the port to which a request should be sent. If not specified, it defaults to `80` when the scheme is `http` or `443` when the scheme is `https`. Note that the [resolver](../../running/resolvers) may return a port in which case the `port` setting is ignored. - -Note that while using `service.namespace.svc.cluster.local` may work for Kubernetes resolvers, the preferred syntax is `service.namespace`. - -## Best practices for configuration - -$productName$'s configuration is assembled from multiple YAML blocks which are managed by independent application teams. This implies: - -- $productName$'s configuration should be under version control. - - While you can always read back the $productName$'s configuration from Kubernetes or its diagnostic service, the $productName$ will not do versioning for you. - -- Be aware that the $productName$ tries to not start with a broken configuration, but it's not perfect. - - Gross errors will result in $productName$ refusing to start, in which case `kubectl logs` will be helpful. However, it's always possible to e.g. map a resource to the wrong service, or use the wrong `rewrite` rules. $productName$ can't detect that on its own, although its diagnostic pages can help you figure it out. - -- Be careful of mapping collisions. - - If two different developers try to map `/user/` to something, this can lead to unexpected behavior. $productName$'s canary-deployment logic means that it's more likely that traffic will be split between them than that it will throw an error -- again, the diagnostic service can help you here. - -**Note:** Unless specified, mapping attributes cannot be applied to any other resource type. diff --git a/content/en/docs/3.0/topics/using/keepalive.md b/content/en/docs/3.0/topics/using/keepalive.md deleted file mode 100644 index d75e96ba..00000000 --- a/content/en/docs/3.0/topics/using/keepalive.md +++ /dev/null @@ -1,70 +0,0 @@ -# Keepalive - -Keepalive option indicates whether `SO_KEEPALIVE` on the socket should be enabled. - -## Keepalive configuration - -Keepalive configuration can be set for all $productName$ mappings in the [`ambassador Module`](../../running/ambassador) or set per [`Mapping`](../mappings). - -The `keepalive` attribute configures keepalive. The following fields are supported: - -```yaml -keepalive: - idle_time: - interval: - probes: -``` - -### `idle_time` - -(Default: `7200`) The number of seconds a connection needs to be idle before keep-alive probes start being sent. - -### `interval` - -(Default: `75`) The number of seconds between keep-alive probes. - -### `probes` - -(Default: `9`) is the maximum number of keepalive probes to send without response before deciding the connection is dead. - -## Examples - -Keepalive probes defined on a single mapping: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - keepalive: - idle_time: 100 - interval: 10 - probes: 9 -``` - -A global keepalive configuration: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - keepalive: - idle_time: 100 - interval: 10 - probes: 9 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote -``` diff --git a/content/en/docs/3.0/topics/using/mappings.md b/content/en/docs/3.0/topics/using/mappings.md deleted file mode 100644 index f930fc62..00000000 --- a/content/en/docs/3.0/topics/using/mappings.md +++ /dev/null @@ -1,189 +0,0 @@ -# Advanced Mapping configuration - -$productName$ is designed so that the author of a given Kubernetes service can easily and flexibly configure how traffic gets routed to the service. The core abstraction used to support service authors is a mapping, which maps a target backend service to a given host or prefix. For Layer 7 protocols such as HTTP, gRPC, or WebSockets, the `Mapping` resource is used. For TCP, the `TCPMapping` resource is used. - -$productName$ _must_ have one or more mappings defined to provide access to any services at all. The name of the mapping must be unique. - -## System-wide defaults for Mappings - -Certain aspects of mappings can be set system-wide using the `defaults` element of the `ambassador Module`: -see [using defaults](../../using/defaults) for more information. The `Mapping` element will look first in -the `httpmapping` default class. - -## Mapping evaluation order - -$productName$ sorts mappings such that those that are more highly constrained are evaluated before those less highly constrained. The prefix length, the request method, constraint headers, and query parameters are all taken into account. - -If absolutely necessary, you can manually set a `precedence` on the mapping (see below). In general, you should not need to use this feature unless you're using the `regex_headers` or `host_regex` matching features. If there's any question about how $productName$ is ordering rules, the diagnostic service is a good first place to look: the order in which mappings appear in the diagnostic service is the order in which they are evaluated. - -## Optional fallback Mapping - -$productName$ will respond with a `404 Not Found` to any request for which no mapping exists. If desired, you can define a fallback "catch-all" mapping so all unmatched requests will be sent to an upstream service. - -For example, defining a mapping with only a `/` prefix will catch all requests previously unhandled and forward them to an external service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: catch-all -spec: - prefix: / - service: https://www.getambassador.io -``` - -### Using `precedence` - -$productName$ sorts mappings such that those that are more highly constrained are evaluated before those less highly constrained. The prefix length, the request method, and the constraint headers are all taken into account. These mechanisms, however, may not be sufficient to guarantee the correct ordering when regular expressions or highly complex constraints are in play. - -For those situations, a `Mapping` can explicitly specify the `precedence`. A `Mapping` with no `precedence` is assumed to have a `precedence` of 0; the higher the `precedence` value, the earlier the `Mapping` is attempted. - -If multiple `Mapping`s have the same `precedence`, $productName$'s normal sorting determines the ordering within the `precedence`; however, there is no way that $productName$ can ever sort a `Mapping` with a lower `precedence` ahead of one at a higher `precedence`. - -### Using `tls` - -To originate TLS, use a `service` with an `https://` prefix. By itself, this will cause $productName$ to originate TLS without presenting a client certificate to the upstream service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-no-cert -spec: - prefix: /prefix/ - service: https://upstream/ -``` - -If you do need to supply a client certificate, you will also need to set `tls` to the name of a defined TLS context. The client certificate given in that context will be presented to the upstream service. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-with-cert -spec: - prefix: /prefix/ - service: https://upstream/ - tls: upstream-cert-context -``` - -(If `tls` is present, $productName$ will originate TLS even if the `service` does not have an `https://` prefix.) - -### Using `cluster_tag` - -If the `cluster_tag` attribute is present, its value will be prepended to cluster names generated from -the `Mapping`. This provides a simple mechanism for customizing the `cluster` name when working with metrics. - -## Using `dns_type` - -If the `dns_type` attribute is present, its value will determine how the DNS is used when locating the upstream service. Valid values are: - -- `strict_dns` (the default): The DNS result is assumed to define the exact membership of the cluster. For example, if DNS returns three IP addresses, the cluster is assumed to have three distinct upstream hosts. If a successful DNS query returns no hosts, the cluster is assumed to be empty. `strict_dns` makes sense for situations like a Kubernetes service, where DNS resolution is fast and returns a relatively small number of IP addresses. - -- `logical_dns`: Instead of assuming that the DNS result defines the full membership of the cluster, every new connection simply uses the first IP address returned by DNS. `logical_dns` makes sense for a service with a large number of IP addresses using round-robin DNS for upstream load balancing: typically each DNS query returns a different first result, and it is not necessarily possible to know the full membership of the cluster. With `logical_dns`, no attempt is made to garbage-collect connections: they will stay open until the upstream closes them. - -If `dns_type` is not given, `strict_dns` is the default, as this is the most conservative choice. When interacting with large web services with many IP addresses, switching to `logical_dns` may be a better choice. For more on the different types of DNS, see the [`strict_dns` Envoy documentation] or the [`logical_dns` Envoy documentation]. - -[`strict_dns` Envoy documentation]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/service_discovery#strict-dns -[`logical_dns` Envoy documentation]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/service_discovery#logical-dns - - -## Namespaces and Mappings - -If `AMBASSADOR_NAMESPACE` is correctly set, $productName$ can map to services in other namespaces by taking advantage of Kubernetes DNS: - -- `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. - -### Linkerd interoperability (`add_linkerd_headers`) - -When using Linkerd, requests going to an upstream service need to include the `l5d-dst-override` header to ensure that Linkerd will route them correctly. Setting `add_linkerd_headers` does this automatically, based on the `service` attribute in the `Mapping`. - -If `add_linkerd_headers` is not specified for a given `Mapping`, the default is taken from the `ambassador`[Module](../../running/ambassador). The overall default is `false`: you must explicitly enable `add_linkerd_headers` for $productName$ to add the header for you (although you can always add it yourself with `add_request_headers`, of course). - -### "Upgrading" to non-HTTP protocols (`allow_upgrade`) - -HTTP has [a mechanism][upgrade-mechanism] where the client can say -`Connection: upgrade` / `Upgrade: PROTOCOL` to switch ("upgrade") from -the current HTTP version to a different one, or even a different -protocol entirely. $productName$ itself understands and can handle the -different HTTP versions, but for other protocols you need to tell -$productName$ to get out of the way, and let the client speak that -protocol directly with your upstream service. You can do this by -setting the `allow_upgrade` field to a case-insensitive list of -protocol names $productName$ will allow switching to from HTTP. After -the upgrade, $productName$ does not interpret the traffic, and behaves -similarly to how it does for `TCPMapping`s. - -[upgrade-mechanism]: https://tools.ietf.org/html/rfc7230#section-6.7 - -This "upgrade" mechanism is a useful way of adding HTTP-based -authentication and access control to another protocol that might not -support authentication; for this reason the designers of the WebSocket -protocol made this "upgrade" mechanism the *only* way of initiating a -WebSocket connection. In a Mapping for an upstream service that -supports WebSockets, you would write - -```yaml -allow_upgrade: -- websocket -``` - -The Kubernetes apiserver itself uses this "upgrade" mechanism to -perform HTTP authentication before switching to SPDY for endpoint used -by `kubectl exec`; if you wanted to use $productName$ to expose the -Kubernetes apiserver such that `kubectl exec` functions, you would -write - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: apiserver -spec: - hostname: "*" - service: https://kubernetes.default - prefix: / - allow_upgrade: - - spdy/3.1 -``` - -There is a deprecated setting `use_websocket`; setting `use_websocket: -true` is equivalent to setting `allow_upgrade: ["websocket"]`. - -## DNS configuration for Mappings - -`respect_dns_ttl` can be set to `true` to force the DNS refresh rate for this `Mapping` to be set to the record’s TTL obtained from DNS resolution. -- Allowed values: `true` or `false` -- Default: `false` - - -`dns_type` can be used to configure the service discovery type between Strict DNS and Logical DNS. You can -- Allowed values: - - `strict_dns`: Ambassador will continuously and asynchronously resolve the specified DNS targets. - - `logical_dns`: Similar to `strict_dns`, but only uses the first IP address returned when a new connection needs to be initiated and Connections are never drained. More optimal for large scale web services that must be accessed via DNS. -- Default: `strict_dns` - - -For more information on the differences between dns types, see [the Envoy documentation for service discovery](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/service_discovery.html). - -> **Note:** When the [endpoint resolver](../../running/resolvers/#the-kubernetes-endpoint-resolver) is used in a `Mapping`, `dns_type` will be ignored in favor of the endpoint resolver's service discovery. - - - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: dnsoverwrite -spec: - service: quote - prefix: /backend/ - dns_type: logical_dns - respect_dns_ttl: true -``` diff --git a/content/en/docs/3.0/topics/using/method.md b/content/en/docs/3.0/topics/using/method.md deleted file mode 100644 index 94185dcd..00000000 --- a/content/en/docs/3.0/topics/using/method.md +++ /dev/null @@ -1,26 +0,0 @@ -# Method-based routing - -$productName$ supports routing based on the HTTP method and regular expression. - -## Using `method` - -The `method` annotation specifies the specific HTTP method for a mapping. The value of the `method` annotation must be in all upper case. - -For example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: get -spec: - hostname: "*" - prefix: /backend/get_only/ - method: GET - service: quote -``` - -## Using `method_regex` - -When `method_regex` is set to `true`, the value of the `method` annotation will be interpreted as a regular expression. diff --git a/content/en/docs/3.0/topics/using/prefix_regex.md b/content/en/docs/3.0/topics/using/prefix_regex.md deleted file mode 100644 index 04a6e4b8..00000000 --- a/content/en/docs/3.0/topics/using/prefix_regex.md +++ /dev/null @@ -1,25 +0,0 @@ -# Prefix regex - -## Using `prefix` and `prefix_regex` - -When the `prefix_regex` attribute is set to `true`, $productName$ configures a [regex route](https://www.envoyproxy.io/docs/envoy/v1.5.0/api-v1/route_config/route#route) instead of a prefix route in Envoy. **This means the entire path must match the regex specified, not only the prefix.** - -## Example with a version in the URL - -If the version is a path parameter and the resources are served by different services, then - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: qotm -spec: - prefix: "/(v1|v2)/qotm/.*" - prefix_regex: true - service: qotm -``` - -will map requests to both `/v1` and `/v2` to the `qotm` service. - -Note that enclosing regular expressions in quotes can be important to prevent backslashes from being doubled. diff --git a/content/en/docs/3.0/topics/using/query-parameters.md b/content/en/docs/3.0/topics/using/query-parameters.md deleted file mode 100644 index 6b880fd4..00000000 --- a/content/en/docs/3.0/topics/using/query-parameters.md +++ /dev/null @@ -1,69 +0,0 @@ -# Query parameter-based routing - -$productName$ can route to target services based on HTTP query parameters with the `query_parameters` and `regex_query_parameters` specifications. Multiple mappings with different annotations can be applied to construct more complex routing rules. - -## The `query_parameters` annotation - -The `query_parameters` attribute is a dictionary of `query_parameter`: `value` pairs. $productName$ will only allow requests that match the specified `query_parameter`: `value` pairs to reach the target service. - -You can also set the `value` of a query parameter to `true` to test for the existence of a query parameter. - -### A basic example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - query_parameters: - quote-mode: backend - random-query-parameter: datawire -``` - -This will allow requests to /backend/ to succeed only if the `quote-mode` query parameter has the value `backend` and the `random-query-parameter` has the value `datawire`. - -## `regex_query_parameters` - -The following mapping will route requests with the `quote-mode` header that contain values that match the regex. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - regex_query_parameters: - quote-mode: "^[a-z].*" - prefix: /backend/ - service: quote -``` - -### A conditional example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-mode -spec: - prefix: /backend/ - service: quote-mode - regex_query_parameters: - quote-mode: .* ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-regular -spec: - prefix: /backend/ - service: quote-regular -``` - -This will send requests that contain the `quote-mode` query parameter (with any value) to the `quote-mode` target, while routing all other requests to the `quote-regular` target. diff --git a/content/en/docs/3.0/topics/using/rate-limits/index.md b/content/en/docs/3.0/topics/using/rate-limits/index.md deleted file mode 100644 index b65f8c5d..00000000 --- a/content/en/docs/3.0/topics/using/rate-limits/index.md +++ /dev/null @@ -1,199 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Basic rate limiting - -Rate limiting in $productName$ is composed of two parts: - -* The [`RateLimitService`](../../running/services/rate-limit-service) resource tells $productName$ what external service - to use for rate limiting. - - If $productName$ cannot contact the rate limit service, it will allow the request to be processed as if there were no rate limit service configuration. - -* _Labels_ that get attached to requests. A label is basic metadata that - is used by the `RateLimitService` to decide which limits to apply to - the request. - - - These labels require Mapping resources with apiVersion - getambassador.io/v2 or newer — if you're updating an old installation, check the - apiVersion! - - -Labels are grouped according to _domain_ and _group_: - -```yaml -labels: - "domain1": - - "group1": - - "my_label_specifier_1" - - "my_label_specifier_2" - - "group2": - - "my_label_specifier_3" - - "my_label_specifier_4" - "domain2": - - ... -``` - -The names of domains and groups are not interpreted by $productName$ in any way: -they are solely there to help configuration authors remember the different groupings. -Note that **at present, rate limiting supports just one domain**: the name of the -domain must be configured in the [`RateLimitService`](../../running/services/rate-limit-service). - - - -## Attaching labels to requests - -There are two ways of setting labels on a request: - -1. You can set labels on an individual [`Mapping`](../mappings). These labels - will only apply to requests that use that `Mapping`. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Mapping - metadata: - name: foo-mapping - spec: - hostname: "*" - prefix: /foo/ - service: foo - labels: - "domain1": - - "group1": - - "my_label_specifier_1" - - "my_label_specifier_2" - - "group2": - - "my_label_specifier_3" - - "my_label_specifier_4" - "domain2": - - ... - ``` - -2. You can set global labels in the [`ambassador` `Module`](../../running/ambassador). - These labels will apply to _every_ request that goes through $productName$. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - spec: - config: - default_labels: - "domain1": - defaults: - - "my_label_specifier_a" - - "my_label_specifier_b" - "domain2": - defaults: - - "my_label_specifier_c" - - "my_label_specifier_d" - ``` - - If a `Mapping` and the defaults both give label groups for the same domain, the - default labels are prepended to each label group from the `Mapping`. If the `Mapping` - does not give any labels for that domain, the global labels are placed into a new - label group named "default" for that domain. - -Each label group is a list of labels; each label is a key/value pair. Since the label -group is a list rather than a map: -- it is possible to have multiple labels with the same key, and -- the order of labels matters. - -> Note: The terminology used by the Envoy documentation differs from -> the terminology used by $productName$: -> -> | $productName$ | Envoy | -> |-----------------|-------------------| -> | label group | descriptor | -> | label | descriptor entry | -> | label specifier | rate limit action | - -The `Mapping`s' listing of the groups of specifiers have names for the -groups; the group names are useful for humans dealing with the YAML, -but are ignored by $productName$, all $productName$ cares about are the -*contents* of the groupings of label specifiers. - -There are 5 types of label specifiers in $productName$: - - - -1. `source_cluster` - - ```yaml - source_cluster: - key: source_cluster - ``` - - Sets the label `source_cluster=«Envoy source cluster name»"`. The Envoy - source cluster name is the name of the Envoy cluster that the request came - in on. - - The syntax of this label currently _requires_ `source_cluster: {}`. - -2. `destination_cluster` - - ```yaml - destination_cluster: - key: destination_cluster - ``` - - Sets the label `destination_cluster=«Envoy destination cluster name»"`. The Envoy - destination cluster name is the name of the Envoy cluster to which the `Mapping` - routes the request. You can get the name for a cluster from the - [diagnostics service](../../running/diagnostics). - - The syntax of this label currently _requires_ `destination_cluster: {}`. - -3. `remote_address` - - ```yaml - remote_address: - key: remote_address - ``` - - Sets the label `remote_address=«IP address of the client»"`. The IP address of - the client will be taken from the `X-Forwarded-For` header, to correctly manage - situations with L7 proxies. This requires that $productName$ be correctly - [configured to communicate](../../../howtos/configure-communications). - - The syntax of this label currently _requires_ `remote_address: {}`. - -4. `request_headers` - - ```yaml - request_headers: - header_name: "header-name" - key: mykey - ``` - - If a header named `header-name` is present, set the label `mykey=«value of the header»`. - If no header named `header-name` is present, **the entire label group is dropped**. - -5. `generic_key` - - ```yaml - generic_key: - key: mykey - value: myvalue - ``` - - Sets the label `«mykey»=«myval»`. Note that supplying a `key` is supported only - with the Envoy V3 API. - -## Rate limiting requests based on their labels - -This is determined by your `RateLimitService` implementation. See the -[Basic Rate Limiting tutorial](../../../howtos/rate-limiting-tutorial) for an -example `RateLimitService` implementation for $productName$. - -If you'd rather not write your own `RateLimitService` implementation, -$AESproductName$ provides a `RateLimitService` implementation that is -configured by a `RateLimit` custom resource. See the -[$AESproductName$ RateLimit Reference](/docs/edge-stack/latest/topics/using/rate-limits/rate-limits/) -for more information. diff --git a/content/en/docs/3.0/topics/using/redirects.md b/content/en/docs/3.0/topics/using/redirects.md deleted file mode 100644 index f55c467d..00000000 --- a/content/en/docs/3.0/topics/using/redirects.md +++ /dev/null @@ -1,142 +0,0 @@ -# Redirects - -$productName$ can perform 3xx redirects on `Mapping`s to a different host, with various options to redirect the path and to return a different 3xx response code instead of the default 301. - -## Schema - -| Name | Type | Description | -| --- | --- | --- | -| `spec.host_redirect` | Boolean | This is *required* to be set to `true` to use any type of redirect, otherwise the request will be proxied instead of redirected. | -| `spec.path_redirect` | String | Optional, changes the path for the redirect. | -| `spec.prefix_redirect` | String | Optional, matches the `prefix` value and replaces it with the `prefix_redirect` value. | -| `spec.regex_redirect` | String | Optional, uses regex to match and replace the `prefix` value. | -| `spec.redirect_response_code` | Integer | Optional, changes the response code from the default 301, valid values are 301, 302, 303, 307, and 308. | -| `spec.config. x_forwarded_proto_redirect` | Boolean | Redirect only the originating HTTP requests to HTTPS, allowing the originating HTTPS requests to pass through. | -| `spec.config. use_remote_address` | Boolean | Required to be set to `false` to use the `x_forwarded_proto_redirect` feature. | - -## Examples - -### Basic redirect - -To effect any type of HTTP `Redirect`, the `Mapping` *must* set `host_redirect` to `true`, with `service` set to the host to which the client should be redirected: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - prefix: /redirect/ - service: httpbin.org - host_redirect: true - hostname: '*' -``` - -Using this `Mapping`, a request to `http://$AMBASSADOR_URL/redirect/` will be redirected to `http://httpbin.org/redirect/`. - -> As always with $productName$, the trailing `/` on any URL with a -`Mapping` is required! - -### Path redirect - -The `Mapping` may optionally also set additional properties to customize the behavior of the HTTP redirect response. - -To also change the path portion of the URL during the redirect, set `path_redirect`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - hostname: '*' - prefix: /redirect/ - service: httpbin.org - host_redirect: true - path_redirect: /ip -``` - -Here, a request to `http://$AMBASSADOR_URL/redirect/` will be redirected to `http://httpbin.org/ip/`. - -### Prefix redirect - -To change only a prefix of the path portion of the URL, set `prefix_redirect`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - hostname: '*' - prefix: /redirect/path/ - service: httpbin.org - host_redirect: true - prefix_redirect: /ip -``` - -Now, a request to `http://$AMBASSADOR_URL/redirect/path/` will be redirected to `http://httpbin.org/ip/`. The prefix `/redirect/path/` was matched and replaced with `/ip/`. - -### Regex redirect - -`regex_redirect` matches a regular expression to replace instead of a fixed prefix. -[See more information about using regex with $productName$](../rewrites/#regex_rewrite). - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - prefix: /foo/ - service: httpbin.org - host_redirect: true - regex_redirect: - pattern: '/foo/([0-9]*)/list' - substitution: '/bar/\1' -``` -A request to `http://$AMBASSADOR_URL/foo/12345/list` will be redirected to -`http://$AMBASSADOR_URL/bar/12345`. - -### Redirect response code - -To change the HTTP response code return by $productName$, set `redirect_reponse_code`. If this is not set, 301 is returned by default. Valid values include 301, 302, 303, 307, and 308. This -can be used with any type of redirect. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - prefix: /ip/ - service: httpbin.org - host_redirect: true - redirect_response_code: 302 -``` - -A request to `http://$AMBASSADOR_URL/ip/` will result in an HTTP 302 redirect to `http://httpbin.org/ip`. - -### X-FORWARDED-PROTO redirect - -In cases when TLS is being terminated at an external layer 7 load balancer, then you would want to redirect only the originating HTTP requests to HTTPS, and let the originating HTTPS requests pass through. - -This distinction between an originating HTTP request and an originating HTTPS request is done based on the `X-FORWARDED-PROTO` header that the external layer 7 load balancer adds to every request it forwards after TLS termination. - -To enable this `X-FORWARDED-PROTO` based HTTP to HTTPS redirection, add a `x_forwarded_proto_redirect: true` field to `ambassador Module`'s configuration. Note that when this feature is enabled `use_remote_address` MUST be set to false. - -An example configuration is as follows - - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - x_forwarded_proto_redirect: true - use_remote_address: false -``` - -Note: Setting `x_forwarded_proto_redirect: true` will impact all your $productName$ mappings. Every HTTP request to $productName$ will only be allowed to pass if it has an `X-FORWARDED-PROTO: https` header. diff --git a/content/en/docs/3.0/topics/using/retries.md b/content/en/docs/3.0/topics/using/retries.md deleted file mode 100644 index d018ab59..00000000 --- a/content/en/docs/3.0/topics/using/retries.md +++ /dev/null @@ -1,84 +0,0 @@ -# Automatic retries - -Sometimes requests fail. When these requests fail for transient issues, $productName$ can automatically retry the request. - -Retry policy can be set for all $productName$ mappings in the [`ambassador Module`](../../running/ambassador), or set per [`Mapping`](../mappings). Generally speaking, you should set `retry_policy` on a per mapping basis. Global retries can easily result in unexpected cascade failures. - -> Note that when setting `retry_policy`, adjusting `max_retries` in the [circuit breaker](https://www.getambassador.io/docs/edge-stack/pre-release/topics/using/circuit-breakers/) configuration should also be considered in order to account for all desired retries. - -## Configuring retries - -The `retry_policy` attribute configures automatic retries. The following fields are supported: - -```yaml -retry_policy: - retry_on: - num_retries: - per_try_timeout: -``` - -### `retry_on` - -(Required) Specifies the condition under which $productName$ retries a failed request. - -| Value | Description | -| --- | --- | -|`5xx`| Retries if the upstream service responds with any 5xx code or does not respond at all -|`gateway-error`| Similar to a `5xx` but only applies to a 502, 503, or 504 response -|`connect-failure`| Retries on a connection failure to the upstream service (included in `5xx`) -|`retriable-4xx`| Retries on a retriable 4xx response (currently only 409) -|`refused-stream`| Retires if the upstream service sends a REFUSED_STREAM error (included in `5xx`) -|`retriable-status-codes`| Retries based on status codes set in the `x-envoy-retriable-status-codes` header. If that header isn't set, $productName$ will not retry the request. - - For more details on each of these values, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/v1.9.0/configuration/http_filters/router_filter#x-envoy-retry-on). - -### `num_retries` - -(Default: 1) Specifies the number of retries to execute for a failed request. - -### `per_try_timeout` - -(Default: global request timeout) Specify the timeout for each retry. Must be in seconds or nanoseconds, e.g., `1s`, `1500ns`. - -## Examples - -A per mapping retry policy: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - retry_policy: - retry_on: "5xx" - num_retries: 10 -``` - -A global retry policy (not recommended): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - retry_policy: - retry_on: "retriable-4xx" - num_retries: 4 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - hostname: '*' -``` diff --git a/content/en/docs/3.0/topics/using/rewrites.md b/content/en/docs/3.0/topics/using/rewrites.md deleted file mode 100644 index 44d0a961..00000000 --- a/content/en/docs/3.0/topics/using/rewrites.md +++ /dev/null @@ -1,100 +0,0 @@ -# Rewrites - -Once $productName$ uses a prefix to identify the service to which a given request should be passed, it can rewrite the URL before handing it off to the service. - -There are two approaches for rewriting: `rewrite` for simpler scenarios and `regex_rewrite` for more advanced rewriting. - -**Please note that** only one of these two can be configured for a mapping **at the same time**. As a result $productName$ ignores `rewrite` when `regex_rewrite` is provided. - -## `rewrite` - -By default, the `prefix` is rewritten to `/`, so e.g., if we map `/backend-api/` to the service `service1`, then - - -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/content/en/docs/3.0/topics/using/shadowing.md b/content/en/docs/3.0/topics/using/shadowing.md deleted file mode 100644 index 5a2d2457..00000000 --- a/content/en/docs/3.0/topics/using/shadowing.md +++ /dev/null @@ -1,79 +0,0 @@ -# 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. - -
-Shadowing - -## 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/content/en/docs/3.0/topics/using/tcpmappings.md b/content/en/docs/3.0/topics/using/tcpmappings.md deleted file mode 100644 index 37a6eb7a..00000000 --- a/content/en/docs/3.0/topics/using/tcpmappings.md +++ /dev/null @@ -1,225 +0,0 @@ -# TCP connections - -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`. - -## TCPMapping - -An $productName$ `TCPMapping` associates TCP connections with Kubernetes _services_. Cleartext TCP connections are defined by destination IP address and/or destination TCP port; TLS TCP connections can also be defined by the hostname presented using SNI. A service is exactly the same as in Kubernetes. - -## TCPMapping configuration - -$productName$ supports a number of attributes to configure and customize mappings. - -| Attribute | Description | -| :------------------------ | :------------------------ | -| `address` | (optional) the IP address on which $productName$ should listen for connections for this Mapping -- if not present, $productName$ will listen on all addresses ) -| `port` | (required) the TCP port on which $productName$ should listen for connections for this Mapping | -| `idle_timeout_ms` | (optional) the timeout, in milliseconds, after which the connection will be terminated if no traffic is seen -- if not present, no timeout is applied | -| `enable_ipv4` | (optional) if true, enables IPv4 DNS lookups for this mapping's service (the default is set by the [`ambassador Module`](../../running/ambassador)) | -| `enable_ipv6` | (optional) if true, enables IPv6 DNS lookups for this mapping's service (the default is set by the [`ambassador Module`](../../running/ambassador)) | -| `circuit_breakers` | (optional) circuit breakers, as for [`HTTP mapping`](../circuit-breakers) (the default is set by the [`ambassador Module`](../../running/ambassador)) | - -If both `enable_ipv4` and `enable_ipv6` are set, $productName$ will prefer IPv6 to IPv4. See the [`ambassador Module`](../../running/ambassador) documentation for more information. - -$productName$ can manage TCP connections using TLS: - -| Attribute | Description | -| :------------------------ | :------------------------ | -| [`host`](../headers/host) | (optional) enables TLS _termination_ and specifies the hostname that must be presented using SNI for this `TCPMapping` to match -- **FORCES TLS TERMINATION**, see below | -| [`service`](#tcpmapping-and-tls) | An `https://` prefix will enable TLS _origination_ | -| [`tls`](#tcpmapping-and-tls) | (optional) configures TLS _origination_ by specifying the name of a `TLSContext` that will determine the certificate to offer to the upstream service | - -$productName$ supports multiple deployment patterns for your services. These patterns are designed to let you safely release new versions of your service while minimizing its impact on production users. - -| Attribute | Description | -| :------------------------ | :------------------------ | -| [`weight`](../canary) | (optional) specifies the (integer) percentage of traffic for this resource that will be routed using this mapping | - -The name of the mapping must be unique. - -### `TCPMapping` and TLS - -The `host` attribute of a `TCPMapping` determines whether $productName$ will terminate TLS when a client connects. The `service` prefix (if any) and the `tls` attribute work together to determine whether $productName$ will _originate_ TLS. The two are independent. - -This leaves four cases: - -#### `host` is not set, and the `service` does not state `https://` - -In this case, $productName$ simply proxies bytes between the client and the upstream. TLS may or may not be involved, and $productName$ doesn't care. You should specify the port to use for the upstream connection; if you don't, $productName$ will guess port 80. - -Examples: - -```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. - -#### `host` is set, but the `service` has no `https://` prefix - -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 the port to use for the upstream connection; if you don't, $productName$ will guess port **80**. - -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`, and that the termination `TLSContext` has a `host` that matches the `host` in the `TCPMapping`. (This is the same rule as TLS termination with SNI in an HTTP `Mapping`.) - -Example: - -```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 example 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. - -#### `host` is set, and `service` has an `https://` prefix - -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 also set, $productName$ will use to determine the certificate offered to the upstream service. You should specify the port to use for the upstream connection; if you don't, $productName$ will guess port **443**. - -This is useful for doing host routing while maintaining end-to-end encryption. - -Note that this case **requires** that you have created a termination `TLSContext`, and that the termination `TLSContext` has a `host` that matches the `host` in the `TCPMapping`. (This is the same rule as TLS termination with SNI in an HTTP `Mapping`.) - -Example: - -```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 example 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. - -#### `host` is not set, but `service` has an `https://` prefix - -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. - -#### Summary - -- To get a `TCPMapping` to terminate TLS, configure $productName$ with a termination `TLSContext` and list a `host` in the `TCPMapping`. - -- To get a `TCPMapping` to originate TLS, use an `http://` prefix for the `TCPMapping`'s `service`. Use the `tls` attribute as well if you want to offer a certificate to the upstream service. - -- You can mix and match as long as you think about how the protocols interact. - -#### Required attributes for `TCPMapping`s - -- `name` is a string identifying the `Mapping` (e.g. in diagnostics) -- `port` is an integer specifying which port to listen on for connections -- `service` is the name of the service handling the resource; must include the namespace (e.g. `myservice.othernamespace`) if the service is in a different namespace than $productName$ - -Note that the `service` in a `TCPMapping` should include a port number, and may include a scheme of `https`. - -## Namespaces and Mappings - -Given that `AMBASSADOR_NAMESPACE` is correctly set, $productName$ can map to services in other namespaces by taking advantage of Kubernetes DNS: - -- `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. diff --git a/content/en/docs/3.0/topics/using/timeouts.md b/content/en/docs/3.0/topics/using/timeouts.md deleted file mode 100644 index ae004102..00000000 --- a/content/en/docs/3.0/topics/using/timeouts.md +++ /dev/null @@ -1,66 +0,0 @@ -# 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/content/en/docs/3.0/tutorials/dev-portal-tutorial.md b/content/en/docs/3.0/tutorials/dev-portal-tutorial.md deleted file mode 100644 index d3c0d0a8..00000000 --- a/content/en/docs/3.0/tutorials/dev-portal-tutorial.md +++ /dev/null @@ -1,29 +0,0 @@ -# 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:///docs/` to see the -publicly visible Developer Portal. Make sure you include the trailing `/`. -This is a fully customizable portal that you can share with third parties who -need information about your APIs. diff --git a/content/en/docs/3.0/tutorials/getting-started.md b/content/en/docs/3.0/tutorials/getting-started.md deleted file mode 100644 index 014e1f7b..00000000 --- a/content/en/docs/3.0/tutorials/getting-started.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -description: "A simple three step guide to installing $productName$ and quickly get started routing traffic from the edge of your Kubernetes cluster to your services." ---- - -import Alert from '@material-ui/lab/Alert'; -import GettingStartedEmissary21Tabs from './gs-tabs' - -# $productName$ quick start - -
-

Contents

- -- [1. Installation](#1-installation) - - [Connecting your installation to Ambassador Cloud](#connecting-your-installation-to-ambassador-cloud) -- [2. Routing traffic from the edge](#2-routing-traffic-from-the-edge) -- [What's next?](#img-classos-logo-srcimageslogopng-whats-next) - -
- -## 1. Installation - -We'll start by installing $productName$ into your cluster. - -**We recommend using Helm** but there are other options below to choose from. - - - -### Connecting your installation to Ambassador Cloud - -Now is a great moment to connect your new installation to Ambassador Cloud in order to fully leverage the power of $productName$ and the Developer Control Plane (DCP). - -1. Log in to [Ambassador Cloud](https://app.getambassador.io/cloud/services/) with GitHub, GitLab or Google and select your team account. - -2. At the top, click **Add Services** then click **Connection Instructions** in the "Connect your installation" section. - -3. Follow the prompts to name the cluster and click **Generate a Cloud Token**. - -4. Follow the prompts to install the cloud token into your cluster. - -5. When the token installation completes, your services will be listed in the DCP. - -Success! At this point, you have installed $productName$. Now let's get some traffic flowing to your services. - -## 2. Routing traffic from the edge - -$productName$ uses Kubernetes Custom Resource Definitions (CRDs) to declaratively define its desired state. The workflow you are going to build uses a simple demo app, a **`Listener` CRD**, and a **`Mapping` CRD**. The `Listener` CRD tells $productName$ what port to listen on, and the `Mapping` CRD tells $productName$ how to route incoming requests by host and URL path from the edge of your cluster to Kubernetes services. - -1. Start by creating a `Listener` resource for HTTP on port 8080: - - ``` - kubectl apply -f - < - This 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.
-
- Learn more about Listener.
- Learn more about Host. - - -2. Apply the YAML for the "Quote" service. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/quickstart/qotm.yaml - ``` - - The Service and Deployment are created in your default namespace. You can use 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](#connecting-your-installation-to-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` - - ## Mapping editor - - 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 - <Victory! You have created your first $productName$ 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/content/en/docs/3.0/tutorials/gs-tabs.js b/content/en/docs/3.0/tutorials/gs-tabs.js deleted file mode 100644 index eb392504..00000000 --- a/content/en/docs/3.0/tutorials/gs-tabs.js +++ /dev/null @@ -1,131 +0,0 @@ -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 ( - - ); -} - -TabPanel.propTypes = { - children: PropTypes.node, - index: PropTypes.any.isRequired, - value: PropTypes.any.isRequired, -}; - -function a11yProps(index) { - return { - id: `simple-tab-${index}`, - 'aria-controls': `simple-tabpanel-${index}`, - }; -} - -const useStyles = makeStyles((theme) => ({ - root: { - flexGrow: 1, - backgroundColor: 'transparent', - }, -})); - -export default function GettingStartedEmissary21Tabs(props) { - const version = props.version; - const classes = useStyles(); - const [value, setValue] = React.useState(0); - - const handleChange = (event, newValue) => { - setValue(newValue); - }; - - return ( -
- - - } - label="Helm 3" - {...a11yProps(0)} - style={{ minWidth: '10%', textTransform: 'none' }} - /> - } - label="Kubernetes YAML" - {...a11yProps(1)} - style={{ minWidth: '10%', textTransform: 'none' }} - /> - - - - {/*Helm 3 install instructions*/} - - - {'# Add the Repo:' + - '\n' + - 'helm repo add datawire https://app.getambassador.io' + - '\n' + - 'helm repo update' + - '\n \n' + - '# Create Namespace and Install:' + - '\n' + - 'kubectl create namespace emissary && \\' + - '\n' + - `kubectl apply -f https://app.getambassador.io/yaml/emissary/${version}/emissary-crds.yaml` + - '\n' + - 'kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system' + - '\n' + - 'helm install emissary-ingress --namespace emissary datawire/emissary-ingress && \\' + - '\n' + - 'kubectl -n emissary wait --for condition=available --timeout=90s deploy -lapp.kubernetes.io/instance=emissary-ingress' + - '\n'} - - - - - {/*YAML install instructions*/} - - - {'kubectl create namespace emissary && \\' + - '\n' + - `kubectl apply -f https://app.getambassador.io/yaml/emissary/${version}/emissary-crds.yaml && \\` + - '\n' + - 'kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system' + - '\n' + - `kubectl apply -f https://app.getambassador.io/yaml/emissary/${version}/emissary-emissaryns.yaml && \\` + - '\n' + - 'kubectl -n emissary wait --for condition=available --timeout=90s deploy -lproduct=aes' + - '\n'} - - -
- ); -} diff --git a/content/en/docs/3.0/tutorials/gs-tabs2.js b/content/en/docs/3.0/tutorials/gs-tabs2.js deleted file mode 100644 index bfd95047..00000000 --- a/content/en/docs/3.0/tutorials/gs-tabs2.js +++ /dev/null @@ -1,174 +0,0 @@ -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'; - -function TabPanel(props) { - const { children, value, index, ...other } = props; - - return ( - - ); -} - -TabPanel.propTypes = { - children: PropTypes.node, - index: PropTypes.any.isRequired, - value: PropTypes.any.isRequired, -}; - -function a11yProps(index) { - return { - id: `simple-tab-${index}`, - 'aria-controls': `simple-tabpanel-${index}`, - }; -} - -const useStyles = makeStyles((theme) => ({ - root: { - flexGrow: 1, - backgroundColor: 'transparent', - }, -})); - -export default function SimpleTabs() { - const classes = useStyles(); - const [value, setValue] = React.useState(0); - - const handleChange = (event, newValue) => { - setValue(newValue); - }; - - return ( -
- - - - - - - - - - {/*Helm 3 token install instructions*/} - Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Helm. The slideout contains instructions with a - unique cloud-connect-token that is used to connect your - cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'helm upgrade ambassador --namespace ambassador datawire/ambassador \\' + - '\n' + - ' --set agent.cloudConnectToken=$TOKEN && \\' + - '\n' + - 'kubectl -n ambassador wait --for condition=available --timeout=90s deploy -lproduct=aes'} - - - - - {/*Helm 2 token install instructions*/} - Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Helm. The slideout contains instructions with a - unique cloud-connect-token that is used to connect your - cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'helm upgrade --namespace ambassador ambassador datawire/ambassador \\' + - '\n' + - ' --set crds.create=false --set agent.cloudConnectToken=$TOKEN && \\' + - '\n' + - 'kubectl -n ambassador wait --for condition=available --timeout=90s deploy -lproduct=aes'} - - - - - {/*YAML token install instructions*/} - Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Kubernetes YAML. The slideout contains instructions - with a unique cloud-connect-token that is used to connect - your cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'kubectl create configmap -n ambassador ambassador-agent-cloud-token \\' + - '\n' + - ' --from-literal=CLOUD_CONNECT_TOKEN=$TOKEN'} - - - - - {/*edgectl token install instructions*/} - Connecting $productName$ that was installed via edgectl is - identical to the Kubernetes YAML procedure. -
- Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Kubernetes YAML. The slideout contains instructions - with a unique cloud-connect-token that is used to connect - your cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'kubectl create configmap -n ambassador ambassador-agent-cloud-token \\' + - '\n' + - ' --from-literal=CLOUD_CONNECT_TOKEN=$TOKEN'} - - -
- ); -} diff --git a/content/en/docs/3.0/tutorials/quickstart-demo.md b/content/en/docs/3.0/tutorials/quickstart-demo.md deleted file mode 100644 index 70cbce8b..00000000 --- a/content/en/docs/3.0/tutorials/quickstart-demo.md +++ /dev/null @@ -1,176 +0,0 @@ -# $productName$ Tutorial - -In this article, you will explore some of the key features of $productName$ by walking through an example workflow and exploring the -Edge Policy Console. - -## Prerequisites - -You must have [$productName$ installed](../getting-started/) in your -Kubernetes cluster. - -## Routing Traffic from the Edge - -Like any other Kubernetes object, Custom Resource Definitions (CRDs) are used to -declaratively define $productName$’s desired state. The workflow you are going to -build uses a sample deployment and the `Mapping` CRD, which is the core resource -that you will use with $productName$ to manage your edge. It enables you to route -requests by host and URL path from the edge of your cluster to Kubernetes services. - -1. Copy the configuration below and save it to a file named `quote.yaml` so that -you can deploy these resources to your cluster. This basic configuration creates -the `quote` deployment and a service to expose that deployment on port 80. - - ```yaml - --- - apiVersion: apps/v1 - kind: Deployment - metadata: - name: quote - namespace: ambassador - spec: - replicas: 1 - selector: - matchLabels: - app: quote - strategy: - type: RollingUpdate - template: - metadata: - labels: - app: quote - spec: - containers: - - name: backend - image: docker.io/datawire/quote:$quoteVersion$ - ports: - - name: http - containerPort: 8080 - --- - apiVersion: v1 - kind: Service - metadata: - name: quote - namespace: ambassador - spec: - ports: - - name: http - port: 80 - targetPort: 8080 - selector: - app: quote - ``` - -1. Apply the configuration to the cluster with the command `kubectl apply -f quote.yaml`. - -1. Copy the configuration below and save it to a file called `quote-backend.yaml` -so that you can create a `Mapping` on your cluster. This `Mapping` tells $productName$ to route all traffic inbound to the `/backend/` path, on any host that can be used to reach $productName$, to the `quote` service. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Mapping - metadata: - name: quote-backend - namespace: ambassador - spec: - hostname: "*" - prefix: /backend/ - service: quote - ``` - -1. Apply the configuration to the cluster with the command -`kubectl apply -f quote-backend.yaml` - -1. Store the $productName$ `LoadBalancer` address to a local environment variable. -You will use this variable to test accessing your pod. - - ``` - export AMBASSADOR_LB_ENDPOINT=$(kubectl -n ambassador get svc ambassador -o "go-template={{range .status.loadBalancer.ingress}}{{or .ip .hostname}}{{end}}") - ``` - -1. Test the configuration by accessing the service through the $productName$ load -balancer. - - ``` - $ curl -Lk "https://$AMBASSADOR_LB_ENDPOINT/backend/" - { - "server": "idle-cranberry-8tbb6iks", - "quote": "Non-locality is the driver of truth. By summoning, we vibrate.", - "time": "2019-12-11T20:10:16.525471212Z" - } - ``` - -Success, you have created your first $productName$ `Mapping`, routing a -request from your cluster's edge to a service! - -Since the `Mapping` you just created controls how requests are routed, -changing the `Mapping` will immediately change the routing. To see this -in action, use `kubectl` to edit the `Mapping`: - -1. Run `kubectl edit Mapping quote-backend`. - -1. Change `prefix: /backend/` to `prefix: /quoteme/`. - -1. Save the file and let `kubectl` update your `Mapping`. - -1. Run `kubectl get Mappings --namespace ambassador`. You will see the -`quote-backend` `Mapping` has the updated prefix listed. Try to access the -endpoint again via `curl` with the updated prefix. - - ``` - $ kubectl get Mappings --namespace ambassador - NAME PREFIX SERVICE STATE REASON - quote-backend /quoteme/ quote - - $ curl -Lk "https://${AMBASSADOR_LB_ENDPOINT}/quoteme/" - { - "server": "snippy-apple-ci10n7qe", - "quote": "A principal idea is omnipresent, much like candy.", - "time": "2020-11-18T17:15:42.095153306Z" - } - ``` - -1. Change the prefix back to `/backend/` so that you can later use the `Mapping` -with other tutorials. - -## 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. In the Edge Policy Console, navigate to the **APIs** tab. You'll see the -OpenAPI documentation there for the "Quote Service API." Click **GET** to -expand out the documentation. - -1. Navigate to `https:///docs/` to see the -publicly visible Developer Portal. Make sure you include the trailing `/`. -This is a fully customizable portal that you can share with third parties who -need information about your APIs. - -## Next Steps - -Further explore some of the concepts you learned about in this article: -* [`Mapping` resource](../../topics/using/intro-mappings/): routes traffic from -the edge of your cluster to a Kubernetes service -* [`Host` resource](../../topics/running/host-crd/): sets the hostname by which -$productName$ will be accessed and secured with TLS certificates -* [Developer Portal](../../tutorials/dev-portal-tutorial/): -publishes an API catalog and OpenAPI documentation - -$productName$ has a comprehensive range of [features](/features/) to -support the requirements of any edge microservice. - -Learn more about [how developers use $productName$](../../topics/using/) to manage -edge policies. - -Learn more about [how site reliability engineers and operators run $productName$](../../topics/running/) -in production environments. - -To learn how $productName$ works, use cases, best practices, and more, check out -the [Quick Start](../getting-started) or read the [$productName$ Story](../../about/why-ambassador). - -For a custom configuration, you can install $productName$ -[manually](../../topics/install/yaml-install). diff --git a/content/en/docs/3.0/versions.yml b/content/en/docs/3.0/versions.yml deleted file mode 100644 index 8e036b2c..00000000 --- a/content/en/docs/3.0/versions.yml +++ /dev/null @@ -1,35 +0,0 @@ -# branch info -branch: master - -# self -version: 3.0.0 -productName: "Emissary-ingress" -productNamePlural: "Emissary-ingresses" -productNamespace: emissary -productDeploymentName: emissary-ingress -productHelmName: emissary-ingress - -# OSS (self) -ossVersion: 3.0.0 -ossDocsVersion: "3.0" -ossChartVersion: 8.0.0 -OSSproductName: "Emissary-ingress" -OSSproductNamePlural: "Emissary-ingresses" - -# AES (not self) -aesVersion: 3.0.0 -aesDocsVersion: "3.0" -aesChartVersion: 8.0.0 -AESproductName: "Ambassador Edge Stack" -AESproductNamePlural: "Ambassador Edge Stacks" - -# other products -qotmVersion: 1.7 -quoteVersion: 0.5.0 - -# Most recent version from previous major versions -# This is mostly to ensure that the migration matrix stays up-to-date -versionTwoX: 2.3.2 -chartVersionTwoX: 7.4.2 -versionOneX: 1.14.4 -chartVersionOneX: 6.9.5 diff --git a/content/en/docs/3.1/_index.md b/content/en/docs/3.1/_index.md deleted file mode 100644 index 723ccc28..00000000 --- a/content/en/docs/3.1/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: v3.1 docs -cascade: - version: v3.1 - versName: &name v3.1 - git_version_tag: v3.1.0 - exclude_search: true -linkTitle: *name -simple_list: true -weight: -310 # Weight for doc version vX.Y should be -XY0 ---- - -These docs cover everything from setting up and running Emissary-ingress to its operation and usage. diff --git a/content/en/docs/3.1/about/aes-emissary-eol.md b/content/en/docs/3.1/about/aes-emissary-eol.md deleted file mode 100644 index 056ad4f9..00000000 --- a/content/en/docs/3.1/about/aes-emissary-eol.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "Edge Stack and Emissary-ingress End of Life Policy | Ambassador" ---- - -# Ambassador Edge Stack and Emissary-ingress 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/content/en/docs/3.1/about/alternatives.md b/content/en/docs/3.1/about/alternatives.md deleted file mode 100644 index bafec087..00000000 --- a/content/en/docs/3.1/about/alternatives.md +++ /dev/null @@ -1,19 +0,0 @@ -# $productName$ vs. other software - -Alternatives to $productName$ fall into three basic categories: - -* Hosted API gateways, such as the [Amazon API gateway](https://aws.amazon.com/api-gateway/). -* Traditional API gateways, such as [Kong](https://konghq.org/). -* L7 proxies, such as [Traefik](https://traefik.io/), [NGINX](http://nginx.org/), [HAProxy](http://www.haproxy.org/), or [Envoy](https://www.envoyproxy.io), or Ingress controllers built on these proxies. - -Both hosted API gateways and traditional API gateways are: - -* Not self-service. The management interfaces on traditional API gateways are not designed for developer self-service, and provide limited safety and usability for developers. -* Not Kubernetes-native. They're typically configured using REST APIs, making it challenging to adopt cloud-native patterns such as GitOps and declarative configuration. -* [Designed for API management, rather than designed for microservices](../../topics/concepts/microservices-api-gateways). - -A Layer 7 proxy can be used as an API gateway, but typically requires additional bespoke development to support microservices use cases. In fact, many API gateways package the additional features needed for an API gateway on top of an L7 proxy. $productName$ uses Envoy, while Kong uses NGINX. If you're interested in deploying Envoy directly, we've written an [introductory tutorial](https://www.datawire.io/guide/traffic/getting-started-lyft-envoy-microservices-resilience/). - -## Istio - -[Istio](https://istio.io) is an open-source service mesh, built on Envoy. A service mesh is designed to manage East/West traffic (traffic between servers and your data center), while an API gateway manages North/South traffic (in and out of your data center). Documentation on how to deploy $productName$ with Istio is [here](../../howtos/istio). In general, we've found that North/South traffic is quite different from East/West traffic (i.e., you don't control the client in the North/South use case). diff --git a/content/en/docs/3.1/about/changes-2.x.md b/content/en/docs/3.1/about/changes-2.x.md deleted file mode 100644 index 389cc89b..00000000 --- a/content/en/docs/3.1/about/changes-2.x.md +++ /dev/null @@ -1,238 +0,0 @@ -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. - - - $productName$ 2.X supports only API versions getambassador.io/v2 - and getambassador.io/v3alpha1. If you are using any resources with - older API versions, you will need to upgrade them. - - -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 [structural CRDs](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. - - - Learn more about Listener.
- Learn more about Host. - - -### 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. - - - Learn more about Host. - - -### `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. - - - Learn more about Host.
- Learn more about Mapping. - - -### 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. - - - Learn more about Host. - - -### `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). - - - Learn more about Host.
- Learn more about TLSContext. - - -### `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). - - - Learn more about Mapping. - - -### `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. - - - Learn more about Mapping. - - -## 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). In $productName$ -2.X, you may switch back to Envoy V2 by setting the `AMBASSADOR_ENVOY_API_VERSION` -environment variable to "V2"; in $productName$ 3.X, support for the Envoy V2 API (and -the `AMBASSADOR_ENVOY_API_VERSION` environment variable) will be removed. - -### 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. - - - Learn more about Listener. - - -### `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/content/en/docs/3.1/about/changes-3.y.md b/content/en/docs/3.1/about/changes-3.y.md deleted file mode 100644 index 91105d28..00000000 --- a/content/en/docs/3.1/about/changes-3.y.md +++ /dev/null @@ -1,52 +0,0 @@ -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 AuthServices 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, -``` - - - Learn more about Envoy Proxy changes. - - -## 2. Envoy V2 Protocol Support Removed - -With the upgrade to Envoy **1.22**, the V2 Envoy Transport Protocol is no longer supported. -$productName$ 3.X **only** supports [V3 Envoy API](https://www.envoyproxy.io/docs/envoy/latest/api-v3/api). - - -The environment variable AMBASSADOR_ENVOY_API_VERSION has been removed and will no longer have the affect -of changing the transport protocol. - - - -The setting of 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. - diff --git a/content/en/docs/3.1/about/faq.md b/content/en/docs/3.1/about/faq.md deleted file mode 100644 index 513c75c5..00000000 --- a/content/en/docs/3.1/about/faq.md +++ /dev/null @@ -1,79 +0,0 @@ -# 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. -* 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! The core functionality of the $AESproductName$ is free and has no limits whatsoever. If you wish to use one of our additional, proprietary features such as Single Sign-On, you can get a free community license for up to 5 requests per second by registering your connected $AESproductName$ installation in [Ambassador Cloud](https://app.getambassador.io/cloud/). Please contact [sales](/contact-us/) if you need more than 5 RPS. - -For more details on core unlimited features and premium features, see the [editions page](/editions). - -### 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? - -[//]: # (+FIX+ Check for OSS) - -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$? - -[//]: # (+FIX+ Check for OSS) - -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 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/content/en/docs/3.1/about/features-and-benefits.md b/content/en/docs/3.1/about/features-and-benefits.md deleted file mode 100644 index a25d7752..00000000 --- a/content/en/docs/3.1/about/features-and-benefits.md +++ /dev/null @@ -1,43 +0,0 @@ -# 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 - -[//]: # (+FIX+ Forge is no more) - -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 - -[//]: # (+FIX+ we've come to realize that it's better to scale vertically) - -$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 using a custom authentication service. When configured, the $productName$ will check with your external authentication service prior to routing an incoming request. For more information, see the [authentication guide](../../topics/running/services/auth-service). - -## 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/content/en/docs/3.1/about/known-issues.md b/content/en/docs/3.1/about/known-issues.md deleted file mode 100644 index 6b89c65a..00000000 --- a/content/en/docs/3.1/about/known-issues.md +++ /dev/null @@ -1,9 +0,0 @@ -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. diff --git a/content/en/docs/3.1/about/support.md b/content/en/docs/3.1/about/support.md deleted file mode 100644 index 11927f95..00000000 --- a/content/en/docs/3.1/about/support.md +++ /dev/null @@ -1,27 +0,0 @@ -# Need help? - -If you need help deploying $productName$ at your organization, there are several different options available to you. - -## Support tiers - -### $productName$ community support - -When running $OSSproductName$, or $AESproductName$ with free community licenses, [join our Slack channel](http://a8r.io/slack) to talk with other users in the community and get your questions answered. - -If you can’t find an answer there, [contact us](/contact-us) to learn more about the support options available with $AESproductName$ Enterprise. - -### $AESproductName$ Enterprise - -With $AESproductName$ Enterprise, you have access to deployment and production support. To learn more, [contact sales](/contact-us). - -**Deployment and Update Support**: $AESproductName$ can accelerate your migration to Kubernetes, or your upgrade between versions of $AESproductName$. Deployment support helps you with the $AESproductName$ and Kubernetes migration, before you move to production. - -**Production Support**: We offer two types of production support contracts for users deploying the $AESproductName$ in production. We offer both business hour (8am - 5pm EST, M-F) and 24x7 Sev 1 support for the $AESproductName$. 24x7 Sev 1 support includes custom hotfix support for production outages if necessary. - -## File a Github Issue - -If you see a bug you want to fix, see room for documentation improvements, or have something else you want to change, you can [file an issue on github](https://github.com/datawire/ambassador/issues/new). - -## Pricing - -[Contact us](/contact-us) to learn how we can help, and for detailed pricing information. diff --git a/content/en/docs/3.1/about/why-ambassador.md b/content/en/docs/3.1/about/why-ambassador.md deleted file mode 100644 index 39e1949d..00000000 --- a/content/en/docs/3.1/about/why-ambassador.md +++ /dev/null @@ -1,54 +0,0 @@ -# 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://www.getambassador.io/learn/kubernetes-ingress/kubernetes-ingress-nodeport-load-balancers-and-ingress-controllers/)). - -## How Does $productName$ work? - -$productName$ is an open-source, Kubernetes-native [microservices API gateway](../../topics/concepts/microservices-api-gateways) built on 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://www.getambassador.io/learn/kubernetes-ingress/kubernetes-ingress-nodeport-load-balancers-and-ingress-controllers/)). - -## 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/content/en/docs/3.1/community.md b/content/en/docs/3.1/community.md deleted file mode 100644 index 759e4f0e..00000000 --- a/content/en/docs/3.1/community.md +++ /dev/null @@ -1,12 +0,0 @@ -# Community - -## Contributor's guide -Please review our [contributor's guide](https://github.com/emissary-ingress/emissary/blob/master/DEVELOPING.md) -on GitHub to learn how you can help make Emissary-ingress better. - -## Changelog -Our [changelog](https://github.com/emissary-ingress/emissary/blob/master/CHANGELOG.md) -describes new features, bug fixes, and updates to each version of Emissary-ingress. - -## Meetings -Check out our community [meeting schedule](https://github.com/emissary-ingress/emissary/blob/master/MEETING_SCHEDULE.md) for opportunities to interact with Emissary-ingress developers. diff --git a/content/en/docs/3.1/doc-links.yml b/content/en/docs/3.1/doc-links.yml deleted file mode 100644 index 0231a8ce..00000000 --- a/content/en/docs/3.1/doc-links.yml +++ /dev/null @@ -1,223 +0,0 @@ - - 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: $productName$ user guide - items: - - title: Deployment - items: - - title: Deployment architecture - link: /topics/running/ambassador-deployment - - title: The $productName$ container environment - 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: 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: 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/basic-auth - - title: Rate limiting - items: - - title: Rate limiting service - link: /topics/running/services/rate-limit-service/ - - title: Basic rate limiting - link: /topics/using/rate-limits/ - - 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: 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: 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: 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: 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: Licenses - link: licenses diff --git a/content/en/docs/3.1/features-icons/basic-authentication.svg b/content/en/docs/3.1/features-icons/basic-authentication.svg deleted file mode 100644 index 2bd19edf..00000000 --- a/content/en/docs/3.1/features-icons/basic-authentication.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_897228_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.1/features-icons/canary-release.svg b/content/en/docs/3.1/features-icons/canary-release.svg deleted file mode 100644 index f8de57d9..00000000 --- a/content/en/docs/3.1/features-icons/canary-release.svg +++ /dev/null @@ -1,27 +0,0 @@ - - - - Group 25 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.1/features-icons/cors.svg b/content/en/docs/3.1/features-icons/cors.svg deleted file mode 100644 index e559d924..00000000 --- a/content/en/docs/3.1/features-icons/cors.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_111967_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.1/features-icons/datadog.png b/content/en/docs/3.1/features-icons/datadog.png deleted file mode 100644 index eea05f8c..00000000 Binary files a/content/en/docs/3.1/features-icons/datadog.png and /dev/null differ diff --git a/content/en/docs/3.1/features-icons/datadog.svg b/content/en/docs/3.1/features-icons/datadog.svg deleted file mode 100644 index e46e8118..00000000 --- a/content/en/docs/3.1/features-icons/datadog.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Screen Shot 2018-04-05 at 8.22.25 AM - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.1/features-icons/diagnostics.svg b/content/en/docs/3.1/features-icons/diagnostics.svg deleted file mode 100644 index 940e1bc2..00000000 --- a/content/en/docs/3.1/features-icons/diagnostics.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_196445_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.1/features-icons/distributed-tracing.png b/content/en/docs/3.1/features-icons/distributed-tracing.png deleted file mode 100644 index 6b69e28c..00000000 Binary files a/content/en/docs/3.1/features-icons/distributed-tracing.png and /dev/null differ diff --git a/content/en/docs/3.1/features-icons/grpc.png b/content/en/docs/3.1/features-icons/grpc.png deleted file mode 100644 index b2f5a0d9..00000000 Binary files a/content/en/docs/3.1/features-icons/grpc.png and /dev/null differ diff --git a/content/en/docs/3.1/features-icons/prometheus.svg b/content/en/docs/3.1/features-icons/prometheus.svg deleted file mode 100644 index d5252a66..00000000 --- a/content/en/docs/3.1/features-icons/prometheus.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - prometheus_logo_grey - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.1/features-icons/rate-limiting.svg b/content/en/docs/3.1/features-icons/rate-limiting.svg deleted file mode 100644 index f1b6eacb..00000000 --- a/content/en/docs/3.1/features-icons/rate-limiting.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - Group 10 - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.1/features-icons/regex-routing.svg b/content/en/docs/3.1/features-icons/regex-routing.svg deleted file mode 100644 index 113b53b5..00000000 --- a/content/en/docs/3.1/features-icons/regex-routing.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_699774_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.1/features-icons/request-transformers.svg b/content/en/docs/3.1/features-icons/request-transformers.svg deleted file mode 100644 index 0b13e2dc..00000000 --- a/content/en/docs/3.1/features-icons/request-transformers.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_96239_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.1/features-icons/shadowing.svg b/content/en/docs/3.1/features-icons/shadowing.svg deleted file mode 100644 index 9e85eee1..00000000 --- a/content/en/docs/3.1/features-icons/shadowing.svg +++ /dev/null @@ -1,15 +0,0 @@ - - - - shadow - Created with Sketch. - - - - - - - - - - diff --git a/content/en/docs/3.1/features-icons/statsd.png b/content/en/docs/3.1/features-icons/statsd.png deleted file mode 100644 index 28374438..00000000 Binary files a/content/en/docs/3.1/features-icons/statsd.png and /dev/null differ diff --git a/content/en/docs/3.1/features-icons/statsd.svg b/content/en/docs/3.1/features-icons/statsd.svg deleted file mode 100644 index cabc90db..00000000 --- a/content/en/docs/3.1/features-icons/statsd.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - 88eb31f74479e422e4e9abfc6c2b00ee - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.1/features-icons/third-party-auth.svg b/content/en/docs/3.1/features-icons/third-party-auth.svg deleted file mode 100644 index 5359a24a..00000000 --- a/content/en/docs/3.1/features-icons/third-party-auth.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_511233_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.1/features-icons/timeouts.svg b/content/en/docs/3.1/features-icons/timeouts.svg deleted file mode 100644 index 47f63056..00000000 --- a/content/en/docs/3.1/features-icons/timeouts.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_587034_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.1/features-icons/tls-termination.svg b/content/en/docs/3.1/features-icons/tls-termination.svg deleted file mode 100644 index 6a631a96..00000000 --- a/content/en/docs/3.1/features-icons/tls-termination.svg +++ /dev/null @@ -1,17 +0,0 @@ - - - - noun_63544_cc - Created with Sketch. - - - - - - - - - - - - diff --git a/content/en/docs/3.1/features-icons/url-rewrite.svg b/content/en/docs/3.1/features-icons/url-rewrite.svg deleted file mode 100644 index 023e2e05..00000000 --- a/content/en/docs/3.1/features-icons/url-rewrite.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1295942_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.1/features-icons/websockets.svg b/content/en/docs/3.1/features-icons/websockets.svg deleted file mode 100644 index af17b9c0..00000000 --- a/content/en/docs/3.1/features-icons/websockets.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - noun_50814_cc - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.1/howtos/basic-auth.md b/content/en/docs/3.1/howtos/basic-auth.md deleted file mode 100644 index 70ce27ce..00000000 --- a/content/en/docs/3.1/howtos/basic-auth.md +++ /dev/null @@ -1,191 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Basic authentication (for $productName$) - -[//]: # (+FIX+ link to "authentication and authorization" concept) - - - This guide applies to $OSSproductName$, use of this guide with $AESproductName$ is not supported. $AESproductName$ does authentication using the Filter resource instead of the AuthService resource as described below. - - -$productName$ can authenticate incoming requests before routing them to a backing -service. In this tutorial, we'll configure $productName$ to use an external third -party authentication service. We're assuming also that you are running the -quote application in your cluster as described in the -[$productName$ tutorial](../../tutorials/quickstart-demo/). - -## Before you get started - -This tutorial assumes you have already followed the $productName$ [Installation](../../topics/install/) guide. If you haven't done that already, you should do so now. - -Once complete, you'll have a Kubernetes cluster running $productName$. Let's walk through adding authentication to this setup. - -## 1. Deploy the authentication service - -$productName$ delegates the actual authentication logic to a third party authentication service. We've written a [simple authentication service](https://github.com/datawire/ambassador-auth-service) that: - -- listens for requests on port 3000; -- expects all URLs to begin with `/extauth/`; -- performs HTTP Basic Auth for all URLs starting with `/backend/get-quote/` (other URLs are always permitted); -- accepts only user `username`, password `password`; and -- makes sure that the `x-qotm-session` header is present, generating a new one if needed. - -$productName$ routes _all_ requests through the authentication service: it relies on the auth service to distinguish between requests that need authentication and those that do not. If $productName$ cannot contact the auth service, it will return a 503 for the request; as such, **it is very important to have the auth service running before configuring $productName$ to use it.** - -Here's the YAML we'll start with: - -```yaml ---- -apiVersion: v1 -kind: Service -metadata: - name: example-auth -spec: - type: ClusterIP - selector: - app: example-auth - ports: - - port: 3000 - name: http-example-auth - targetPort: http-api ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: example-auth -spec: - replicas: 1 - strategy: - type: RollingUpdate - selector: - matchLabels: - app: example-auth - template: - metadata: - labels: - app: example-auth - spec: - containers: - - name: example-auth - image: docker.io/datawire/ambassador-auth-service:2.0.0 - imagePullPolicy: Always - ports: - - name: http-api - containerPort: 3000 - resources: - limits: - cpu: "0.1" - memory: 100Mi -``` - -Note that the cluster does not yet contain any $productName$ AuthService definition. This is intentional: we want the service running before we tell $productName$ about it. - -The YAML above is published at getambassador.io, so if you like, you can just do - -``` -kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/demo/demo-auth.yaml -``` - -to spin everything up. (Of course, you can also use a local file, if you prefer.) - -Wait for the pod to be running before continuing. The output of `kubectl get pods` should look something like - -``` -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -example-auth-6c5855b98d-24clp 1/1 Running 0 4m -``` -Note that the `READY` field says `1/1` which means the pod is up and running. - -## 2. Configure $productName$ authentication - -Once the auth service is running, we need to tell $productName$ about it. The easiest way to do that is point it to the `example-auth` service with the following: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: AuthService -metadata: - name: authentication -spec: - auth_service: "example-auth:3000" - path_prefix: "/extauth" - allowed_request_headers: - - "x-qotm-session" - allowed_authorization_headers: - - "x-qotm-session" -``` - -This configuration tells $productName$ about the auth service, notably that it needs the `/extauth` prefix, and that it's OK for it to pass back the `x-qotm-session` header. Note that `path_prefix` and `allowed_*_headers` are optional. - -If the auth service uses a framework like [Gorilla Toolkit](http://www.gorillatoolkit.org) which enforces strict slashes as HTTP path separators, it is possible to end up with an infinite redirect where the auth service's framework redirects any request with non-conformant slashing. This would arise if the above example had `path_prefix: "/extauth/"`, the auth service would see a request for `/extauth//backend/get-quote/` which would then be redirected to `/extauth/backend/get-quote/` rather than actually be handled by the authentication handler. For this reason, remember that the full path of the incoming request including the leading slash, will be appended to `path_prefix` regardless of non-conformant slashing. - -You can apply this file from getambassador.io with - -``` -kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/demo/demo-auth-enable.yaml -``` - -or, again, apply it from a local file if you prefer. - -Note that the cluster does not yet contain any $productName$ AuthService definition. - -## 3. Test authentication - -If we `curl` to a protected URL: - -``` -$ curl -Lv $AMBASSADORURL/backend/get-quote/ -``` - -We get a 401 since we haven't authenticated. - -``` -* TCP_NODELAY set -* Connected to 54.165.128.189 (54.165.128.189) port 32281 (#0) -> GET /backend/get-quote/ HTTP/1.1 -> Host: 54.165.128.189:32281 -> User-Agent: curl/7.63.0 -> Accept: */* -> -< HTTP/1.1 401 Unauthorized -< www-authenticate: Basic realm="Ambassador Realm" -< content-length: 0 -< date: Thu, 23 May 2019 15:24:55 GMT -< server: envoy -< -* Connection #0 to host 54.165.128.189 left intact -``` - -If we authenticate to the service, we will get a quote successfully: - -``` -$ curl -Lv -u username:password $AMBASSADORURL/backend/get-quote/ - -* TCP_NODELAY set -* Connected to 54.165.128.189 (54.165.128.189) port 32281 (#0) -* Server auth using Basic with user 'username' -> GET /backend/get-quote/ HTTP/1.1 -> Host: 54.165.128.189:32281 -> Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= -> User-Agent: curl/7.63.0 -> Accept: */* -> -< HTTP/1.1 200 OK -< content-type: application/json -< date: Thu, 23 May 2019 15:25:06 GMT -< content-length: 172 -< x-envoy-upstream-service-time: 0 -< server: envoy -< -{ - "server": "humble-blueberry-o2v493st", - "quote": "Nihilism gambles with lives, happiness, and even destiny itself!", - "time": "2019-05-23T15:25:06.544417902Z" -* Connection #0 to host 54.165.128.189 left intact -} -``` - -## More - -For more details about configuring authentication, see the [`External` filter](/docs/edge-stack/latest/topics/using/filters/) documentation. diff --git a/content/en/docs/3.1/howtos/cert-manager.md b/content/en/docs/3.1/howtos/cert-manager.md deleted file mode 100644 index 975dd3ff..00000000 --- a/content/en/docs/3.1/howtos/cert-manager.md +++ /dev/null @@ -1,230 +0,0 @@ -# Using cert-manager - -[//]: # (+FIX+ link to "TLS and certificates" concept) - -$AESproductName$ has simple and easy built-in support for automatically [using ACME] with the -`http-01` challenge to create and renew TLS certificates. However, this support is not available -in $OSSproductName$, and it is limited to the ACME `http-01` challenge type. If you're running -$OSSproductName$, or if you require more flexible certificate management (such as using ACME's -`dns-01` challenge, or using a non-ACME certificate source), external certificate management -tools are also supported. - -[using ACME]: ../../topics/running/host-crd/#acme-support - -One such tool is Jetstack's [cert-manager](https://github.com/jetstack/cert-manager), which is a general-purpose tool -for managing certificates in Kubernetes. Cert-manager will automatically create and renew TLS certificates and store -them as Kubernetes secrets for easy use in a cluster. $productName$ will automatically watch for secret -changes and reload certificates upon renewal. - -> **Note:** This document assumes cert-manager v0.15 or greater. This document has been updated to use CRD standards -> specified in v0.15. [Legacy CRD support](https://cert-manager.io/docs/installation/upgrading/upgrading-0.14-0.15/) -> was removed in cert-manager v0.15, see their [upgrading](https://cert-manager.io/docs/installation/upgrading/) -> document for more info. - -## Install cert-manager - -There are many different ways to [install cert-manager](https://cert-manager.io/docs/installation/). For simplicity, we will use Helm. - -1. Create the cert-manager CRDs. - ``` - kubectl apply -f https://github.com/jetstack/cert-manager/releases/latest/download/cert-manager.crds.yaml - ``` - -2. Add the `jetstack` Helm repository. - ``` - helm repo add jetstack https://charts.jetstack.io && helm repo update - ``` - -3. Install cert-manager. - - ``` - kubectl create ns cert-manager - helm install cert-manager --namespace cert-manager jetstack/cert-manager - ``` - -## Issuing certificates - -cert-manager issues certificates from a CA such as [Let's Encrypt](https://letsencrypt.org/). It does this using the ACME protocol which supports various challenge mechanisms for verifying ownership of the domain. - -### Issuer - -An `Issuer` or `ClusterIssuer` identifies which Certificate Authority cert-manager will use to issue a certificate. `Issuer` is a namespaced resource allowing you to use different CAs in each namespace, a `ClusterIssuer` is used to issue certificates in any namespace. Configuration depends on which ACME [challenge](#challenge) you are using. - -### Certificate - -A [Certificate](https://cert-manager.io/docs/concepts/certificate/) is a namespaced resource that references an `Issuer` or `ClusterIssuer` for issuing certificates. `Certificate`s define the DNS name(s) a key and certificate should be issued for, as well as the secret to store those files (e.g. `ambassador-certs`). Configuration depends on which ACME [challenge](#challenge) you are using. - -By duplicating issuers, certificates, and secrets one can support multiple domains with [SNI](../../topics/running/tls/sni). - -## Challenge - -cert-manager supports two kinds of ACME challenges that verify domain ownership in different ways: HTTP-01 and DNS-01. - -### DNS-01 challenge - -The DNS-01 challenge verifies domain ownership by proving you have control over its DNS records. Issuer configuration will depend on your [DNS provider](https://cert-manager.io/docs/configuration/acme/dns01/#supported-dns01-providers). This example uses [AWS Route53](https://cert-manager.io/docs/configuration/acme/dns01/route53/). - -1. Create the IAM policy specified in the cert-manager [AWS Route53](https://cert-manager.io/docs/configuration/acme/dns01/route53/) documentation. - -2. Note the `accessKeyID` and create a `secret` named `prod-route53-credentials-secret` in the cert-manager namespace that has a key value: `secret-access-key` from your AWS IaM credentials. - -3. Create and apply a `ClusterIssuer`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: ClusterIssuer - metadata: - name: letsencrypt-prod - spec: - acme: - email: email@example.com - server: https://acme-v02.api.letsencrypt.org/directory - privateKeySecretRef: - name: letsencrypt-prod - solvers: - - selector: - dnsZones: - - "myzone.route53.com" - dns01: - route53: - region: us-east-1 - accessKeyID: {accessKeyID} - hostedZoneID: {Hosted Zone ID} # optional, allows you to reduce the scope of permissions in Amazon IAM - secretAccessKeySecretRef: - name: prod-route53-credentials-secret - key: secret-access-key - ``` - -4. Create and apply a `Certificate`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: Certificate - metadata: - name: myzone.route53.com - # cert-manager will put the resulting Secret in the same Kubernetes - # namespace as the Certificate. You should create the certificate in - # whichever namespace you want to configure a Host. - spec: - secretName: ambassador-certs - issuerRef: - name: letsencrypt-prod - kind: ClusterIssuer - commonName: myzone.route53.com - dnsNames: - - myzone.route53.com - ``` - -5. Verify the secret is created. - - ``` - $ kubectl get secrets -n ambassador - NAME TYPE DATA AGE - ambassador-certs kubernetes.io/tls 2 1h - ``` - -### HTTP-01 challenge - -The HTTP-01 challenge verifies ownership of the domain by sending a request for a specific file on that domain. cert-manager accomplishes this by sending a request to a temporary pod with the prefix `/.well-known/acme-challenge/`. To perform this challenge: - -1. Create and apply a `ClusterIssuer`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: ClusterIssuer - metadata: - name: letsencrypt-prod - spec: - acme: - email: email@example.com - server: https://acme-v02.api.letsencrypt.org/directory - privateKeySecretRef: - name: letsencrypt-prod - solvers: - - http01: - ingress: - class: nginx - selector: {} - ``` - -2. Create and apply a `Certificate`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: Certificate - metadata: - name: ambassador-certs - # cert-manager will put the resulting Secret in the same Kubernetes - # namespace as the Certificate. You should create the certificate in - # whichever namespace you want to configure a Host. - namespace: ambassador - spec: - secretName: ambassador-certs - issuerRef: - name: letsencrypt-prod - kind: ClusterIssuer - dnsNames: - - example.com - ``` - -3. Apply both the `ClusterIssuer` and `Certificate` - - After applying both of these YAML manifests, you will notice that cert-manager has spun up a temporary pod named `cm-acme-http-solver-xxxx` but no certificate has been issued. Check the cert-manager logs and you will see a log message that looks like this: - - ``` - $ kubectl logs cert-manager-756d6d885d-v7gmg - ... - Preparing certificate default/ambassador-certs with issuer - Calling GetOrder - Calling GetAuthorization - Calling HTTP01ChallengeResponse - Cleaning up old/expired challenges for Certificate default/ambassador-certs - Calling GetChallenge - wrong status code '404' - Looking up Ingresses for selector certmanager.k8s.io/acme-http-domain=161156668,certmanager.k8s.io/acme-http-token=1100680922 - Error preparing issuer for certificate default/ambassador-certs: http-01 self check failed for domain "example.com - ``` - -4. Create a Mapping for the `/.well-known/acme-challenge/` route. - - cert-manager uses an `Ingress` to issue the challenge to `/.well-known/acme-challenge/` that is incompatible with Ambassador. We will need to create a `Mapping` so the cert-manager can reach the temporary pod. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Mapping - metadata: - name: acme-challenge-mapping - spec: - hostname: "*" - prefix: /.well-known/acme-challenge/ - rewrite: "" - service: acme-challenge-service - - --- - apiVersion: v1 - kind: Service - metadata: - name: acme-challenge-service - spec: - ports: - - port: 80 - targetPort: 8089 - selector: - acme.cert-manager.io/http01-solver: "true" - ``` - - Apply the YAML and wait a couple of minutes. cert-manager will retry the challenge and issue the certificate. - -5. Verify the secret is created: - - ``` - $ kubectl get secrets - NAME TYPE DATA AGE - ambassador-certs kubernetes.io/tls 2 1h - ambassador-token-846d5 kubernetes.io/service-account-token 3 2h - ``` diff --git a/content/en/docs/3.1/howtos/client-cert-validation.md b/content/en/docs/3.1/howtos/client-cert-validation.md deleted file mode 100644 index 10fe639d..00000000 --- a/content/en/docs/3.1/howtos/client-cert-validation.md +++ /dev/null @@ -1,110 +0,0 @@ -# Client certificate validation - -[//]: # (+FIX+ link to "TLS and client certs" concept) - -Sometimes, for additional security or authentication purposes, you will want -the server to validate who the client is before establishing an encrypted -connection. - -To support this, $productName$ can be configured to use a provided CA certificate -to validate certificates sent from your clients. This allows for client-side -mTLS where both $productName$ and the client provide and validate each other's -certificates. - -## Prerequisites - -- [openssl](https://www.openssl.org/source/) For creating client certificates -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [$productName$](../../tutorials/getting-started) -- [cURL](https://curl.haxx.se/download.html) - - -## Configuration - -1. Create a certificate and key. - - This can be done with a single command with `openssl`: - - ``` - openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 - ``` - - Enter a passcode for PEM files and fill in the certificate information. - Since this certificate will only be shared between a client and $productName$, - the Common Name must be set to something. Everything else can be left blank. - - **Note:** If using MacOS, - [you must](https://curl.haxx.se/mail/archive-2014-10/0053.html) - add the certificate and key as a PKCS encoded file to your Keychain. To do - this: - - 1. Encode `cert.pem` and `key.pem` created above in PKCS format - - ``` - openssl pkcs12 -inkey key.pem -in cert.pem -export -out certificate.p12 - ``` - - 2. Open "Keychain Access" on your system and select "File"->"Import Items..." - - 3. Navigate to your working directory and select the `certificate.p12` file - we just created above. - -2. Create a secret to hold the client CA certificate. - - ``` - kubectl create secret generic client-cacert --from-file=tls.crt=cert.pem - ``` - -3. Configure $productName$ to use this certificate for client certificate validation. - - First create a `Host` to manage your domain: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Host - metadata: - name: example-host - spec: - hostname: host.example.com - acmeProvider: - email: julian@example.com - ``` - - Then create a `TLSContext` to configure advanced TLS options like client - certificate validation: - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: TLSContext - metadata: - name: example-host-context - spec: - hosts: - - host.example.com - secret: host.example.com - ca_secret: client-cacert - cert_required: false # Optional: Configures $productName$ to reject the request if the client does not provide a certificate. Default: false - ``` - - **Note**: Client certificate validation requires $productName$ be configured to terminate TLS - - $productName$ is now be configured to validate certificates that the client provides. - -4. Test that $productName$ is validating the client certificates with `curl` - - **Linux**: - ``` - curl -v --cert cert.pem --key key.pem https://host.example.com/ - ``` - - **MacOS**: - ``` - curl -v --cert certificate.p12:[password] https://host.example.com/ - ``` - - Looking through the verbose output, you can see we are sending a client - certificate and $productName$ is validating it. - - If you need further proof, simply create a new set of certificates and - try sending the curl with those. You will see $productName$ deny the request. diff --git a/content/en/docs/3.1/howtos/configure-communications.md b/content/en/docs/3.1/howtos/configure-communications.md deleted file mode 100644 index 1ac09d2c..00000000 --- a/content/en/docs/3.1/howtos/configure-communications.md +++ /dev/null @@ -1,763 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -Configuring $productName$ Communications -======================================== - -For $productName$ to do its job of managing network communications for your services, it first needs to know how its own communications should be set up. This is handled by a combination of resources: the `Listener`, the `Host`, and the `TLSContext`. - -- `Listener`: defines where, and how, $productName$ should listen for requests from the network. -- `Host`: defines which hostnames $productName$ should care about, and how to handle different kinds of requests for those hosts. `Host`s can be associated with one or more `Listener`s. -- `TLSContext`: defines whether, and how, $productName$ will manage TLS certificates and options. `TLSContext`s can be associated with one or more `Host`s. - -Once the basic communications setup is in place, $productName$ `Mapping`s and `TCPMapping`s can be associated with `Host`s to actually do routing. - - - Remember that Listener and Host resources are  - required for a functioning $productName$ installation that can route traffic!
- Learn more about Listener.
- Learn more about Host. - - - - Remember than $productName$ does not make sure that a wildcard Host exists! If the - wildcard behavior is needed, a Host with a hostname of "*" - must be defined by the user. - - - - Several different resources work together to configure communications. A working knowledge of all of them - can be very useful:
- Learn more about Listener.
- Learn more about Host.
- Learn more about Mapping.
- Learn more about TCPMapping.
- Learn more about TLSContext. - - -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]: ../../topics/running/tls -[certificates]: ../../topics/running/tls#certificates-and-secrets -[check the logs]: ../../topics/running/debugging#review-logs - -Examples / Cookbook -------------------- - -### Basic HTTP and HTTPS - -A useful configuration is to support either HTTP or HTTPS, in this case on either port 8080 or port 8443. This -tends to make it as easy as possible to communicate with the services behind the $productName$ instance. It uses -two `Listener`s and at least one `Host`. - - -#### `Listener`s: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: http-listener -spec: - port: 8080 - protocol: HTTPS # NOT A TYPO, see below - securityModel: XFP - hostBinding: - namespace: - from: SELF # See below ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: - namespace: - from: SELF # See below -``` - -- Both `Listener`s use `protocol: HTTPS` to allow Envoy to inspect incoming connections, determine - whether or not TLS is in play, and set `X-Forwarded-Proto` appropriately. The `securityModel` then specifies - that `X-Forwarded-Proto` will determine whether requests will be considered secure or insecure. - -- The `hostBinding` shown here will allow any `Host` in the same namespace as the `Listener`s - to be associated with both `Listener`s; in turn, that will allow access to that `Host`'s - `Mapping`s from either port. For greater control, use a `selector` instead. - -- Note that the `Listener`s do not specify anything about TLS certificates. The `Host` - handles that; see below. - - - Learn more about Listener - - -#### `Host` - -This example will assume that we expect to be reachable as `foo.example.com`, and that the `foo.example.com` -certificate is stored in the Kubernetes `Secret` named `foo-secret`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: "foo.example.com" - tlsSecret: - name: foo-secret - requestPolicy: - insecure: - action: Redirect -``` - -- The `tlsSecret` specifies the certificate in use for TLS termination. -- The `requestPolicy` specifies routing HTTPS and redirecting HTTP to HTTPS. -- Since the `Host` does not specify a `selector`, only `Mapping`s with a `hostname` that matches - `foo.example.com` will be associated with this `Host`. -- **Note well** that simply defining a `TLSContext` is not sufficient to terminate TLS: you must define either - a `Host` or an `Ingress`. -- Note that if no `Host` is present, but a TLS secret named `fallback-secret` is available, the system will - currently define a `Host` using `fallback-secret`. **This behavior is subject to change.** - - - Learn more about Host - - -### HTTP-Only - -Another straightforward configuration is to support only HTTP, in this case on port 8080. This uses a single -`Listener` and a single `Host`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: http-listener -spec: - port: 8080 - protocol: HTTP - securityModel: INSECURE - hostBinding: - namespace: - from: SELF # See below ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: "foo.example.com" - requestPolicy: - insecure: - action: Route -``` - -- Here, we listen only on port 8080, and only for HTTP. HTTPS will be rejected. -- Since requests are only allowed using HTTP, we declare all requests `INSECURE` by definition. -- The `Host` specifies routing HTTP, rather than redirecting it. - - - - Learn more about Listener
- Learn more about Host - - -### TLS using ACME ($AESproductName$ only) - -This scenario uses ACME to get certificates for `foo.example.com` and `bar.example.com`. HTTPS traffic to either -host is routed; HTTP traffic to `foo.example.com` will be redirected to HTTPS, but HTTP traffic to `bar.example.com` -will be rejected outright. - -Since this example uses ACME, **it is only supported in $AESproductName$**. - -For demonstration purposes, we show this example listening for HTTPS on port 9999, using `X-Forwarded-Proto`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener-9999 -spec: - port: 9999 - protocol: HTTPS - securityModel: XFP - hostBinding: # Edit as needed - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - acmeProvider: - email: julian@example.com ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - acmeProvider: - email: julian@example.com - requestPolicy: - insecure: - action: Reject -``` - -(`Mapping`s are not shown.) - -- Our `Listener`s will accept HTTPS and HTTP on port 9999, and the protocol used will dictate whether - the requests are secure (HTTPS) or insecure (HTTP). -- `foo-host` defaults to ACME with Let's Encrypt, since `acmeProvider.authority` is not provided. -- `foo-host` defaults to redirecting insecure requests, since the default for `requestPolicy.insecure.action` is `Redirect`. -- `bar-host` uses Let's Encrypt as well, but it will reject insecure requests. - -**If you use ACME for multiple Hosts, add a wildcard Host too.** -This is required to manage a known issue. This issue will be resolved in a future Ambassador Edge Stack release. - - - Learn more about Listener
- Learn more about Host - - -### Multiple TLS Certificates - -This scenario uses TLS without ACME. Each of our two `Host`s uses a distinct TLS certificate. HTTPS -traffic to either`foo.example.com` or `bar.example.com` is routed, but this time `foo.example.com` will redirect -HTTP requests, while `bar.example.com` will route them. - -Since this example does not use ACME, it is supported in $productName$ as well as $AESproductName$. - -For demonstration purposes, we show this example listening for HTTPS on port 4848, using `X-Forwarded-Proto`. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: foo-example-secret -data: - tls.crt: -certificate PEM- - tls.key: -secret key PEM- ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: bar-example-secret -data: - tls.crt: -certificate PEM- - tls.key: -secret key PEM- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener-4848 -spec: - port: 4848 - protocol: HTTPS - securityModel: XFP - hostBinding: # Edit as needed - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - tlsSecret: - name: foo-example-secret ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - tlsSecret: - name: bar-example-secret - requestPolicy: - insecure: - action: Route -``` - -- `foo-host` and `bar-host` simply reference the `tlsSecret` to use for termination. - - If the secret involved contains a wildcard cert, or a cert with multiple SAN, both `Host`s could - reference the same `tlsSecret`. -- `foo-host` relies on the default insecure routing action of `Redirect`. -- `bar-host` must explicitly specify routing HTTP. - - - - Learn more about Listener
- Learn more about Host - - -### Using a `TLSContext` - -If you need to share other TLS settings between two `Host`s, you can reference a `TLSContext` as well as -the `tlsSecret`. This is the same as the previous example, but we use a `TLSContext` to set `ALPN` information, -and we assume that the `Secret` contains a wildcard cert. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: wildcard-example-secret -data: - tls.crt: -wildcard here- - tls.key: -wildcard here- ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-context -spec: - secret: wildcard-example-secret - alpn_protocols: [h2, istio] ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener-4848 -spec: - port: 4848 - protocol: HTTPS - securityModel: XFP - hostBinding: # Edit as needed - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - tlsContext: - name: example-context - tlsSecret: - name: wildcard-example-secret ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - tlsContext: - name: example-context - tlsSecret: - name: wildcard-example-secret - requestPolicy: - insecure: - action: Route -``` - -- Note that specifying the `tlsSecret` is still necessary, even when `tlsContext` is specified. - - - - Learn more about Listener
- Learn more about Host - - -### ACME With a TLSContext ($AESproductName$ Only) - -In $AESproductName$, you can use a `TLSContext` with ACME as well. This example is the same as "TLS using ACME", -but we use a `TLSContext` to set `ALPN` information. Again, ACME is only supported in $AESproductName$. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-context -spec: - secret: example-acme-secret - alpn_protocols: [h2, istio] ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - acmeProvider: - email: julian@example.com - tlsContext: - name: example-context - tlsSecret: - name: example-acme-secret -``` - -- Note that we don't provide the `Secret`: the ACME client will create it for us. - - - - Learn more about Listener
- Learn more about Host - - -### Using an L7 Load Balancer to Terminate TLS - -In this scenario, a layer 7 load balancer ahead of $productName$ will terminate TLS, so $productName$ will always see HTTP with a known good `X-Forwarded-Protocol`. We'll use that to route HTTPS and redirect HTTP. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: lb-listener -spec: - port: 8443 - protocol: HTTP - securityModel: XFP - l7Depth: 1 - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: "foo.example.com" - requestPolicy: - insecure: - action: Redirect -``` - -- We set `l7Depth` to 1 to indicate that there's a single trusted L7 load balancer ahead of us. -- We specifically set this Listener to HTTP-only, but we stick with port 8443 just because we expect people setting up TLS at all to expect to use port 8443. (There's nothing special about the port number, pick whatever you like.) -- Our `Host` does not specify a `tlsSecret`, so $productName$ will not try to terminate TLS. -- Since the `Listener` still pays attention to `X-Forwarded-Proto`, both secure and insecure requests - are possible, and we use the `Host` to route HTTPS and redirect HTTP. - - - - Learn more about Listener
- Learn more about Host - - -### Using a Split L4 Load Balancer to Terminate TLS - -Here, we assume that $productName$ is behind a load balancer setup that handles TLS at layer 4: - -- Incoming cleartext traffic is forwarded to $productName$ on port 8080. -- Incoming TLS traffic is terminated at the load balancer, then forwarded to $productName$ _as cleartext_ on port 8443. -- This might involve multiple L4 load balancers, but the actual number doesn't matter. -- The actual port numbers we use don't matter either, as long as $productName$ and the load balancer(s) agree on which port is for which traffic. - -We're going to route HTTPS for both `foo.example.com` and `bar.example.com`, redirect HTTP for `foo.example.com`, and reject HTTP for `bar.example.com`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: split-lb-one-listener -spec: - protocol: HTTP - port: 8080 - securityModel: INSECURE - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: split-lb-two-listener -spec: - protocol: HTTP - port: 8443 - securityModel: SECURE - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - requestPolicy: - insecure: - action: Reject -``` - -- Since L4 load balancers cannot set `X-Forwarded-Protocol`, we don't use it at all here: instead, we dictate that 8080 and 8443 both speak cleartext HTTP, but everything arriving at port 8080 is insecure and everything at port 8443 is secure. - - - - Learn more about Listener
- Learn more about Host - - -### Listening on Multiple Ports - -There's no reason you need to use ports 8080 and 8443, or that you're limited to two ports. Here we'll use ports 9001 and 9002 for HTTP, and port 4001 for HTTPS. We'll route traffic irrespective of protocol. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-9001 -spec: - protocol: HTTP - port: 9001 - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-9002 -spec: - protocol: HTTP - port: 9002 - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-4001 -spec: - protocol: HTTPS - port: 4001 - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: route-host -spec: - requestPolicy: - insecure: - action: Route -``` - -- We can use `X-Forwarded-Proto` for all our `Listener`s: the HTTP-only `Listener`s will set it correctly. -- Each `Listener` can specify only one port, but there's no hardcoded limit on the number of `Listener`s you can have. - - - - Learn more about Listener
- Learn more about Host - - -### Using Labels to Associate `Host`s and `Listener`s - -In the examples above, the `Listener`s all associate with any `Host` in their namespace. In this -example, we will use Kubernetes labels to control the association instead. - -Here, we'll listen for HTTP to `foo.example.com` on port 8888, and for either HTTP or HTTPS to `bar.example.com` on -port 9999 (where we'll redirect HTTP to HTTPS). Traffic to `baz.example.com` will work on both ports, and we'll route -HTTP for it rather than redirecting. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-8888 -spec: - protocol: HTTP - port: 8888 - securityModel: XFP - hostBinding: - selector: - matchLabels: - tenant: foo ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-9999 -spec: - protocol: HTTPS - port: 9999 - securityModel: XFP - hostBinding: - selector: - matchLabels: - tenant: bar ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: bar-secret -data: - tls.crt: -wildcard here- - tls.key: -wildcard here- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host - labels: - tenant: foo -spec: - hostname: foo.example.com - requestPolicy: - insecure: - action: Route ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host - labels: - tenant: bar -spec: - hostname: bar.example.com - tlsSecret: - name: bar-secret ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: baz-host - labels: - tenant: foo - tenant: bar -spec: - hostname: baz.example.com - tlsSecret: - name: bar-secret - requestPolicy: - insecure: - action: Route -``` - -- Note the `labels` on each `Host`, which the `hostBinding` on the `Listener` can reference. - - Note also that only label selectors are supported at the moment. - - - - Learn more about Listener
- Learn more about Host - - -### Wildcard `Host`s and `Mapping`s - -In a `Mapping`, the `host` is now treated as a glob rather than an exact match, with the goal of vastly reducing the need for `host_regex`. (The `hostname` in a `Host` has always been treated as a glob). - -- **Note that only prefix and suffix matches are supported**, so `*.example.com` and `foo.*` are both fine, but `foo.*.com` will not work -- you'll need to use `host_regex` if you really need that. (This is an Envoy limitation.) - -In this example, we'll accept both HTTP and HTTPS, but: - -- Cleartext traffic to any host in `lowsec.example.com` will be routed. -- Cleartext traffic to any host in `normal.example.com` will be redirected. -- Any other cleartext traffic will be rejected. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: example-secret -data: - tls.crt: -wildcard for *.example.com here- - tls.key: -wildcard for *.example.com here- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-8443 -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: lowsec-host -spec: - hostname: "*.lowsec.example.com" - tlsSecret: - name: example-secret - requestPolicy: - insecure: - action: Route ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: normal-host -spec: - hostname: "*.normal.example.com" - tlsSecret: - name: example-secret - requestPolicy: # We could leave this out since - insecure: # redirecting is the default, but - action: Redirect # it's spelled out for clarity. ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: catchall-host -spec: - hostname: "*.example.com" - tlsSecret: - name: example-secret - requestPolicy: - insecure: - action: Reject -``` - -- We'll listen for HTTP or HTTPS on port 8443. -- The three `Host`s apply different insecure routing actions depending on the hostname. -- You could also do this with `host_regex`, but using `host` with globs will give better performance. - - Being able to _not_ associate a given `Mapping` with a given `Host` when the `Mapping`'s - `host` doesn't match helps a lot when you have many `Host`s. - - Reliably determining if a regex (for the `Mapping`) matches a glob (for the `Host`) isn't really possible, so we can't prune `host_regex` `Mapping`s at all. - - - Learn more about Listener
- Learn more about Host - diff --git a/content/en/docs/3.1/howtos/consul.md b/content/en/docs/3.1/howtos/consul.md deleted file mode 100644 index 2b23ba53..00000000 --- a/content/en/docs/3.1/howtos/consul.md +++ /dev/null @@ -1,564 +0,0 @@ - -import Alert from '@material-ui/lab/Alert'; - -# Consul integration - -
-

Contents

- -- [Consul integration](#consul-integration) - - [Architecture overview](#architecture-overview) - - [Installing Consul](#installing-consul) - - [Installing $productName$](#installing-consul) - - [Using Consul for service discovery](#using-consul-for-service-discovery) - - [Using Consul for authorization and encryption](#using-consul-for-authorization-and-encryption) - - [Environment variables](#environment-variables) - - [More information](#more-information) - -
- -[Consul](https://www.consul.io) is a widely used service mesh. -$productName$ natively supports service discovery and unauthenticated -communication to services in Consul. Additionally, the *Ambassador -Consul Connector* enables $productName$ to encrypt and authenticate -its communication via mTLS with services in Consul that make use of -[Consul's *Connect* feature](https://www.consul.io/docs/connect). - -## Architecture overview - -Using Consul with $productName$ is particularly useful when deploying -$productName$ in hybrid cloud environments where you deploy -applications on VMs and Kubernetes. In this environment, Consul -enables $productName$ to securely route over TLS to any application -regardless of where it is deployed. - -In this architecture, Consul serves as the source of truth for your -entire data center, tracking available endpoints, service -configuration, and secrets for TLS encryption. New applications and -services automatically register themselves with Consul using the -Consul agent or API. When you send a request through $productName$, -$productName$ sends the request to an endpoint based on the data in -Consul. - -ambassador-consul - -This guide first instructs you on registering a service with Consul -and using $productName$ to dynamically route requests to that service -based on Consul's service discovery data, and subsequently instructs -you on using using the Ambassador Consul Connector to use Consul for -authorizing and encrypting requests. - -## Installing Consul - -If you already have Consul installed in your cluster, then go ahead -and skip to the next section. - -1. Before you install Consul, make sure to check the Consul - documentation for any setup steps specific to your platform. Below - you can find setup guides for some of the more popular Kubernetes - platforms. This step is primarily to ensure you have the proper - permissions to set up Consul. You can skip these guides if your - cluster is already configured to grant you the necessary - permissions. - - - [Microsoft Azure Kubernetes Service (AKS)](https://learn.hashicorp.com/tutorials/consul/kubernetes-aks-azure?utm_source=consul.io&utm_medium=docs) - - [Amazon Elastic Kubernetes Service (EKS)](https://learn.hashicorp.com/tutorials/consul/kubernetes-eks-aws?utm_source=consul.io&utm_medium=docs) - - [Google Kubernetes Engine (GKE)](https://learn.hashicorp.com/tutorials/consul/kubernetes-gke-google?utm_source=consul.io&utm_medium=docs) - - - - If you did not find your Kubernetes platform above, check the - [Consul documentation here](https://www.consul.io/docs/k8s) to see - if there are specific setup instructions for your platform. - - - -2. Add the Hashicorp repository for installing Consul with Helm. If - you do not have Helm installed, you can find an [installation guide - here](https://helm.sh/docs/intro/install/). - - ```shell - helm repo add hashicorp https://helm.releases.hashicorp.com - ``` - -3. Create a new `consul-values.yaml` YAML file for the Consul - installation values and copy the values below into that file. - - ```yaml - global: - datacenter: dc1 - - ui: - service: - type: 'LoadBalancer' - - syncCatalog: - enabled: true - - server: - replicas: 1 - bootstrapExpect: 1 - - connectInject: - enabled: true - ``` - - - - Note: you are free to change the value of the `datacenter` field in - the install values. This is the the name of your Consul - Datacenter. - - - -4. Install Consul with Helm using the `consul-values.yaml` values file - you just created. - - ```shell - helm install -f consul-values.yaml hashicorp hashicorp/consul - ``` - -## Installing $productName$ - -If you have not already installed $productName$ in to your cluster, -then go to the [quick start guide](../../tutorials/getting-started) -before continuing any further in this guide. - -## Using Consul for service discovery - -This section of the guide instructs you on configuring $productName$ -to look for services registered to Consul, registering a demo -application with Consul, and configuring $productName$ to route to -this application using endpoint data from Consul. - -In this tutorial, you deploy the application in Kubernetes. However, -this application can be deployed anywhere in your data center, such as -on a VM. - -1. Configure $productName$ to look for services registered to Consul - by creating the `ConsulResolver`. Use `kubectl` to apply the - following manifest: - - ```shell - kubectl apply -f < - - **Note:** If you changed the name of your `datacenter` in the - Consul install values, make sure to change it in the resolver above - to match the name of your datacenter. - - If you changed the name of the helm install from `hashicorp` to - another value, make sure to update the value of the `address` field - in your resolver to match it. - - If you are having trouble figuring out what your `address` field - should be, it follow this format: - `http://{consul_server_pod}.{consul_server_service}.{namespace}.svc.cluster.local:{consul_port}`. - The default Consul port should be `8500` unless you changed it. - - - - This tells $productName$ that Consul is a service discovery endpoint. - - You must set the resolver to your `ConsulResolver` on a - per-`Mapping` basis, otherwise for that `Mapping` $productName$ - uses the default resolver. That is, in order for a `Mapping` to - make use of a service registered in Consul, you need to add - `resolver: consul-dc1` to that `Mapping`. - - For more information about resolver configuration, see the - [resolver reference documentation](../../topics/running/resolvers). - (If you're using Consul deployed elsewhere in your data center, - make sure the `address` points to your Consul FQDN or IP address). - -2. Deploy the Quote demo application. Use `kubectl` to - apply the following manifest: - - ```shell - kubectl apply -f < - - The `SERVICE_NAME` environment variable in the `quote-consul` - `Deployment` specifies the service name for Consul. The default - value is set to "quote-consul", so you only need to include it if - you want to change the service name. - - - - The Quote application contains code to automatically - register itself with Consul, using the `CONSUL_IP` and `POD_IP` - environment variables specified within the `quote-consul` container - spec. - - When you apply this manifest, it registers the `Pod` in the - `quote-consul` `Deployment` as a Consul service with the name - `quote-consul` and the IP address of the `Pod`. - - - - The `"consul.hashicorp.com/connect-inject": "false"` annotation - tells Consul that for this `Deployment` you do not want to use the - sidecar proxy that is part of Consul's Connect feature. Without - Consul's sidecar, the service needs to include code to make a - request to Consul to register the service. The manifest includes - the environment variables `CONSUL_IP`, `POD_IP`, and `SERVICE_NAME` - to provide the Quote service with enough information - to build that request and send it to Consul. To see how this code - works, see our [our Git repo for the Quote - service](https://github.com/datawire/quote). - - - -3. Verify the `quote-consul` `Deployment`'s `Pod` has been registered - with Consul. You can verify this by accessing the Consul UI. - - First use `kubectl port-forward` to make the UI available on your - local workstation: - - ```shell - kubectl port-forward service/hashicorp-consul-ui 8500:80 - ``` - - Then, while the port-forward is running, go to - http://localhost:8500/ in a web browser. You should see a service - named `quote-consul`. - - After you have verified that you see the `quote-consul` service in - your web browser, you may kill the port-forward. - - - - Port forwarding not working for you? Make sure the service name - matches your Consul UI service by checking `kubectl get svc -A` - - - -4. Configure $productName$ to make use of this `quote-consul` service. - Use `kubectl` to apply the following manifest: - - ```shell - kubectl apply -f < - -**Congratulations!** You're successfully routing traffic to the Quote -application, the location of which is registered in -Consul. - - - -## Using Consul for authorization and encryption - -In this part of the guide, you'll install a different version of the -demo application that now uses Consul's *Connect* feature to authorize -its incoming connections using mTLS, and install *Ambassador Consul -Connector* to enable $productName$ to authenticate to such services. - -The following steps assume you've already set up Consul for service -discovery, as detailed above. - -1. The Ambassador Consul Connector retrieves the TLS certificate - issued by the Consul CA and stores it in a Kubernetes `Secret` for - $productName$ to use. Deploy the Ambassador Consul Connector with - `kubectl`: - - ```shell - kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/consul/ambassador-consul-connector.yaml - ``` - - This installs in to your cluster: - - - RBAC resources. - - The Ambassador Consul Connector service. - - A `TLSContext` named `ambassador-consul` to load the - `ambassador-consul-connect` `Secret` into $productName$. - -2. Deploy a new version of the demo application, and configure it to - inject the Consul Connect sidecar by setting - `"consul.hashicorp.com/connect-inject"` to `true`. Note that in - this version of the configuration, you do not have to configure - environment variables for the location of the Consul server. Use - `kubectl` to apply the following manifest: - - ```yaml - kubectl apply -f - < - - Note: Annotations are used to attach metadata to Kubernetes - objects. You can use annotations to link external information to - objects, working in a similar, yet different, fashion to labels. - For more information on annotations, refer to the [Annotating - Kubernetes Services for - Humans](https://kubernetes.io/blog/2021/04/20/annotating-k8s-for-humans/) - article, or get started with annotations in your own cluster with - the [Ambassador Cloud Quick start - guide](https://www.getambassador.io/docs/cloud/latest/service-catalog/quick-start/). - - - - This deploys a demo application `Deployment` called `quote-connect` - (different than the `quote-consul` `Deployment` in the previous - section) with the Consul Connect sidecar proxy. The Connect - sidecar registers the application with Consul, requires TLS to - access the application, and exposes other [Consul Service - Segmentation](https://www.consul.io/docs/connect) features. - - The annotation `consul.hashicorp.com/connect-inject` being set to - `true` in this `Deployment` tells Consul that you want this - `Deployment` to use the Consul Connect sidecar. The sidecar - proxies requests to the service that it is attached to. Keep this - in mind mind when debug requests to the service. - -4. Verify the `quote-connect` `Deployment`'s `Pod` has been registered - with Consul. You can verify this by accessing the Consul UI. - - First use `kubectl port-forward` to make the UI available on your - local workstation: - - ```shell - kubectl port-forward service/hashicorp-consul-ui 8500:80 - ``` - - Then, while the port-forward is running, open - http://localhost:8500/ in a web browser. You should see a service - named `quote-connect`. - - After you have verified that you see the `quote-connect` service in - your web browser, you may kill the port-forward. - -5. Create a `Mapping` to configure $productName$ route to the - `quote-connect` service in Consul. Use `kubectl` to apply the - following manifest: - - ```shell - kubectl apply -f < - -**Congratulations!** You successfully configured the service to work -with the Consul Connect sidecar. - - - -### Environment variables - -The Ambassador Consul Connector can be configured with the following -environment variables. The defaults are best for most use-cases. - -| Environment Variable | Description | Default | -|------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------| -| `_AMBASSADOR_ID` | Set 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`) | `""` | -| `_CONSUL_HOST` | Set the IP or DNS name of the target Consul HTTP API server | `127.0.0.1` | -| `_CONSUL_PORT` | Set the port number of the target Consul HTTP API server | `8500` | -| `_AMBASSADOR_TLS_SECRET_NAME` | Set the name of the Kubernetes `v1.Secret` created by this program that contains the Consul-generated TLS certificate. | `$AMBASSADOR_ID-consul-connect` | -| `_AMBASSADOR_TLS_SECRET_NAMESPACE` | Set the namespace of the Kubernetes `v1.Secret` created by this program. | (same Namespace as the Pod running this integration) | - -## More information - -For more about $productName$'s integration with Consul, read the -[service discovery configuration](../../topics/running/resolvers) -documentation. diff --git a/content/en/docs/3.1/howtos/dist-tracing.md b/content/en/docs/3.1/howtos/dist-tracing.md deleted file mode 100644 index ec5b160f..00000000 --- a/content/en/docs/3.1/howtos/dist-tracing.md +++ /dev/null @@ -1,49 +0,0 @@ -# Explore distributed tracing and Kubernetes monitoring - -The Kubernetes monitoring and distributed tracing landscape is hard to grasp. Although this conceptual approach to [observability is nothing new](https://blog.getambassador.io/distributed-tracing-with-java-microdonuts-kubernetes-and-the-ambassador-api-gateway-ace15b62a89e) — companies like New Relic revolutionized single-application performance monitoring (APM) over a decade ago — it took a few years and the [Dapper publication](https://research.google/pubs/pub36356/) for this idea to migrate to distributed applications. The importance of this technology is only increasing, as more and more of us are building [“deep systems”](https://lightstep.com/deep-systems/). - -As the industry is slowly but surely maturing, standardization is underway. Standardization means proprietary vendor solutions and open source projects are able to collaborate, making our lives easier. For newcomers, understanding the plethora of options, concepts, specifications, and implementations available is still a daunting task: - -* How are Zipkin and Jaeger related? -* What is header propagation? -* Which headers format should I use? -* Who owns the initialization of a trace context? -* How are the data points collected? - -The [K8s Initializer](https://app.getambassador.io/initializer/) can make it easy to enable distributed tracing in any microservices-based system by offering an opinionated and preconfigured application stack that will get you up and running in no time. This way, you can focus on understanding your service topology and interactions rather than waste days on attempting to understand competing standard integrations and tuning configuration switches. - -## One-Click Tracing Configuration with the K8s Initializer - -The K8s Initializer is a tool we built for you to quickly bootstrap any Kubernetes cluster with your own application-ready playground. It will generate YAML manifests for ingress, observability, and more in just a few clicks. Once installed on a local or remote Kubernetes cluster, the generated Kubernetes manifest resources will give you a perfect sandbox environment to deploy your own applications and explore standard integrations. - -Specifically for observability and distributed tracing, the K8s Initializer bundles a Jaeger installation to collect and visualize traces along with a pre-configured Ambassador Edge Stack acting as the ingress controller that will create a trace context on every request. A single selection is required. - -As per the option we selected, we’ll be generating Zipkin-format traces and use B3 headers for propagation between our services. There you have it! Instrument your Java, Python, Golang or Node.js applications with Zipkin and B3 header propagation libraries, then configure your code to send the trace data to the `jaeger-collector.monitoring:9411` service endpoint. - -All that is left to do is making a few requests and visualizing the trace data in the Jaeger UI. - -## Visualizing Trace Data - -As we installed the Ambassador Edge Stack as our ingress controller for Kubernetes via the K8s Initializer, it will instrument parent trace spans for each request coming into our Kubernetes cluster from the internet. The K8s Initializer also pre-configured Ambassador to exposes the Jaeger UI on a subpath: `https://$AMBASSADOR_IP/jaeger/` - -Simply by visiting this URL on our installation, we are able to visualize the generated and collected trace information emitted by our Ambassador installation: - -![Jaeger screenshot](../../images/jaeger.png) - -## Tracing the Future: OpenTelemetry - -The [OpenTelemetry project](https://opentelemetry.io/) was created with the intent of stopping the proliferation of API standards and libraries one might need to support for all their observability needs, effectively replacing the Zipkin-API, OpenCensus, OpenTracing and more competing implementations. - -> OpenTelemetry provides a single set of APIs, libraries, agents, and collector services to capture distributed traces and metrics from your application. You can analyze them using Prometheus, Jaeger, and other observability tools.
--[https://opentelemetry.io/](https://opentelemetry.io/) - -It’s at this point in the conversation that someone inevitably mentions that XKCD... - -![XKCD #927](../../images/xkcd.png) - -OpenTelemetry ultimately supports multiple formats in its [OpenTelemetry-Collector](https://github.com/open-telemetry/opentelemetry-collector), easing the transition from one technology to another when installed as a middleware and translator to relay trace data to other collectors. Along with many of its long-awaited features, it supports multiple trace exporters for Jaeger, Zipkin and proprietary APIs. - -## Learn More -In this tutorial, we’ve shown you how to monitor your Kubernetes application with distributed tracing in just a few clicks with the K8s Initializer. To learn more about these tools and distributed tracing, we also recommend [A Complete Guide to Distributed Tracing by the Lightstep Team](https://lightstep.com/distributed-tracing/). - -We also have guides to setup Edge Stack with [Datadog](../tracing-datadog/), [Zipkin](../tracing-zipkin/), and [Prometheus and Grafana](../prometheus). diff --git a/content/en/docs/3.1/howtos/external-dns.md b/content/en/docs/3.1/howtos/external-dns.md deleted file mode 100644 index f0f51dbb..00000000 --- a/content/en/docs/3.1/howtos/external-dns.md +++ /dev/null @@ -1,130 +0,0 @@ -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 - -Start by checking the [ExternalDNS repo's deployment instructions](https://github.com/kubernetes-sigs/external-dns#deploying-to-a-cluster) to get information about the supported DNS providers and steps to setup ExternalDNS for your provider. Each DNS provider will have its own required steps as well as annotations, arguments, and permissions needed for the following configuration. - - -### Installation - -Configuration for a `ServiceAccount`, `ClusterRole`, and `ClusterRoleBinding` are necessary for the ExternalDNS deployment to support compatability 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 above for annotations and arguments for your DNS Provider. - - -1. Create a YAML file named `externaldns-config.yaml`, and copy the following configuration into it. - - - Ensure that the apiGroups include "getambassador.io" following "networking.k8s.io" and the resources include "hosts" after "ingresses". - - - ```yaml - --- - apiVersion: v1 - kind: ServiceAccount - metadata: - name: external-dns - annotations: - eks.amazonaws.com/role-arn: {ARN} # AWS ARN role - --- - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRole - metadata: - name: external-dns - rules: - - apiGroups: [""] - resources: ["services","endpoints","pods"] - verbs: ["get","watch","list"] - - apiGroups: ["extensions","networking.k8s.io", "getambassador.io"] - resources: ["ingresses", "hosts"] - verbs: ["get","watch","list"] - - apiGroups: [""] - resources: ["nodes"] - verbs: ["list","watch"] - --- - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRoleBinding - metadata: - name: external-dns-viewer - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: external-dns - subjects: - - kind: ServiceAccount - name: external-dns - namespace: default - --- - apiVersion: apps/v1 - kind: Deployment - metadata: - name: external-dns - spec: - strategy: - type: Recreate - selector: - matchLabels: - app: external-dns - template: - metadata: - labels: - app: external-dns - annotations: - iam.amazonaws.com/role: {ARN} # AWS ARN role - spec: - serviceAccountName: external-dns - containers: - - name: external-dns - image: registry.opensource.zalan.do/teapot/external-dns:latest - args: - - --source=ambassador-host - - --domain-filter=example.net # will make ExternalDNS see only the hosted zones matching provided domain, omit to process all available hosted zones - - --provider=aws - - --policy=upsert-only # would prevent ExternalDNS from deleting any records, omit to enable full synchronization - - --aws-zone-type=public # only look at public hosted zones (valid values are public, private or no value for both) - - --registry=txt - - --txt-owner-id= {Hosted Zone ID} # Insert Route53 Hosted Zone ID here - ``` - -2. Review the arguments section from the ExternalDNS deployment - - Configure or remove arguments to fit your needs. Additional arguments required for your DNS provider can be found by checking the [ExternalDNS repo's deployment instructions](https://github.com/kubernetes-sigs/external-dns#deploying-to-a-cluster). - - * `--source=ambassador-host` - required across all DNS providers to tell ExternalDNS to look for hostnames in the $productName$ `Host` configurations. - -3. Apply the above config with the following command to deploy ExternalDNS to your cluster and configure support for $productName$ - - ```shell - kubectl apply -f externaldns-ambassador.yaml - ``` - - - For the above example, ensure that you are using an EKS cluster, or register your cluster with AWS so that ExternalDNS can view and edit your AWS Hosted Zones. If you are using a cluster outside EKS and not registered with AWS you will see permissions errors from the ExternalDNS pod when attempting to list the Hosted Zones. - - -## Usage - -After applying the above configuration, ExternalDNS is ready to use. Configure a `Host` with the following annotation to allow ExternalDNS to get the IP address of your $productName$'s LoadBalancer and register it with your DNS provider. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: your-hostname - annotations: - external-dns.ambassador-service: $productDeploymentName$.$productNamespace$ -spec: - acmeProvider: - authority: none - hostname: your-hostname.example.com -``` - - -Victory! ExternalDNS is now running and configured to report $productName$'s IP and hostname with your DNS provider. diff --git a/content/en/docs/3.1/howtos/filter-dev-guide.md b/content/en/docs/3.1/howtos/filter-dev-guide.md deleted file mode 100644 index eefe8b6b..00000000 --- a/content/en/docs/3.1/howtos/filter-dev-guide.md +++ /dev/null @@ -1,97 +0,0 @@ -# Developing custom filters for routing - -Sometimes you may want $AESproductName$ to manipulate an incoming request. Some example use cases: - -* Inspect an incoming request, and add a custom header that can then be used for routing -* Add custom Authorization headers -* Validate an incoming request fits an OpenAPI specification before passing the request to a target service - -$AESproductName$ supports these use cases by allowing you to execute custom logic in `Filters`. Filters are written in Golang, and managed by $AESproductName$. If you want to write a filter in a language other than Golang, $AESproductName$ also has an HTTP/gRPC interface for Filters called `External`. - -## Prerequisites - -`Plugin` `Filter`s are built as [Go plugins](https://golang.org/pkg/plugin/) and loaded directly into the $AESproductName$ container so they can run in-process with the rest of $AESproductName$. - -To build a `Plugin` `Filter` into the $AESproductName$ container you will need -- Linux or MacOS host (Windows Subsystem for Linux is ok) -- [Docker](https://docs.docker.com/install/) -- [rsync](https://rsync.samba.org/) - -The `Plugin` `Filter` is built by `make` which uses Docker to create a stable build environment in a container and `rsync` to copy files between the container and your host machine. - -See the [README](https://github.com/datawire/apro-example-plugin) for more information on how the `Plugin` works. - -## Creating and deploying filters - -We've created an example filter that you can customize for your particular use case. - -1. Start with the example filter: `git clone - https://github.com/datawire/apro-example-plugin/`. - -2. Make code changes to `param-plugin.go`. Note: If you're developing a non-trivial filter, see the rapid development section below for a faster way to develop and test your filter. - -3. Run `make DOCKER_REGISTRY=...`, setting `DOCKER_REGISTRY` to point - to a registry you have access to. This will generate a Docker image - named `$DOCKER_REGISTRY/amb-sidecar-plugin:VERSION`. - -4. Push the image to your Docker registry: `docker push $DOCKER_REGISTRY/amb-sidecar-plugin:VERSION`. - -5. Configure $AESproductName$ to use the plugin by creating a `Filter` - and `FilterPolicy` CRD, as per the [filter reference](/docs/edge-stack/latest/topics/using/filters/). - -6. Update the standard $AESproductName$ manifest to use your Docker - image instead of the standard sidecar. - - ```patch - value: '60' - - name: AMBASSADOR_INTERNAL_URL - value: https://127.0.0.1:8443 - - image: docker.io/datawire/aes:$version$ - + image: DOCKER_REGISTRY/aes-plugin:VERSION - imagePullPolicy: Always - livenessProbe: - httpGet: - ``` - -## Rapid development of a custom filter - -During development, you may want to sidestep the deployment process for a faster development loop. The `aes-plugin-runner` helps you rapidly develop $AESproductName$ filters locally. - -To install the runner, download the latest version: - -Mac 64-bit | -Linux 64-bit - -Note that the plugin runner must match the version of $AESproductName$ that you are running. Place the binary somewhere in your `$PATH`. - -Information about open-source code used in `aes-plugin-runner` can be found by running `aes-plugin-runner --version`. - -Now, you can quickly test and develop your filter. - -1. In your filter directory, type: `aes-plugin-runner :8080 ./param-plugin.so`. -2. Test the filter by running `curl`: - - ``` - $ curl -Lv localhost:8080?db=2 - * Rebuilt URL to: localhost:8080/?db=2 - * Trying ::1... - * TCP_NODELAY set - * Connected to localhost (::1) port 8080 (#0) - > GET /?db=2 HTTP/1.1 - > Host: localhost:8080 - > User-Agent: curl/7.54.0 - > Accept: */* - > - < HTTP/1.1 200 OK - < X-Dc: Even - < Date: Mon, 25 Feb 2019 19:58:38 GMT - < Content-Length: 0 - < - * Connection #0 to host localhost left intact - ``` - -Note in the example above the `X-Dc` header is added. This lets you inspect the changes the filter is making to your HTTP header. - -## Further reading - -For more details about configuring filters and the `plugin` interface, see the [filter reference](/docs/edge-stack/latest/topics/using/filters/). diff --git a/content/en/docs/3.1/howtos/grpc.md b/content/en/docs/3.1/howtos/grpc.md deleted file mode 100644 index 7ba77340..00000000 --- a/content/en/docs/3.1/howtos/grpc.md +++ /dev/null @@ -1,403 +0,0 @@ -# gRPC Connections - -$productName$ makes it easy to access your services from outside your application. This includes gRPC services, although a little bit of additional configuration is required: by default, Envoy connects to upstream services using HTTP/1.x and then upgrades to HTTP/2 whenever possible. However, gRPC is built on HTTP/2 and most gRPC servers do not speak HTTP/1.x at all. $productName$ must tell its underlying Envoy that your gRPC service only wants to speak to that HTTP/2, using the `grpc` attribute of a `Mapping`. - -## Writing a gRPC service for $productName$ - -There are many examples and walkthroughs on how to write gRPC applications so that is not what this article will aim to accomplish. If you do not yet have a service written you can find examples of gRPC services in all supported languages here: [gRPC Quickstart](https://grpc.io/docs/quickstart/) - -This document will use the [gRPC python helloworld example](https://github.com/grpc/grpc/tree/master/examples/python/helloworld) to demonstrate how to configure a gRPC service with $productName$. - -Follow the example up through [Run a gRPC application](https://grpc.io/docs/languages/python/quickstart/#run-a-grpc-application) to get started. - -### Dockerize - -After building our gRPC application and testing it locally, we need to package it as a Docker container and deploy it to Kubernetes. - -To run a gRPC application, we need to include the client/server and the protocol buffer definitions. - -For gRPC with python, we need to install `grpcio` and the common protos. - -```Dockerfile -FROM python:2.7 - -WORKDIR /grpc - -ENV PATH "$PATH:/grpc" - -COPY greeter_server.py /grpc -COPY helloworld_pb2.py /grpc -COPY helloworld_pb2_grpc.py /grpc - -RUN python -m pip install grpcio -RUN python -m pip install grpcio-tools googleapis-common-protos - -CMD ["python", "./greeter_server.py"] - -EXPOSE 50051 -``` - -Create the container and test it: - -``` -$ docker build -t /grpc_example -$ docker run -p 50051:50051 /grpc_example -``` - -Where `` is your Docker user or registry. - -Switch to another terminal and from the same directory, run the `greeter_client`. The output should be the same as running it outside of the container. - -``` -$ docker run -p 50051:50051 /grpc_example -Greeter client received: Hello, you! -``` - -Once you verify the container works, push it to your Docker registry: - -``` -$ docker push /grpc_example -``` - -### Mapping gRPC services - -$productName$ `Mapping`s are based on URL prefixes; for gRPC, the URL prefix is the full-service name, including the package path (`package.service`). These are defined in the `.proto` definition file. In the example [proto definition file](https://github.com/grpc/grpc/blob/master/examples/protos/helloworld.proto) we see: - -``` -package helloworld; - -// The greeting service definition. -service Greeter { ... } -``` - -so the URL `prefix` is `helloworld.Greeter` and the mapping would be: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py -spec: - hostname: "*" - grpc: True - prefix: /helloworld.Greeter/ - rewrite: /helloworld.Greeter/ - service: grpc-example -``` - -Note the `grpc: true` line - this is what tells Envoy to use HTTP/2 so the request can communicate with your backend service. Also note that you'll need `prefix` and `rewrite` the same here, since the gRPC service needs the package and service to be in the request to do the right thing. - -### Deploying to Kubernetes - -`grpc_example.yaml` - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - acmeProvider: - authority: none - requestPolicy: - insecure: - action: Route ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py -spec: - hostname: "*" - grpc: True - prefix: /helloworld.Greeter/ - rewrite: /helloworld.Greeter/ - service: grpc-example - ---- -apiVersion: v1 -kind: Service -metadata: - labels: - service: grpc-example - name: grpc-example -spec: - type: ClusterIP - ports: - - name: grpc-greet - port: 80 - targetPort: grpc-api - selector: - service: grpc-example ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: grpc-example -spec: - replicas: 1 - selector: - matchLabels: - service: grpc-example - template: - metadata: - labels: - service: grpc-example - spec: - containers: - - name: grpc-example - image: /grpc_example - ports: - - name: grpc-api - containerPort: 50051 - restartPolicy: Always -``` - -The Host is declared here because we are using gRPC without TLS. Since $productName$ terminates TLS by default, in the Host we add a `requestPolicy` which allows insecure connections. After adding the $productName$ mapping to the service, the rest of the Kubernetes deployment YAML file is pretty straightforward. We need to identify the container image to use, expose the `containerPort` to listen on the same port the Docker container is listening on, and map the service port (80) to the container port (50051). - -> For more information on insecure routing, please refer to the [`Host` documentation](../../topics/running/host-crd#secure-and-insecure-requests). - - -Once you have the YAML file and the correct Docker registry, deploy it to your cluster with `kubectl`. - -``` -$ kubectl apply -f grpc_example.yaml -``` - -### Testing the Deployment - -Make sure to test your Kubernetes deployment before making more advanced changes (like adding TLS). To test any service with $productName$, we will need the hostname of the running $productName$ service which you can get with: - -``` -$ kubectl get service ambassador -o wide -``` -Which should return something similar to: - -``` -NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE -ambassador 10.11.12.13 35.36.37.38 80:31656/TCP 1m -``` -where `EXTERNAL-IP` is the `$AMBASSADORHOST` and 80 is the `$PORT`. - -You will need to open the `greeter_client.py` and change `localhost:50051` to `$AMBASSADORHOST:$PORT` - -```diff -- with grpc.insecure_channel('localhost:50051') as channel: -+ with grpc.insecure_channel(‘$AMBASSADORHOST:$PORT’) as channel: - stub = helloworld_pb2_grpc.GreeterStub(channel) - response = stub.SayHello(helloworld_pb2.HelloRequest(name='you')) - print("Greeter client received: " + response.message) -``` - -After making that change, simply run the client again and you will see the gRPC service in your cluster respond: - -``` -$ python greeter_client.py -Greeter client received: Hello, you! -``` - -### gRPC and TLS - -There is some extra configuration required to connect to a gRPC service through $productName$ over an encrypted channel. Currently, the gRPC call is being sent over cleartext to $productName$ which proxies it to the gRPC application. - -grpc-tls - -If you want to add TLS encryption to your gRPC calls, first you need to tell $productName$ to add [ALPN protocols](../../topics/running/tls) which are required by HTTP/2 to do TLS. - -For example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls -spec: - hosts: - - "*" - secret: ambassador-cert - alpn_protocols: h2 -``` - -Next, you need to change the client code slightly and tell it to open a secure RPC channel with $productName$. - -```diff -- with grpc.insecure_channel(‘$AMBASSADORHOST:$PORT’) as channel: -+ with grpc.secure_channel(‘$AMBASSADORHOST:$PORT’, grpc.ssl_channel_credentials()) as channel: - stub = helloworld_pb2_grpc.GreeterStub(channel) - response = stub.SayHello(helloworld_pb2.HelloRequest(name='you')) - print("Greeter client received: " + response.message) -``` - -`grpc.ssl_channel_credentials(root_certificates=None, private_key=None, certificate_chain=None)`returns the root certificate that will be used to validate the certificate and public key sent by $productName$. The default values of `None` tells the gRPC runtime to grab the root certificate from the default location packaged with gRPC and ignore the private key and certificate chain fields. Generally, passing no arguments to the method that requests credentials gives the same behavior. Refer to the languages [API Reference](https://grpc.io/docs/) if this is not the case. - -$productName$ is now terminating TLS from the gRPC client and proxying the call to the application over cleartext. - -gRPC-TLS-Ambassador - -If you want to configure authentication in another language, [gRPC provides examples](https://grpc.io/docs/guides/auth.html) with proper syntax for other languages. - -#### Working with Host headers that include the port - -Some gRPC clients automatically include the port in the Host header. This is a problem when using TLS because the certificate will match `myurl.com` but the Host header will be `myurl.com:443`, resulting in the error `rpc error: code = Unimplemented desc =`. If you run into this issue, there are two ways to solve it depending on your use case, both using the Module resource. - -The first is to set the `strip_matching_host_port` [property](../../topics/running/ambassador#strip-matching-host-port) to `true`. However, this only works if the port in the header matches the port that Envoy listens on (8443 by default). In the default installation of $productName$, the public port is 443, which then maps internally to 8443, so this only works for custom installations where the public service port matches the port in the Listener resource. - -The second solution is to use the following [Lua script](../../topics/running/ambassador#lua-scripts), which always strips the port: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador - namespace: ambassador -spec: - config: - lua_scripts: | - function envoy_on_request(request_handle) - local authority = request_handle:headers():get(":authority") - if(string.find(authority, ":") ~= nil) - then - local authority_index = string.find(authority, ":") - local stripped_authority = string.sub(authority, 1, authority_index - 1) - request_handle:headers():replace(":authority", stripped_authority) - end - end -``` - -#### Originating TLS with gRPC service - -gRPC-TLS-Originate - -$productName$ can originate TLS with your gRPC service so the entire RPC channel is encrypted. To configure this, first get some TLS certificates and configure the server to open a secure channel with them. Using self-signed certs this can be done with OpenSSL and adding a couple of lines to the server code. - -```diff -def serve(): - server = grpc.server(futures.ThreadPoolExecutor(max_workers=10)) -+ with open('certs/server.key', 'rb') as f: -+ private_key = f.read() -+ with open('certs/server.crt', 'rb') as f: -+ cert_chain = f.read() -+ server_creds = grpc.ssl_server_credentials( ( (private_key, cert_chain), ) ) - helloworld_pb2_grpc.add_GreeterServicer_to_server(Greeter(), server) -- server.add_insecure_port('[::]:50052') -+ server.add_secure_port('[::]:50052', server_creds) - server.start() -``` - -Rebuild your docker container **making sure the certificates are included** and follow the same steps of testing and deploying to Kubernetes. You will need to make a small change to the client code to test locally. - -```diff -- with grpc.insecure_channel(‘localhost:$PORT’) as channel: -+ with grpc.secure_channel(‘localhost:$PORT’, grpc.ssl_channel_credentials(open('certs/server.crt', 'rb').read())) as channel: - stub = helloworld_pb2_grpc.GreeterStub(channel) - response = stub.SayHello(helloworld_pb2.HelloRequest(name='you')) - print("Greeter client received: " + response.message) -``` - -Once deployed we will need to tell $productName$ to originate TLS to the application. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py-tls -spec: - hostname: "*" - grpc: True - tls: upstream - prefix: /hello.Greeter/ - rewrite: /hello.Greeter/ - service: https://grpc-py - ---- -apiVersion: v1 -kind: Service -metadata: - labels: - service: grpc-py - name: grpc-py -spec: - type: ClusterIP - ports: - - name: grpc-greet - port: 443 - targetPort: grpc-api - selector: - service: grpc-py -``` - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: upstream -spec: - alpn_protocols: h2 - secret: ambassador-cert -``` - -We need to tell $productName$ to route to the `service:` over https and have the service listen on `443`. We also need to tell $productName$ to use ALPN protocols when originating TLS with the application, the same way we did with TLS termination. This is done by setting `alpn_protocols: ["h2"]` in a `TLSContext` telling the service to use that tls-context in the mapping by setting `tls: upstream`. - -Refer to the [TLS document](../../topics/running/tls/origination#advanced-configuration-using-a-tlscontext) for more information on TLS origination. - -### gRPC headers - -gRPC services use [HTTP/2 headers](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md). This means that some header-based routing rules will need to be rewritten to support HTTP/2 headers. For example, `host: subdomain.host.com` needs to be rewritten using the `headers: ` attribute with the `:authority` header: - -``` -headers: - :authority: subdomain.host.com -``` - -## Note - -### Ingress controllers - -Some [Kubernetes ingress controllers](https://kubernetes.io/docs/concepts/services-networking/ingress/) do not support HTTP/2 fully. As a result, if you are running $productName$ with an ingress controller in front, you may find that gRPC requests fail even with correct $productName$ configuration. - -A simple way around this is to use $productName$ with a `LoadBalancer` service, rather than an Ingress controller. You can also consider using [$productName$ as your Ingress Controller](../../topics/running/ingress-controller). - -### Mappings with hosts - -As with any `Mapping`, your gRPC service's `Mapping` may include a `host`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py -spec: - hostname: "*" - grpc: true - prefix: /helloworld.Greeter/ - rewrite: /helloworld.Greeter/ - service: grpc-example - host: api.example.com -``` - -Some gRPC client libraries produce requests where the `host` or `:authority` header includes the port number. For example, a request to the above service might include `host: api.example.com:443` instead of just `host: api.example.com`. To avoid having $productName$ return a 404 (not found) response to these requests due to the mismatched host, you may want to set `strip_matching_host_port` in the [Ambassador module](../../topics/running/ambassador#strip-matching-host-port). - -Alternately, you may find it cleaner to make sure your gRPC client does not include the port in the `host` header. Here is an example using gRPC/Go. - -```go -hostname := "api.example.com" -port := "443" -config := &tls.Config{ServerName: hostname} -creds := credentials.NewTLS(config) -opts := []grpc.DialOption{ - grpc.WithTransportCredentials(creds), -// ... -} -conn, err := grpc.Dial(hostname+":"+port, opts...) -// ... -``` - -## gRPC-Web - -$productName$ also supports the [gRPC-Web](../../topics/running/ambassador#grpc) protocol for browser-based gRPC applications. diff --git a/content/en/docs/3.1/howtos/http3-aks.md b/content/en/docs/3.1/howtos/http3-aks.md deleted file mode 100644 index 2f9be012..00000000 --- a/content/en/docs/3.1/howtos/http3-aks.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "$productName$ - HTTP/3 support for Azure Kubernetes Service (AKS)" -description: "How to configure HTTP/3 support for Azure Kubernetes Service (AKS). This guide shows how to setup the LoadBalancer service for AKS to support both TCP and UDP communications." ---- - -# Azure Kubernetes Service Engine HTTP/3 configuration - -This guide shows how to setup HTTP/3 support for Azure Kubernetes Service (AKS). The instructions provided in this page are a continuation of the [HTTP/3 in $productName$](../../topics/running/http3) documentation. - -## Configuring an external load balancer for AKS - -To configure an external load balancer for AKS, you need to: - -1. Reserve a public static IP address. -2. Create two `LoadBalancer` services, one for TCP and one for UDP. -3. Assign the public static IP address to the `loadBalancerIP` field. - -An example of the two load balancer services described above looks as follows: - -```yaml -# selectors and labels removed for clarity -apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$ - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - --- - apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$-udp - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http3 - port: 443 # Default support for HTTP/3 requires you to use 443 for the external client-facing port. - targetPort: 8443 - protocol: UDP - -``` - -In the above example, AKS generates two `LoadBalancer` services, one for UDP and the other for TCP. - - -You should verify that the Managed Identity or Serivce Principal has permissions to assign the IP address to the newly created LoadBalancer services. Refer to the Azure Docs - Managed Identity for more information. - diff --git a/content/en/docs/3.1/howtos/http3-eks.md b/content/en/docs/3.1/howtos/http3-eks.md deleted file mode 100644 index ce54fd0c..00000000 --- a/content/en/docs/3.1/howtos/http3-eks.md +++ /dev/null @@ -1,252 +0,0 @@ ---- -title: "HTTP/3 with Amazon Elastic Kubernetes Service—EKS | $productName$" -description: "How to configure HTTP/3 support for Amazon Elastic Kubernetes Service (EKS). This guide shows how to setup the LoadBalancer service for EKS to support both TCP and UDP communications." ---- - -# Amazon Elastic Kubernetes Service HTTP/3 configuration - -This guide shows how to setup HTTP/3 support for Amazon Elastic Kubernetes Service (EKS) The instructions provided in this page are a continuation of the [HTTP/3 in $productName$](../../topics/running/http3) documentation. - -## Create a network load balancer (NLB) - - The virtual private cloud (VPC) for your load balancer needs one public subnet in each availability zone where you have targets. - - ```shell - SUBNET_IDS=( ) - - aws elbv2 create-load-balancer \ - --name ${CLUSTER_NAME}-nlb \ - --type network \ - --subnets ${SUBNET_IDS} - ``` - -## Create a NodePort service - -Now create a `NodePort` service for $productName$ installation with two entries. Use `port: 443` to include support for both TCP and UDP traffic. - ```yaml - # Selectors and labels removed for clarity. - apiVersion: v1 - kind: Service - metadata: - name: $productDeploymentName$-http3 - namespace: $productNamespace$ - spec: - type: NodePort - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - nodePort: 30080 - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - nodePort: 30443 - - name: http3 - port: 443 - targetPort: 8443 - protocol: UDP - nodePort: 30443 - ``` - -## Create target groups - -Run the following command with the variables for your VPC ID and cluster name: - - ```shell - VPC_ID= - CLUSTER_NAME= - - aws elbv2 create-target-group --name ${CLUSTER_NAME}-tcp-tg \ - --protocol TCP --port 30080 --vpc-id ${VPC_ID} \ - --health-check-protocol TCP \ - --health-check-port 30080 \ - --target-type instance - - aws elbv2 create-target-group --name ${CLUSTER_NAME}-tcp-udp-tg \ - --protocol TCP_UDP --port 30443 --vpc-id ${VPC_ID} \ - --health-check-protocol TCP \ - --health-check-port 30443 \ - --target-type instance - ``` - -## Register your instances - -Next, register your cluster's instance with the the instance IDs and Amazon Resource Names (ARN). - -To get your cluster's instance IDs, enter the following command: - ```shell - aws ec2 describe-instances \ - --filters Name=tag:eks:cluster-name,Values=${CLUSTER_NAME} \ - --output text - --query 'Reservations[*].Instances[*].InstanceId' \ - ``` - -To get your ARNs, enter the following command: - ```shell - TCP_TG_NAME=${CLUSTER_NAME}-tcp-tg-name - TCP_UDP_TG_NAME=${CLUSTER_NAME}-tcp-udp-tg-name - - aws elbv2 describe-target-groups \ - --query 'TargetGroups[?TargetGroupName==`'${TCP_TG_NAME}'`].TargetGroupArn' \ - --output text - aws elbv2 describe-target-groups \ - --query 'TargetGroups[?TargetGroupName==`'${TCP_UDP_TG_NAME}'`]. TargetGroupArn' \ - --output text - ``` - -Register the instances with the target groups and load balancer using the instance IDs and ARNs you retrieved. - ```shell - INSTANCE_IDS=( ) - REGION= - TG_NAME= - TCP_TG_ARN=arn:aws:elasticloadbalancing:${REGION}:079.....:targetgroup/${TG_NAME}/... - TCP_UDP_TG_ARN=arn:aws:elasticloadbalancing:${REGION}:079.....:targetgroup/${TG_NAME}/... - - aws elbv2 register-targets --target-group-arn ${TCP_TG_ARN} --targets ${INSTANCE_IDS} - aws elbv2 register-targets --target-group-arn ${TCP_UDP_TG_ARN} --targets ${INSTANCE_IDS} - ``` - -## Create listeners in AWS. - -Register your cluster's instance with the instance IDs and ARNs. - -To get the load balancer's ARN, enter the following command: - ```shell - aws elbv2 describe-load-balancers --name ${CLUSTER_NAME}-nlb \ - --query 'LoadBalancers[0].LoadBalancerArn' \ - --output text - ``` - -Create a TCP listener on port 80 that that forwards to the TargetGroup {TCP_TG_ARN}. - ```shell - aws elbv2 create-listener --load-balancer-arn ${LB_ARN} \ - --protocol TCP --port 80 \ - --default-actions Type=forward,TargetGroupArn=${TCP_TG_ARN} - ``` - - Create a TCP_UDP listener on port 443 that forwards to the TargetGroup {TCP_UDP_TG_ARN}. - ```shell - aws elbv2 create-listener --load-balancer-arn ${LB_ARN} \ - --protocol TCP_UDP --port 443 \ - --default-actions Type=forward,TargetGroupArn=${TCP_UDP_TG_ARN} - ``` - -## Update the security groups - -Now you need to update your security groups to receive traffic. This security group covers all node groups attached to the EKS cluster: - ```shell - aws eks describe-cluster --name ${CLUSTER_NAME} | grep clusterSecurityGroupId - ``` - -Now authorize the cluster security group to allow internet traffic: - ```shell - for x in ${CLUSTER_SG}; do \ - aws ec2 authorize-security-group-ingress --group-id $$x --protocol tcp --port 30080 --cidr 0.0.0.0/0; \ - aws ec2 authorize-security-group-ingress --group-id $$x --protocol tcp --port 30443 --cidr 0.0.0.0/0; \ - aws ec2 authorize-security-group-ingress --group-id $$x --protocol udp --port 30443 --cidr 0.0.0.0/0; \ - done - ``` - -## Get the DNS name for the load balancers - -Enter the following command to get the DNS name for your load balancers and create a CNAME record at your domain provider: - ```shell - aws elbv2 describe-load-balancers --name ${CLUSTER_NAME}-nlb \ - --query 'LoadBalancers[0].DNSName' \ - --output text - ``` - -## Create Listener resources - -Now you need to create the `Listener` resources for $productName$. The first `Listener` in the example below handles traffic for HTTP/1.1 and HTTP/2, while the second `Listener` handles all HTTP/3 traffic. - - ```yaml - kubectl apply -f - < - acmeProvider: - authority: none - tlsSecret: - name: tls-cert # The QUIC network protocol requires TLS with a valid certificate - tls: - min_tls_version: v1.3 - max_tls_version: v1.3 - alpn_protocols: h2,http/1.1 - EOF - ``` - -## Apply the quote service and a Mapping to test the HTTP/3 configuration. - -Finally, apply the quote service to a $productName$ `Mapping`. - - ```shell - kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$version$/quickstart/qotm.yaml - kubectl apply -f - </backend/ - ``` -Your domain now shows that it is being served with HTTP/3. diff --git a/content/en/docs/3.1/howtos/http3-gke.md b/content/en/docs/3.1/howtos/http3-gke.md deleted file mode 100644 index 677e89e3..00000000 --- a/content/en/docs/3.1/howtos/http3-gke.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: "$productName$ - HTTP/3 support for Google Kubernetes Engine (GKE)" -description: "How to configure HTTP/3 support for Google Kubernetes Engine (GKE). This guide shows how to setup the LoadBalancer service for GKE to support both TCP and UDP communications." ---- - -# Google Kubernetes Service Engine HTTP/3 configuration - -This guide shows how to setup HTTP/3 support for Google Kubernetes Engine (GKE). The instructions provided in this page are a continuation of the [HTTP/3 in $productName$](../../topics/running/http3) documentation. - -## Configuring an external load balancer for GKE - -Currently, GKE only supports adding feature flags to `alpha` clusters, and doesn't support the creation of mixed protocol services of type `LoadBalancer`. To configure an external load balancer for GKE, you need to: - -1. Reserve a public static IP address. -2. Create two `LoadBalancer` services, one for TCP and one for UDP. -3. Assign the public static IP address to the `loadBalancerIP` field. - -An example of the two load balancer services described above looks as follows: - -```yaml -# selectors and labels removed for clarity -apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$ - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - --- - apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$-udp - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http3 - port: 443 # Default support for HTTP/3 requires you to use 443 for the external client-facing port. - targetPort: 8443 - protocol: UDP - -``` - -In the above example, GKE generates two `LoadBalancer` services, one for UDP and the other for TCP. diff --git a/content/en/docs/3.1/howtos/index.md b/content/en/docs/3.1/howtos/index.md deleted file mode 100644 index f16cdd46..00000000 --- a/content/en/docs/3.1/howtos/index.md +++ /dev/null @@ -1,25 +0,0 @@ -# "How-to" guides - -These guides are designed to help users quickly accomplish common tasks. The guides assume a certain level of understanding of $productName$. Many of these guides are contributed by third parties; we welcome contributions via Pull Request at https://github.com/emissary-ingress/emissary. - -* Integrating with Service Mesh. $productName$ natively integrates with many service meshes. - * [HashiCorp Consul](consul) - * [Istio](istio) - * [Linkerd](linkerd2) -* Distributed tracing. $productName$ natively supports a number of distributed tracing systems to enable developers to visualize request flow in microservice and service-oriented architectures. - * [Datadog](tracing-datadog) - * [Zipkin](tracing-zipkin) -* Monitoring. $productName$ integrates with a number of different monitoring/metrics providers. - * [Prometheus](prometheus) -* [Developing Custom Filters](filter-dev-guide) -* Frameworks and Protocols. $productName$ supports a wide range of protocols and cloud-native frameworks. - * [gRPC](grpc) - * [Knative Serverless Framework](knative) - * [WebSockets](websockets) -* Security. $productName$ supports a number of strategies for securing Kubernetes services. - * [Protecting the Diagnostics Interface](protecting-diag-access) - * [HTTPS and TLS termination](tls-termination) - * [Certificate Manager](cert-manager) can be used to automatically obtain and renew TLS certificates; $AESproductName$ natively integrates this functionality. - * [Client Certificate Validation](client-cert-validation) - * [Basic Authentication](basic-auth) is a tutorial on how to use the external authentication API to code your own authentication service. - * [Basic Rate Limiting](rate-limiting-tutorial) diff --git a/content/en/docs/3.1/howtos/istio.md b/content/en/docs/3.1/howtos/istio.md deleted file mode 100644 index 6fa74fcf..00000000 --- a/content/en/docs/3.1/howtos/istio.md +++ /dev/null @@ -1,445 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Istio integration - -$productName$ and Istio: Edge Proxy and Service Mesh together in one. $productName$ is deployed at the edge of your network and routes incoming traffic to your internal services (aka "north-south" traffic). [Istio](https://istio.io/) is a service mesh for microservices, and is designed to add application-level Layer (L7) observability, routing, and resilience to service-to-service traffic (aka "east-west" traffic). Both Istio and $productName$ are built using [Envoy](https://www.envoyproxy.io). - -$productName$ and Istio can be deployed together on Kubernetes. In this configuration, $productName$ manages -traditional edge functions such as authentication, TLS termination, and edge routing. Istio mediates communication -from $productName$ to services, and communication between services. - -This allows the operator to have the best of both worlds: a high performance, modern edge service ($productName$) combined with a state-of-the-art service mesh (Istio). While Istio has introduced a [Gateway](https://istio.io/latest/docs/tasks/traffic-management/ingress/ingress-control/#configuring-ingress-using-an-istio-gateway) abstraction, $productName$ still has a much broader feature set for edge routing than Istio. For more on this topic, see our blog post on [API Gateway vs Service Mesh](https://blog.getambassador.io/api-gateway-vs-service-mesh-104c01fa4784). - -This guide explains how to take advantage of both $productName$ and Istio to have complete control and observability over how requests are made in your cluster: - -- [Install Istio](#install-istio) and configure auto-injection -- [Install $productName$ with Istio integration](#install-edge) -- [Configure an mTLS `TLSContext`](#configure-an-mtls-tlscontext) -- [Route to services using mTLS](#route-to-services-using-mtls) - -If desired, you may also - -- [Enable strict mTLS](#enable-strict-mtls) -- [Configure Prometheus metrics collection](#configure-prometheus-metrics-collection) -- [Configure Istio distributed tracing](#configure-istio-distributed-tracing) - -To follow this guide, you need: - -- A Kubernetes cluster version 1.15 and above -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- Istio version 1.10 or higher - -## Install Istio - -Start by [installing Istio](https://istio.io/docs/setup/getting-started/). Any supported installation method for -Istio will work for use with $productName$. - -### Configure Istio Auto-Injection - -Istio functions by supplying a sidecar container running Envoy with every service in the mesh (including -$productName$). The sidecar is what enforces Istio policies for traffic to and from the service, notably -including mTLS encryption and certificate handling. As such, it is very important that the sidecar be -correctly supplied for every service in the mesh! - -While it is possible to manage sidecars by hand, it is far easier to allow Istio to automatically inject -the sidecar as necessary. To do this, set the `istio-injection` label on each Kubernetes Namespace for -which you want auto-injection: - -```yaml -kubectl label namespace $namespace istio-injection=enabled --overwrite -``` - - - The following example uses the `istio-injection` label to arrange for auto-injection in the - `$productNamespace$` Namespace below. You can manage sidecar injection by hand if you wish; what - is critical is that every service that participates in the Istio mesh have the Istio - sidecar. - - -## Install $productName$ with Istio Integration - -Properly integrating $productName$ with Istio provides support for: - -* [Mutual TLS (mTLS)](../../topics/running/tls/mtls/), with certificates managed by Istio, to allow end-to-end encryption -for east-west traffic; -* Automatic generation of Prometheus metrics for services; and -* Istio distributed tracing for end-to-end observability. - -The simplest way to enable everything is to install $productName$ using [Helm](https://helm.sh), though -you can use manual installation with YAML if you wish. - -### Installation with Helm (Recommended) - -To install with Helm, write the following YAML to a file called `istio-integration.yaml`: - -```yaml -# Listeners are required in $productName$ 2.0. -# This will create the two default Listeners for HTTP on port 8080 and HTTPS on port 8443. -createDefaultListeners: true - -# These are annotations that will be added to the $productName$ pods. -podAnnotations: - # These first two annotations tell Istio not to try to do port management for the - # $productName$ pod itself. Though these annotations are placed on the $productName$ - # pods, they are interpreted by Istio. - traffic.sidecar.istio.io/includeInboundPorts: "" # do not intercept any inbound ports - traffic.sidecar.istio.io/includeOutboundIPRanges: "" # do not intercept any outbound traffic - - # We use proxy.istio.io/config to tell the Istio proxy to write newly-generated mTLS certificates - # into /etc/istio-certs, which will be mounted below. Though this annotation is placed on the - # $productName$ pods, it is interpreted by Istio. - proxy.istio.io/config: | - proxyMetadata: - OUTPUT_CERTS: /etc/istio-certs - - # We use sidecar.istio.io/userVolumeMount to tell the Istio sidecars to mount the istio-certs - # volume at /etc/istio-certs, allowing the sidecars to see the generated certificates. Though - # this annotation is placed on the $productName$ pods, it is interpreted by Istio. - sidecar.istio.io/userVolumeMount: '[{"name": "istio-certs", "mountPath": "/etc/istio-certs"}]' - -# We define a single storage volume called "istio-certs". It starts out empty, and Istio -# uses it to communicate mTLS certs between the Istio proxy and the Istio sidecars (see the -# annotations above). -volumes: - - emptyDir: - medium: Memory - name: istio-certs - -# We also tell $productName$ to mount the "istio-certs" volume at /etc/istio-certs in the -# $productName$ pod. This gives $productName$ access to the mTLS certificates, too. -volumeMounts: - - name: istio-certs - mountPath: /etc/istio-certs/ - readOnly: true - -# Finally, we need to set some environment variables for $productName$. -env: - # AMBASSADOR_ISTIO_SECRET_DIR tells $productName$ to look for Istio mTLS certs, and to - # make them available as a secret named "istio-certs". - AMBASSADOR_ISTIO_SECRET_DIR: "/etc/istio-certs" - - # AMBASSADOR_ENVOY_BASE_ID is set to prevent collisions with the Istio sidecar's Envoy, - # which runs with base-id 0. - AMBASSADOR_ENVOY_BASE_ID: "1" -``` - -To install $productName$ with Helm, use these values to configure Istio integration: - -1. Create the `$productNamespace$` Namespace: - - ```yaml - kubectl create namespace $productNamespace$ - ``` - -2. Enable Istio auto-injection for it: - - ```yaml - kubectl label namespace $productNamespace$ istio-injection=enabled --overwrite - ``` - -3. Make sure the Helm repo is configured: - - ```bash - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - -4. Use Helm to install $productName$ in $productNamespace$: - - ```bash - helm install $productHelmName$ --namespace $productNamespace$ -f istio-integration.yaml datawire/$productHelmName$ && \ - kubectl -n $productNamespace$ wait --for condition=available --timeout=90s deploy -lapp.kubernetes.io/instance=$productDeploymentName$ - ``` - -### Installation Using YAML - -To install using YAML files, you need to manually incorporate the contents of the `istio-integration.yaml` -file shown above into your deployment YAML: - -* `pod-annotations` should be configured as Kubernetes `annotations` on the $productName$ Pods; -* `volumes`, `volumeMounts`, and `env` contents should be included in the $productDeploymentName$ Deployment; and -* you must also label the $productNamespace$ Namespace for auto-injection as described above. - -### Configuring an Existing Installation - -If you have already installed $productName$ and want to enable Istio: - -1. Install Istio. -2. Label the $productNamespace$ namespace for Istio auto-injection, as above. -2. Edit the $productName$ Deployments to contain the `annotations`, `volumes`, `volumeMounts`, and `env` elements - shown above. - * If you installed with Helm, you can use `helm upgrade` with `-f istio-integration.yaml` to modify the - installation for you. -3. Restart the $productName$ pods. - -## Configure an mTLS `TLSContext` - -After configuring $productName$ for Istio integration, the Istio mTLS certificates are available within -$productName$: - -- Both the `istio-proxy` sidecar and $productName$ mount the `istio-certs` volume at `/etc/istio-certs`. -- The `istio-proxy` sidecar saves the mTLS certificates into `/etc/istio-certs` (per the `OUTPUT_CERTS` - environment variable). -- $productName$ reads the mTLS certificates from `/etc/istio-certs` (per the `AMBASSADOR_ISTIO_SECRET_DIR` - environment variable) and creates a Secret named `istio-certs`. - - - At present, the Secret name istio-certs cannot be changed. - - -To make use of the `istio-certs` Secret, create a `TLSContext` referencing it: - - ```shell - $ kubectl apply -f - < - You must either explicitly specify port 80 in your 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 - <This guide applies to $OSSproductName$. It will not work correctly -on $AESproductName$. - -$productName$ can validate incoming requests before routing them to a backing service. In this tutorial, we'll configure $productName$ to use a simple third party rate limit service. (If you don't want to implement your own rate limiting service, $AESproductName$ integrates a [powerful, flexible rate limiting service](/docs/edge-stack/latest/topics/using/rate-limits/rate-limits/).) - -## Before you get started - -This tutorial assumes you have already followed the $productName$ [Installation](../../topics/install/) and [Quickstart Tutorial](../../tutorials/quickstart-demo) guides. If you haven't done that already, you should do so now. - -Once completed, you'll have a Kubernetes cluster running $productName$ and the Quote service. Let's walk through adding rate limiting to this setup. - -## 1. Deploy the rate limit service - -$productName$ delegates the actual rate limit logic to a third party service. We've written a [simple rate limit service](https://github.com/emissary-ingress/emissary/tree/v2.1.0/docker/test-ratelimit) that: - -- listens for requests on port 5000; -- handles gRPC `shouldRateLimit` requests; -- allows requests with the `x-ambassador-test-allow: "true"` header; and -- marks all other requests as `OVER_LIMIT`; - -Here's the YAML we'll start with: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: RateLimitService -metadata: - name: ratelimit -spec: - service: "example-rate-limit:5000" ---- -apiVersion: v1 -kind: Service -metadata: - name: example-rate-limit -spec: - type: ClusterIP - selector: - app: example-rate-limit - ports: - - port: 5000 - name: http-example-rate-limit - targetPort: http-api ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: example-rate-limit -spec: - replicas: 1 - strategy: - type: RollingUpdate - selector: - matchLabels: - app: example-rate-limit - template: - metadata: - labels: - app: example-rate-limit - spec: - containers: - - name: example-rate-limit - image: datawire/test_services:test-ratelimit:0.0.4 - imagePullPolicy: Always - ports: - - name: http-api - containerPort: 5000 - resources: - limits: - cpu: "0.1" - memory: 100Mi -``` - -This configuration tells $productName$ about the rate limit service, notably that it is serving requests at `example-rate-limit:5000`. $productName$ will see the `RateLimitService` and reconfigure itself within a few -seconds, allowing incoming requests to be rate-limited. - -Note that you can configure the `RateLimitService` to use a specific label `domain`. -If `domain` is not specified (which is the situation here), the default is `ambassador`. - -If $productName$ cannot contact the rate limit service, it will allow the request to be processed as if there were no rate limit service configuration. - -## 2. Configure $productName$ Mappings - -$productName$ only validates requests on `Mapping`s which set labels to use for rate limiting, -so you'll need to apply `labels` to your `Mapping`s to enable rate limiting. For more information -on the labelling process, see the [Rate Limits configuration documentation](../../topics/using/rate-limits/). - - - These labels require Mapping resources with apiVersion - getambassador.io/v2 or newer — if you're updating an old installation, check the - apiVersion! - - -If $productName$ cannot contact the rate limit service, it will allow the request to be processed as if there were no rate limit service configuration. - -Replace the label that is applied to the `service-backend` with: - -```yaml -labels: - ambassador: - - request_label_group: - - x-ambassador-test-allow: - request_headers: - key: "x-ambassador-test-allow" - header_name: "x-ambassador-test-allow" -``` - -so the `Mapping` definition will now look like this: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: "*" - prefix: /backend/ - service: quote - labels: - ambassador: - - request_label_group: - - x-ambassador-test-allow: - request_headers: - key: "x-ambassador-test-allow" - header_name: "x-ambassador-test-allow" -``` - - - -Note that the `key` could be anything you like, but our example rate limiting service expects it to -match the name of the header. Also note that since our `RateLimitService` expects to use labels in the -`ambassador` domain, our `Mapping` must match. - -## 2. Test rate limiting - -If we `curl` to a rate-limited URL: - -``` -$ curl -Lv -H "x-ambassador-test-allow: probably" $AMBASSADORURL/backend/ -``` - -We get a 429, since we are limited. - -``` -HTTP/1.1 429 Too Many Requests -content-type: text/html; charset=utf-8 -content-length: 0 -``` - -If we set the correct header value to the service request, we will get a quote successfully: - -``` -$ curl -Lv -H "x-ambassador-test-allow: true" $AMBASSADORURL/backend/ - -TCP_NODELAY set -* Connected to 35.196.173.175 (35.196.173.175) port 80 (#0) -> GET /backed HTTP/1.1 -> Host: 35.196.173.175 -> User-Agent: curl/7.54.0 -> Accept: */* -> -< HTTP/1.1 200 OK -< content-type: application/json -< date: Thu, 23 May 2019 15:25:06 GMT -< content-length: 172 -< x-envoy-upstream-service-time: 0 -< server: envoy -< -{ - "server": "humble-blueberry-o2v493st", - "quote": "Nihilism gambles with lives, happiness, and even destiny itself!", - "time": "2019-05-23T15:25:06.544417902Z" -* Connection #0 to host 54.165.128.189 left intact -} -``` - -## More - -For more details about configuring the external rate limit service, read the [rate limit documentation](../../topics/using/rate-limits/). diff --git a/content/en/docs/3.1/howtos/route.md b/content/en/docs/3.1/howtos/route.md deleted file mode 100644 index b2d9dc0f..00000000 --- a/content/en/docs/3.1/howtos/route.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -description: "$productName$ uses the Mapping resource to map a resource, like a URL prefix, to a Kubernetes service or web service." ---- - -import Alert from '@material-ui/lab/Alert'; - -# Get traffic from the edge - -
-

Contents

- -* [Examples](#examples) -* [Applying a Mapping Resource](#applying-a-mapping-resouce) -* [Resources](#resources) -* [Services](#services) -* [Extending Mappings](#extending-mappings) -* [Best Practices](#best-practices) -* [What's next?](#img-classos-logo-srcimageslogopng-whats-next) - -
- -The core $productName$ resource used to manage cluster ingress is the `Mapping` resource. - -**A `Mapping` resource routes a URL path (or prefix) to a service (either a Kubernetes service or other web service).** - - - Remember that Listener and Host resources are  - required for a functioning $productName$ installation that can route traffic!
- Learn more about Listener.
- Learn more about Host. - - -## Examples - -This `Mapping` would route requests to `https:///webapp/` to the `webapp-svc` Service. **This is not a -complete example on its own; see below.** - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: webapp-mapping -spec: - prefix: /webapp/ - service: webapp-svc -``` - -| Name | Type | Description | -| :--- | :--- | :--- | -| `metadata.name` | String | Identifies the Mapping. | -| `spec.prefix` | String | The URL prefix identifying your resource. [See below](#resources) on how $productName$ handles resources. | -| `spec.service` | String | The service handling the resource. If a Kubernetes service, it must include the namespace (in the format `service.namespace`) if the service is in a different namespace than $productName$. [See below](#services) on service name formatting.| - -Here's another example using a web service that maps requests to `/httpbin/` to `http://httpbin.org` (again, **this is not a -complete example on its own; see below**): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin-mapping -spec: - prefix: /httpbin/ - service: http://httpbin.org - hostname: '*' -``` - -### Complete example configuration - -For demonstration purposes, here's a possible way of combining a `Listener`, a `Host`, and both `Mapping`s above that is complete and functional: - -- it will accept HTTP or HTTPS on port 8443; -- $productName$ is terminating TLS; -- HTTPS to `foo.example.com` will be routed as above; -- HTTP to `foo.example.com` will be redirected to HTTPS; -- HTTP or HTTPS to other hostnames will be rejected; and -- the associations between the `Listener`, the `Host`, and the `Mappings` use Kubernetes `label`s. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: foo-example-secret -data: - tls.crt: -certificate PEM- - tls.key: -secret key PEM- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-8443 -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: - selector: - matchLabels: - exampleName: basic-https ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host - labels: - exampleName: basic-https -spec: - hostname: "foo.example.com" - tlsSecret: - name: foo-example-secret - selector: - matchLabels: - exampleName: basic-https ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: webapp-mapping - labels: - exampleName: basic-https -spec: - prefix: /webapp/ - service: webapp-svc - hostname: 'foo.example.com' ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin-mapping - labels: - exampleName: basic-https -spec: - prefix: /httpbin/ - service: http://httpbin.org - hostname: 'foo.example.com' - -``` - -Note the addition of `label`s and `selector`s to explicitly specify which resources should associate in this example. - - - Learn more about Listener.
- Learn more about Host. - - -## Applying a Mapping resource - -A Mapping resource can be managed using the same workflow as any other Kubernetes resources (like a Service or Deployment). For example, if the above Mapping is saved into a file called `httpbin-mapping.yaml`, the following command will apply the configuration directly to $productName$: - -``` -kubectl apply -f httpbin-mapping.yaml -``` - -For production use, best practice is to store the file in a version control system and apply the changes with a continuous deployment pipeline. The Ambassador Operating Model provides more detail. - -## Resources - -To $productName$, a resource is a group of one or more URLs that all share a common prefix in the URL path. For example, these URLs all share the `/resource1/` path prefix, so `/resource1/` can be considered a single resource: - -* `https://ambassador.example.com/resource1/foo` -* `https://ambassador.example.com/resource1/bar` -* `https://ambassador.example.com/resource1/baz/zing` - -On the other hand, these URLs share only the prefix `/` -- you _could_ tell $productName$ to treat them as a single resource, but it's probably not terribly useful. - -* `https://ambassador.example.com/resource1/foo` -* `https://ambassador.example.com/resource2/bar` -* `https://ambassador.example.com/resource3/baz/zing` - -Note that the length of the prefix doesn't matter; a prefix like `/v1/this/is/my/very/long/resource/name/` is valid. - -Also note that $productName$ does not actually require the prefix to start and end with `/` -- however, in practice, it's a good idea. Specifying a prefix of `/man` would match all of the following, which probably is not what was intended: - -* `https://ambassador.example.com/man/foo` -* `https://ambassador.example.com/mankind` -* `https://ambassador.example.com/man-it-is/really-hot-today` - -## Services - -$productName$ routes traffic to a service. A service is defined as `[scheme://]service[.namespace][:port]`. Everything except for the service is optional. - -- `scheme` can be either `http` or `https`; if not present, the default is `http`. -- `service` is the name of a service (typically the service name in Kubernetes or Consul); it is not allowed to contain the `.` character. -- `namespace` is the namespace in which the service is running. Starting with $productName$ 1.0.0, if not supplied, it defaults to the namespace in which the Mapping resource is defined. The default behavior can be configured using the [Module resource](../../topics/running/ambassador). When using a Consul resolver, `namespace` is not allowed. -- `port` is the port to which a request should be sent. If not specified, it defaults to `80` when the scheme is `http` or `443` when the scheme is `https`. Note that the [resolver](../../topics/running/resolvers) may return a port in which case the `port` setting is ignored. - -While using service.namespace.svc.cluster.local may work for Kubernetes resolvers, the preferred syntax is service.namespace. - - -## Extending Mappings - -Mapping resources support a rich set of annotations to customize the specific routing behavior. Here's an example service for implementing the [CQRS pattern](https://docs.microsoft.com/en-us/azure/architecture/patterns/cqrs) (using HTTP): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-get -spec: - prefix: /cqrs/ - method: GET - service: getcqrs - hostname: '*' ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-put -spec: - prefix: /cqrs/ - method: PUT - service: putcqrs - hostname: '*' -``` - -## Best Practices - -$productName$'s configuration is assembled from multiple YAML blocks which are managed by independent application teams. This implies that certain best practices should be followed. - -#### $productName$'s configuration should be under version control. - -While you can always read back the $productName$'s configuration from Kubernetes or its diagnostic service, the $productName$ will not do versioning for you. - -#### $productName$ tries to not start with a broken configuration, but it's not perfect. - -Gross errors will result in the $productName$ refusing to start, in which case `kubectl logs` will be helpful. However, it's always possible to map a resource to the wrong service, or use the wrong `rewrite` rules. $productName$ can't detect that on its own, although its [diagnostic service](../../topics/running/diagnostics/) can help you figure it out. - -#### Be careful of mapping collisions. - -If two different developers try to map `/myservice/` to something, this can lead to unexpected behavior. $productName$'s [canary deployment](../../topics/using/canary/) logic means that it's more likely that traffic will be split between them than that it will throw an error -- again, the diagnostic service can help you here. - -#### Unless specified, mapping attributes cannot be applied to any other resource type. - -## 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/content/en/docs/3.1/howtos/tls-termination.md b/content/en/docs/3.1/howtos/tls-termination.md deleted file mode 100644 index d634c76b..00000000 --- a/content/en/docs/3.1/howtos/tls-termination.md +++ /dev/null @@ -1,195 +0,0 @@ -# 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 - selector: - matchLabels: - hostname: wildcard-host -``` - -**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/content/en/docs/3.1/howtos/tracing-datadog.md b/content/en/docs/3.1/howtos/tracing-datadog.md deleted file mode 100644 index d627e29f..00000000 --- a/content/en/docs/3.1/howtos/tracing-datadog.md +++ /dev/null @@ -1,63 +0,0 @@ -# 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/content/en/docs/3.1/howtos/tracing-zipkin.md b/content/en/docs/3.1/howtos/tracing-zipkin.md deleted file mode 100644 index 37ddc902..00000000 --- a/content/en/docs/3.1/howtos/tracing-zipkin.md +++ /dev/null @@ -1,129 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Distributed tracing with Zipkin - -In this tutorial, we'll configure $productName$ to initiate a trace on some sample requests, and use Zipkin 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. Deploy Zipkin - -In this tutorial, you will use a simple deployment of the open-source [Zipkin](https://github.com/openzipkin/zipkin/wiki) distributed tracing system to store and visualize $productName$-generated traces. The trace data will be stored in memory within the Zipkin container, and you will be able to explore the traces via the Zipkin web UI. - -First, add the following YAML to a file named `zipkin.yaml`. This configuration will create a Zipkin Deployment that uses the [openzipkin/zipkin](https://hub.docker.com/r/openzipkin/zipkin/) container image and also an associated Service. We will also include a `TracingService` that configures $productName$ to use the Zipkin service (running on the default port of 9411) to provide tracing support. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TracingService -metadata: - name: tracing -spec: - service: "zipkin:9411" - driver: zipkin - config: {} ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: zipkin -spec: - replicas: 1 - selector: - matchLabels: - app: zipkin - template: - metadata: - labels: - app: zipkin - spec: - containers: - - name: zipkin - image: openzipkin/zipkin - env: - # note: in-memory storage holds all data in memory, purging older data upon a span limit. - # you should use a proper storage in production environments - - name: STORAGE_TYPE - value: mem ---- -apiVersion: v1 -kind: Service -metadata: - labels: - name: zipkin - name: zipkin -spec: - ports: - - port: 9411 - targetPort: 9411 - selector: - app: zipkin -``` - -Next, deploy this configuration into your cluster: - -``` -$ kubectl apply -f zipkin.yaml -``` - -As a final step we want to restart $productName$ as this is necessary to add the tracing header. This command will restart all the Pods (assuming $productName$ is installed in the ambassador namespace): - -``` -$ kubectl -n ambassador rollout restart deploy -``` - - Restarting $productName$ is required after deploying a Tracing Service for changes to take effect. - - -## 2. 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/backend/ -``` - -## 3. Test traces - -To test things out, we'll need to access the Zipkin UI. If you're on Kubernetes, get the name of the Zipkin pod: - -``` -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -ambassador-5ffcfc798-c25dc 2/2 Running 0 1d -prometheus-prometheus-0 2/2 Running 0 113d -zipkin-868b97667c-58v4r 1/1 Running 0 2h -``` - -And then use `kubectl port-forward` to access the pod: - -``` -$ kubectl port-forward zipkin-868b97667c-58v4r 9411 -``` - -Open your web browser to `http://localhost:9411` for the Zipkin UI. - -If you're on `minikube` you can access the `NodePort` directly, and this ports number can be obtained via the `minikube services list` command. If you are using `Docker for Mac/Windows`, you can use the `kubectl get svc` command to get the same information. - -``` -$ minikube service list -|-------------|----------------------|-----------------------------| -| NAMESPACE | NAME | URL | -|-------------|----------------------|-----------------------------| -| default | ambassador-admin | http://192.168.99.107:30319 | -| default | ambassador | http://192.168.99.107:31893 | -| default | zipkin | http://192.168.99.107:31043 | -|-------------|----------------------|-----------------------------| -``` - -Open your web browser to the Zipkin dashboard `http://192.168.99.107:31043/zipkin/`. - -In the Zipkin UI, click on the "Find Traces" button to get a listing instrumented traces. Each of the traces that are displayed can be clicked on, which provides further information about each span and associated metadata. - -## Learn more - -For more details about configuring the external tracing service, read the documentation on [external tracing](../../topics/running/services/tracing-service). diff --git a/content/en/docs/3.1/howtos/websockets.md b/content/en/docs/3.1/howtos/websockets.md deleted file mode 100644 index 25cac7da..00000000 --- a/content/en/docs/3.1/howtos/websockets.md +++ /dev/null @@ -1,43 +0,0 @@ -# WebSocket connections - -$productName$ makes it easy to access your services from outside your -application, and this includes services that use WebSockets. Only a -small amount of additional configuration is required, which is as -simple as telling the Mapping to allow "upgrading" from the HTTP protocol to -the "websocket" protocol: - -```yaml -allow_upgrade: -- websocket -``` - -## Example WebSocket service - -The example configuration below demonstrates the addition of the `allow_upgrade:` attribute to support websockets. The use of `use_websocket` is now deprecated. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: my-service-mapping -spec: - hostname: "*" - prefix: /my-service/ - service: my-service - allow_upgrade: - - websocket - ---- -kind: Service -apiVersion: v1 -metadata: - name: my-service -spec: - selector: - app: MyApp - ports: - - protocol: TCP - port: 80 - targetPort: 9376 -``` diff --git a/content/en/docs/3.1/images/Auth0_JWT.png b/content/en/docs/3.1/images/Auth0_JWT.png deleted file mode 100644 index e18155f5..00000000 Binary files a/content/en/docs/3.1/images/Auth0_JWT.png and /dev/null differ diff --git a/content/en/docs/3.1/images/Auth0_domain_clientID.png b/content/en/docs/3.1/images/Auth0_domain_clientID.png deleted file mode 100644 index a7f8edf6..00000000 Binary files a/content/en/docs/3.1/images/Auth0_domain_clientID.png and /dev/null differ diff --git a/content/en/docs/3.1/images/Auth0_method_callback_origins.png b/content/en/docs/3.1/images/Auth0_method_callback_origins.png deleted file mode 100644 index 8d31138e..00000000 Binary files a/content/en/docs/3.1/images/Auth0_method_callback_origins.png and /dev/null differ diff --git a/content/en/docs/3.1/images/aes-success.png b/content/en/docs/3.1/images/aes-success.png deleted file mode 100644 index 66f28d3f..00000000 Binary files a/content/en/docs/3.1/images/aes-success.png and /dev/null differ diff --git a/content/en/docs/3.1/images/ambassador-arch.png b/content/en/docs/3.1/images/ambassador-arch.png deleted file mode 100644 index 5a5cb652..00000000 Binary files a/content/en/docs/3.1/images/ambassador-arch.png and /dev/null differ diff --git a/content/en/docs/3.1/images/ambassador-logo.svg b/content/en/docs/3.1/images/ambassador-logo.svg deleted file mode 100644 index 1f0e06a8..00000000 --- a/content/en/docs/3.1/images/ambassador-logo.svg +++ /dev/null @@ -1,49 +0,0 @@ - - - - ambassador logo@1x - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.1/images/ambassador_oidc_flow.jpg b/content/en/docs/3.1/images/ambassador_oidc_flow.jpg deleted file mode 100644 index 4f1c0c7e..00000000 Binary files a/content/en/docs/3.1/images/ambassador_oidc_flow.jpg and /dev/null differ diff --git a/content/en/docs/3.1/images/apple.png b/content/en/docs/3.1/images/apple.png deleted file mode 100644 index 8b8277f1..00000000 Binary files a/content/en/docs/3.1/images/apple.png and /dev/null differ diff --git a/content/en/docs/3.1/images/auth-flow.png b/content/en/docs/3.1/images/auth-flow.png deleted file mode 100644 index e1ba4387..00000000 Binary files a/content/en/docs/3.1/images/auth-flow.png and /dev/null differ diff --git a/content/en/docs/3.1/images/authentication-icon.svg b/content/en/docs/3.1/images/authentication-icon.svg deleted file mode 100644 index 342e8a3d..00000000 --- a/content/en/docs/3.1/images/authentication-icon.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_897228_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.1/images/blackbird.png b/content/en/docs/3.1/images/blackbird.png deleted file mode 100644 index 1f10e5cc..00000000 Binary files a/content/en/docs/3.1/images/blackbird.png and /dev/null differ diff --git a/content/en/docs/3.1/images/canary-release-overview.png b/content/en/docs/3.1/images/canary-release-overview.png deleted file mode 100644 index c683a23d..00000000 Binary files a/content/en/docs/3.1/images/canary-release-overview.png and /dev/null differ diff --git a/content/en/docs/3.1/images/configure-icon.svg b/content/en/docs/3.1/images/configure-icon.svg deleted file mode 100644 index 0f556840..00000000 --- a/content/en/docs/3.1/images/configure-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_858572_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.1/images/consul-ambassador.png b/content/en/docs/3.1/images/consul-ambassador.png deleted file mode 100644 index c4911624..00000000 Binary files a/content/en/docs/3.1/images/consul-ambassador.png and /dev/null differ diff --git a/content/en/docs/3.1/images/container-inner-dev-loop.png b/content/en/docs/3.1/images/container-inner-dev-loop.png deleted file mode 100644 index 06586cd6..00000000 Binary files a/content/en/docs/3.1/images/container-inner-dev-loop.png and /dev/null differ diff --git a/content/en/docs/3.1/images/datawire-logo.svg b/content/en/docs/3.1/images/datawire-logo.svg deleted file mode 100644 index fb45872c..00000000 --- a/content/en/docs/3.1/images/datawire-logo.svg +++ /dev/null @@ -1,27 +0,0 @@ - - - - Group 3 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.1/images/diagnostics-example.png b/content/en/docs/3.1/images/diagnostics-example.png deleted file mode 100644 index 6c825b0c..00000000 Binary files a/content/en/docs/3.1/images/diagnostics-example.png and /dev/null differ diff --git a/content/en/docs/3.1/images/diagnostics.png b/content/en/docs/3.1/images/diagnostics.png deleted file mode 100644 index 29248703..00000000 Binary files a/content/en/docs/3.1/images/diagnostics.png and /dev/null differ diff --git a/content/en/docs/3.1/images/docker-compose.png b/content/en/docs/3.1/images/docker-compose.png deleted file mode 100644 index b8829521..00000000 Binary files a/content/en/docs/3.1/images/docker-compose.png and /dev/null differ diff --git a/content/en/docs/3.1/images/docker.png b/content/en/docs/3.1/images/docker.png deleted file mode 100644 index 1f35e5ea..00000000 Binary files a/content/en/docs/3.1/images/docker.png and /dev/null differ diff --git a/content/en/docs/3.1/images/edge-stack-1.13.4.png b/content/en/docs/3.1/images/edge-stack-1.13.4.png deleted file mode 100644 index 954ac1a9..00000000 Binary files a/content/en/docs/3.1/images/edge-stack-1.13.4.png and /dev/null differ diff --git a/content/en/docs/3.1/images/edge-stack-1.13.7-json-logging.png b/content/en/docs/3.1/images/edge-stack-1.13.7-json-logging.png deleted file mode 100644 index 4a47cbdf..00000000 Binary files a/content/en/docs/3.1/images/edge-stack-1.13.7-json-logging.png and /dev/null differ diff --git a/content/en/docs/3.1/images/edge-stack-1.13.7-memory.png b/content/en/docs/3.1/images/edge-stack-1.13.7-memory.png deleted file mode 100644 index 9c415ba3..00000000 Binary files a/content/en/docs/3.1/images/edge-stack-1.13.7-memory.png and /dev/null differ diff --git a/content/en/docs/3.1/images/edge-stack-1.13.7-tcpmapping-consul.png b/content/en/docs/3.1/images/edge-stack-1.13.7-tcpmapping-consul.png deleted file mode 100644 index c455a47f..00000000 Binary files a/content/en/docs/3.1/images/edge-stack-1.13.7-tcpmapping-consul.png and /dev/null differ diff --git a/content/en/docs/3.1/images/edge-stack-1.13.8-cloud-bugfix.png b/content/en/docs/3.1/images/edge-stack-1.13.8-cloud-bugfix.png deleted file mode 100644 index 6beaf653..00000000 Binary files a/content/en/docs/3.1/images/edge-stack-1.13.8-cloud-bugfix.png and /dev/null differ diff --git a/content/en/docs/3.1/images/emissary-1.13.10-cors-origin.png b/content/en/docs/3.1/images/emissary-1.13.10-cors-origin.png deleted file mode 100644 index b7538e5f..00000000 Binary files a/content/en/docs/3.1/images/emissary-1.13.10-cors-origin.png and /dev/null differ diff --git a/content/en/docs/3.1/images/fast-icon.svg b/content/en/docs/3.1/images/fast-icon.svg deleted file mode 100644 index 354542ee..00000000 --- a/content/en/docs/3.1/images/fast-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1187990_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.1/images/features-icons/basic-authentication.svg b/content/en/docs/3.1/images/features-icons/basic-authentication.svg deleted file mode 100644 index 2bd19edf..00000000 --- a/content/en/docs/3.1/images/features-icons/basic-authentication.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_897228_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.1/images/features-icons/canary-release.svg b/content/en/docs/3.1/images/features-icons/canary-release.svg deleted file mode 100644 index f8de57d9..00000000 --- a/content/en/docs/3.1/images/features-icons/canary-release.svg +++ /dev/null @@ -1,27 +0,0 @@ - - - - Group 25 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.1/images/features-icons/cors.svg b/content/en/docs/3.1/images/features-icons/cors.svg deleted file mode 100644 index e559d924..00000000 --- a/content/en/docs/3.1/images/features-icons/cors.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_111967_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.1/images/features-icons/datadog.png b/content/en/docs/3.1/images/features-icons/datadog.png deleted file mode 100644 index eea05f8c..00000000 Binary files a/content/en/docs/3.1/images/features-icons/datadog.png and /dev/null differ diff --git a/content/en/docs/3.1/images/features-icons/datadog.svg b/content/en/docs/3.1/images/features-icons/datadog.svg deleted file mode 100644 index e46e8118..00000000 --- a/content/en/docs/3.1/images/features-icons/datadog.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Screen Shot 2018-04-05 at 8.22.25 AM - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.1/images/features-icons/diagnostics.svg b/content/en/docs/3.1/images/features-icons/diagnostics.svg deleted file mode 100644 index 940e1bc2..00000000 --- a/content/en/docs/3.1/images/features-icons/diagnostics.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_196445_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.1/images/features-icons/distributed-tracing.png b/content/en/docs/3.1/images/features-icons/distributed-tracing.png deleted file mode 100644 index 6b69e28c..00000000 Binary files a/content/en/docs/3.1/images/features-icons/distributed-tracing.png and /dev/null differ diff --git a/content/en/docs/3.1/images/features-icons/grpc.png b/content/en/docs/3.1/images/features-icons/grpc.png deleted file mode 100644 index b2f5a0d9..00000000 Binary files a/content/en/docs/3.1/images/features-icons/grpc.png and /dev/null differ diff --git a/content/en/docs/3.1/images/features-icons/prometheus.svg b/content/en/docs/3.1/images/features-icons/prometheus.svg deleted file mode 100644 index d5252a66..00000000 --- a/content/en/docs/3.1/images/features-icons/prometheus.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - prometheus_logo_grey - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.1/images/features-icons/rate-limiting.svg b/content/en/docs/3.1/images/features-icons/rate-limiting.svg deleted file mode 100644 index f1b6eacb..00000000 --- a/content/en/docs/3.1/images/features-icons/rate-limiting.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - Group 10 - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.1/images/features-icons/regex-routing.svg b/content/en/docs/3.1/images/features-icons/regex-routing.svg deleted file mode 100644 index 113b53b5..00000000 --- a/content/en/docs/3.1/images/features-icons/regex-routing.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_699774_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.1/images/features-icons/request-transformers.svg b/content/en/docs/3.1/images/features-icons/request-transformers.svg deleted file mode 100644 index 0b13e2dc..00000000 --- a/content/en/docs/3.1/images/features-icons/request-transformers.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_96239_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.1/images/features-icons/shadowing.svg b/content/en/docs/3.1/images/features-icons/shadowing.svg deleted file mode 100644 index 9e85eee1..00000000 --- a/content/en/docs/3.1/images/features-icons/shadowing.svg +++ /dev/null @@ -1,15 +0,0 @@ - - - - shadow - Created with Sketch. - - - - - - - - - - diff --git a/content/en/docs/3.1/images/features-icons/statsd.png b/content/en/docs/3.1/images/features-icons/statsd.png deleted file mode 100644 index 28374438..00000000 Binary files a/content/en/docs/3.1/images/features-icons/statsd.png and /dev/null differ diff --git a/content/en/docs/3.1/images/features-icons/statsd.svg b/content/en/docs/3.1/images/features-icons/statsd.svg deleted file mode 100644 index cabc90db..00000000 --- a/content/en/docs/3.1/images/features-icons/statsd.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - 88eb31f74479e422e4e9abfc6c2b00ee - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.1/images/features-icons/third-party-auth.svg b/content/en/docs/3.1/images/features-icons/third-party-auth.svg deleted file mode 100644 index 5359a24a..00000000 --- a/content/en/docs/3.1/images/features-icons/third-party-auth.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_511233_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.1/images/features-icons/timeouts.svg b/content/en/docs/3.1/images/features-icons/timeouts.svg deleted file mode 100644 index 47f63056..00000000 --- a/content/en/docs/3.1/images/features-icons/timeouts.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_587034_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.1/images/features-icons/tls-termination.svg b/content/en/docs/3.1/images/features-icons/tls-termination.svg deleted file mode 100644 index 6a631a96..00000000 --- a/content/en/docs/3.1/images/features-icons/tls-termination.svg +++ /dev/null @@ -1,17 +0,0 @@ - - - - noun_63544_cc - Created with Sketch. - - - - - - - - - - - - diff --git a/content/en/docs/3.1/images/features-icons/url-rewrite.svg b/content/en/docs/3.1/images/features-icons/url-rewrite.svg deleted file mode 100644 index 023e2e05..00000000 --- a/content/en/docs/3.1/images/features-icons/url-rewrite.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1295942_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.1/images/features-icons/websockets.svg b/content/en/docs/3.1/images/features-icons/websockets.svg deleted file mode 100644 index af17b9c0..00000000 --- a/content/en/docs/3.1/images/features-icons/websockets.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - noun_50814_cc - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.1/images/features-table.jpg b/content/en/docs/3.1/images/features-table.jpg deleted file mode 100644 index 3de2eb4f..00000000 Binary files a/content/en/docs/3.1/images/features-table.jpg and /dev/null differ diff --git a/content/en/docs/3.1/images/gRPC-TLS-Ambassador.png b/content/en/docs/3.1/images/gRPC-TLS-Ambassador.png deleted file mode 100644 index 0189253e..00000000 Binary files a/content/en/docs/3.1/images/gRPC-TLS-Ambassador.png and /dev/null differ diff --git a/content/en/docs/3.1/images/gRPC-TLS-Originate.png b/content/en/docs/3.1/images/gRPC-TLS-Originate.png deleted file mode 100644 index 1b62010d..00000000 Binary files a/content/en/docs/3.1/images/gRPC-TLS-Originate.png and /dev/null differ diff --git a/content/en/docs/3.1/images/github-login.png b/content/en/docs/3.1/images/github-login.png deleted file mode 100644 index cfd4d4bf..00000000 Binary files a/content/en/docs/3.1/images/github-login.png and /dev/null differ diff --git a/content/en/docs/3.1/images/global-features-bg.svg b/content/en/docs/3.1/images/global-features-bg.svg deleted file mode 100644 index a39c5232..00000000 --- a/content/en/docs/3.1/images/global-features-bg.svg +++ /dev/null @@ -1,34 +0,0 @@ - - - - ambassador_logo@2x - Created with Sketch. - - - - - - - - diff --git a/content/en/docs/3.1/images/grafana.png b/content/en/docs/3.1/images/grafana.png deleted file mode 100644 index befe3377..00000000 Binary files a/content/en/docs/3.1/images/grafana.png and /dev/null differ diff --git a/content/en/docs/3.1/images/grpc-tls.png b/content/en/docs/3.1/images/grpc-tls.png deleted file mode 100644 index 4d705ff0..00000000 Binary files a/content/en/docs/3.1/images/grpc-tls.png and /dev/null differ diff --git a/content/en/docs/3.1/images/helm-navy.png b/content/en/docs/3.1/images/helm-navy.png deleted file mode 100644 index a9710143..00000000 Binary files a/content/en/docs/3.1/images/helm-navy.png and /dev/null differ diff --git a/content/en/docs/3.1/images/helm.png b/content/en/docs/3.1/images/helm.png deleted file mode 100644 index 1c5af71b..00000000 Binary files a/content/en/docs/3.1/images/helm.png and /dev/null differ diff --git a/content/en/docs/3.1/images/highly-available-icon.svg b/content/en/docs/3.1/images/highly-available-icon.svg deleted file mode 100644 index 9cb3eff9..00000000 --- a/content/en/docs/3.1/images/highly-available-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1205522_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.1/images/jaeger.png b/content/en/docs/3.1/images/jaeger.png deleted file mode 100644 index 3b821c09..00000000 Binary files a/content/en/docs/3.1/images/jaeger.png and /dev/null differ diff --git a/content/en/docs/3.1/images/kubernetes.png b/content/en/docs/3.1/images/kubernetes.png deleted file mode 100644 index a392a886..00000000 Binary files a/content/en/docs/3.1/images/kubernetes.png and /dev/null differ diff --git a/content/en/docs/3.1/images/left-arrow.svg b/content/en/docs/3.1/images/left-arrow.svg deleted file mode 100644 index 75cdc7f1..00000000 --- a/content/en/docs/3.1/images/left-arrow.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Path 2 - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.1/images/linux.png b/content/en/docs/3.1/images/linux.png deleted file mode 100644 index 1832c594..00000000 Binary files a/content/en/docs/3.1/images/linux.png and /dev/null differ diff --git a/content/en/docs/3.1/images/logo.png b/content/en/docs/3.1/images/logo.png deleted file mode 100644 index 701f63ba..00000000 Binary files a/content/en/docs/3.1/images/logo.png and /dev/null differ diff --git a/content/en/docs/3.1/images/mapping-editor.png b/content/en/docs/3.1/images/mapping-editor.png deleted file mode 100644 index f8b751a1..00000000 Binary files a/content/en/docs/3.1/images/mapping-editor.png and /dev/null differ diff --git a/content/en/docs/3.1/images/network-architecture.png b/content/en/docs/3.1/images/network-architecture.png deleted file mode 100644 index 3217b3e1..00000000 Binary files a/content/en/docs/3.1/images/network-architecture.png and /dev/null differ diff --git a/content/en/docs/3.1/images/penguin-background.svg b/content/en/docs/3.1/images/penguin-background.svg deleted file mode 100644 index 7affc0d5..00000000 --- a/content/en/docs/3.1/images/penguin-background.svg +++ /dev/null @@ -1,102 +0,0 @@ - - - - @2xambassador_logo - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.1/images/pro-iap.png b/content/en/docs/3.1/images/pro-iap.png deleted file mode 100644 index 787265d8..00000000 Binary files a/content/en/docs/3.1/images/pro-iap.png and /dev/null differ diff --git a/content/en/docs/3.1/images/quote.svg b/content/en/docs/3.1/images/quote.svg deleted file mode 100644 index bab6e871..00000000 --- a/content/en/docs/3.1/images/quote.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - “ - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.1/images/right-arrow.svg b/content/en/docs/3.1/images/right-arrow.svg deleted file mode 100644 index 627144c6..00000000 --- a/content/en/docs/3.1/images/right-arrow.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Path 2 Copy - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.1/images/routing-icon.svg b/content/en/docs/3.1/images/routing-icon.svg deleted file mode 100644 index bd860b13..00000000 --- a/content/en/docs/3.1/images/routing-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1062254_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.1/images/self-service-features-bg.svg b/content/en/docs/3.1/images/self-service-features-bg.svg deleted file mode 100644 index 40bc400a..00000000 --- a/content/en/docs/3.1/images/self-service-features-bg.svg +++ /dev/null @@ -1,93 +0,0 @@ - - - - Group 8 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - SELF-SERVICE FEATURES - - - - diff --git a/content/en/docs/3.1/images/shadowing.png b/content/en/docs/3.1/images/shadowing.png deleted file mode 100644 index 097ecbd5..00000000 Binary files a/content/en/docs/3.1/images/shadowing.png and /dev/null differ diff --git a/content/en/docs/3.1/images/speedometers.png b/content/en/docs/3.1/images/speedometers.png deleted file mode 100644 index 7ce2c2a2..00000000 Binary files a/content/en/docs/3.1/images/speedometers.png and /dev/null differ diff --git a/content/en/docs/3.1/images/tp-architecture.png b/content/en/docs/3.1/images/tp-architecture.png deleted file mode 100644 index 20ae3589..00000000 Binary files a/content/en/docs/3.1/images/tp-architecture.png and /dev/null differ diff --git a/content/en/docs/3.1/images/tp-tutorial-1.png b/content/en/docs/3.1/images/tp-tutorial-1.png deleted file mode 100644 index ee68dc7d..00000000 Binary files a/content/en/docs/3.1/images/tp-tutorial-1.png and /dev/null differ diff --git a/content/en/docs/3.1/images/tp-tutorial-2.png b/content/en/docs/3.1/images/tp-tutorial-2.png deleted file mode 100644 index 129dc6ee..00000000 Binary files a/content/en/docs/3.1/images/tp-tutorial-2.png and /dev/null differ diff --git a/content/en/docs/3.1/images/tp-tutorial-3.png b/content/en/docs/3.1/images/tp-tutorial-3.png deleted file mode 100644 index 946629fc..00000000 Binary files a/content/en/docs/3.1/images/tp-tutorial-3.png and /dev/null differ diff --git a/content/en/docs/3.1/images/tp-tutorial-4.png b/content/en/docs/3.1/images/tp-tutorial-4.png deleted file mode 100644 index cb6e7a9d..00000000 Binary files a/content/en/docs/3.1/images/tp-tutorial-4.png and /dev/null differ diff --git a/content/en/docs/3.1/images/trad-inner-dev-loop.png b/content/en/docs/3.1/images/trad-inner-dev-loop.png deleted file mode 100644 index 618b674f..00000000 Binary files a/content/en/docs/3.1/images/trad-inner-dev-loop.png and /dev/null differ diff --git a/content/en/docs/3.1/images/windows.png b/content/en/docs/3.1/images/windows.png deleted file mode 100644 index a065dc17..00000000 Binary files a/content/en/docs/3.1/images/windows.png and /dev/null differ diff --git a/content/en/docs/3.1/images/xkcd.png b/content/en/docs/3.1/images/xkcd.png deleted file mode 100644 index ed0d5c33..00000000 Binary files a/content/en/docs/3.1/images/xkcd.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/edge-stack-1.13.4.png b/content/en/docs/3.1/release-notes/edge-stack-1.13.4.png deleted file mode 100644 index 954ac1a9..00000000 Binary files a/content/en/docs/3.1/release-notes/edge-stack-1.13.4.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/edge-stack-1.13.7-json-logging.png b/content/en/docs/3.1/release-notes/edge-stack-1.13.7-json-logging.png deleted file mode 100644 index 4a47cbdf..00000000 Binary files a/content/en/docs/3.1/release-notes/edge-stack-1.13.7-json-logging.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/edge-stack-1.13.7-memory.png b/content/en/docs/3.1/release-notes/edge-stack-1.13.7-memory.png deleted file mode 100644 index 9c415ba3..00000000 Binary files a/content/en/docs/3.1/release-notes/edge-stack-1.13.7-memory.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/edge-stack-1.13.7-tcpmapping-consul.png b/content/en/docs/3.1/release-notes/edge-stack-1.13.7-tcpmapping-consul.png deleted file mode 100644 index c455a47f..00000000 Binary files a/content/en/docs/3.1/release-notes/edge-stack-1.13.7-tcpmapping-consul.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/edge-stack-1.13.8-cloud-bugfix.png b/content/en/docs/3.1/release-notes/edge-stack-1.13.8-cloud-bugfix.png deleted file mode 100644 index 6beaf653..00000000 Binary files a/content/en/docs/3.1/release-notes/edge-stack-1.13.8-cloud-bugfix.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/edge-stack-2.0.0-host_crd.png b/content/en/docs/3.1/release-notes/edge-stack-2.0.0-host_crd.png deleted file mode 100644 index c77ef528..00000000 Binary files a/content/en/docs/3.1/release-notes/edge-stack-2.0.0-host_crd.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/edge-stack-2.0.0-ingressstatus.png b/content/en/docs/3.1/release-notes/edge-stack-2.0.0-ingressstatus.png deleted file mode 100644 index 6856d308..00000000 Binary files a/content/en/docs/3.1/release-notes/edge-stack-2.0.0-ingressstatus.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/edge-stack-2.0.0-insecure_action_hosts.png b/content/en/docs/3.1/release-notes/edge-stack-2.0.0-insecure_action_hosts.png deleted file mode 100644 index 79c20bad..00000000 Binary files a/content/en/docs/3.1/release-notes/edge-stack-2.0.0-insecure_action_hosts.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/edge-stack-2.0.0-listener.png b/content/en/docs/3.1/release-notes/edge-stack-2.0.0-listener.png deleted file mode 100644 index ea45a02b..00000000 Binary files a/content/en/docs/3.1/release-notes/edge-stack-2.0.0-listener.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/edge-stack-2.0.0-prune_routes.png b/content/en/docs/3.1/release-notes/edge-stack-2.0.0-prune_routes.png deleted file mode 100644 index bc43229f..00000000 Binary files a/content/en/docs/3.1/release-notes/edge-stack-2.0.0-prune_routes.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/edge-stack-2.0.0-tlscontext.png b/content/en/docs/3.1/release-notes/edge-stack-2.0.0-tlscontext.png deleted file mode 100644 index 68dbad80..00000000 Binary files a/content/en/docs/3.1/release-notes/edge-stack-2.0.0-tlscontext.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/edge-stack-2.0.0-v3alpha1.png b/content/en/docs/3.1/release-notes/edge-stack-2.0.0-v3alpha1.png deleted file mode 100644 index c0ac3596..00000000 Binary files a/content/en/docs/3.1/release-notes/edge-stack-2.0.0-v3alpha1.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/emissary-1.13.10-cors-origin.png b/content/en/docs/3.1/release-notes/emissary-1.13.10-cors-origin.png deleted file mode 100644 index b7538e5f..00000000 Binary files a/content/en/docs/3.1/release-notes/emissary-1.13.10-cors-origin.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/emissary-ga.png b/content/en/docs/3.1/release-notes/emissary-ga.png deleted file mode 100644 index 062f043a..00000000 Binary files a/content/en/docs/3.1/release-notes/emissary-ga.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/tada.png b/content/en/docs/3.1/release-notes/tada.png deleted file mode 100644 index c8832e8e..00000000 Binary files a/content/en/docs/3.1/release-notes/tada.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/v2.0.4-k8s-1.22.png b/content/en/docs/3.1/release-notes/v2.0.4-k8s-1.22.png deleted file mode 100644 index ed9b0415..00000000 Binary files a/content/en/docs/3.1/release-notes/v2.0.4-k8s-1.22.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/v2.0.4-l7depth.png b/content/en/docs/3.1/release-notes/v2.0.4-l7depth.png deleted file mode 100644 index 9314324c..00000000 Binary files a/content/en/docs/3.1/release-notes/v2.0.4-l7depth.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/v2.0.4-mapping-dns-type.png b/content/en/docs/3.1/release-notes/v2.0.4-mapping-dns-type.png deleted file mode 100644 index 7770c77d..00000000 Binary files a/content/en/docs/3.1/release-notes/v2.0.4-mapping-dns-type.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/v2.0.4-v3alpha1.png b/content/en/docs/3.1/release-notes/v2.0.4-v3alpha1.png deleted file mode 100644 index 9c50b8fb..00000000 Binary files a/content/en/docs/3.1/release-notes/v2.0.4-v3alpha1.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/v2.0.4-version.png b/content/en/docs/3.1/release-notes/v2.0.4-version.png deleted file mode 100644 index 9481b7db..00000000 Binary files a/content/en/docs/3.1/release-notes/v2.0.4-version.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/v2.0.5-auth-circuit-breaker.png b/content/en/docs/3.1/release-notes/v2.0.5-auth-circuit-breaker.png deleted file mode 100644 index cac8cf7b..00000000 Binary files a/content/en/docs/3.1/release-notes/v2.0.5-auth-circuit-breaker.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/v2.0.5-mappingselector.png b/content/en/docs/3.1/release-notes/v2.0.5-mappingselector.png deleted file mode 100644 index 31942ede..00000000 Binary files a/content/en/docs/3.1/release-notes/v2.0.5-mappingselector.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/v2.1.0-canary.png b/content/en/docs/3.1/release-notes/v2.1.0-canary.png deleted file mode 100644 index 39d3bbbf..00000000 Binary files a/content/en/docs/3.1/release-notes/v2.1.0-canary.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/v2.1.0-gzip-enabled.png b/content/en/docs/3.1/release-notes/v2.1.0-gzip-enabled.png deleted file mode 100644 index 061fcbc9..00000000 Binary files a/content/en/docs/3.1/release-notes/v2.1.0-gzip-enabled.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/v2.1.0-smoother-migration.png b/content/en/docs/3.1/release-notes/v2.1.0-smoother-migration.png deleted file mode 100644 index ebd77497..00000000 Binary files a/content/en/docs/3.1/release-notes/v2.1.0-smoother-migration.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/v2.1.2-annotations.png b/content/en/docs/3.1/release-notes/v2.1.2-annotations.png deleted file mode 100644 index b5498c3c..00000000 Binary files a/content/en/docs/3.1/release-notes/v2.1.2-annotations.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/v2.1.2-host-mapping-matching.png b/content/en/docs/3.1/release-notes/v2.1.2-host-mapping-matching.png deleted file mode 100644 index 1cfba5ed..00000000 Binary files a/content/en/docs/3.1/release-notes/v2.1.2-host-mapping-matching.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/v2.1.2-mapping-cors.png b/content/en/docs/3.1/release-notes/v2.1.2-mapping-cors.png deleted file mode 100644 index f76ea01c..00000000 Binary files a/content/en/docs/3.1/release-notes/v2.1.2-mapping-cors.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/v2.1.2-mapping-less-weighted.png b/content/en/docs/3.1/release-notes/v2.1.2-mapping-less-weighted.png deleted file mode 100644 index 7e299062..00000000 Binary files a/content/en/docs/3.1/release-notes/v2.1.2-mapping-less-weighted.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/v2.1.2-mapping-no-rewrite.png b/content/en/docs/3.1/release-notes/v2.1.2-mapping-no-rewrite.png deleted file mode 100644 index 5d3d5a29..00000000 Binary files a/content/en/docs/3.1/release-notes/v2.1.2-mapping-no-rewrite.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/v2.2.0-cloud.png b/content/en/docs/3.1/release-notes/v2.2.0-cloud.png deleted file mode 100644 index 5923fcb4..00000000 Binary files a/content/en/docs/3.1/release-notes/v2.2.0-cloud.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/v2.2.0-percent-escape.png b/content/en/docs/3.1/release-notes/v2.2.0-percent-escape.png deleted file mode 100644 index df4d81b9..00000000 Binary files a/content/en/docs/3.1/release-notes/v2.2.0-percent-escape.png and /dev/null differ diff --git a/content/en/docs/3.1/release-notes/v2.2.0-tls-cert-validation.png b/content/en/docs/3.1/release-notes/v2.2.0-tls-cert-validation.png deleted file mode 100644 index f8635b5a..00000000 Binary files a/content/en/docs/3.1/release-notes/v2.2.0-tls-cert-validation.png and /dev/null differ diff --git a/content/en/docs/3.1/releaseNotes.yml b/content/en/docs/3.1/releaseNotes.yml deleted file mode 100644 index 58721c5a..00000000 --- a/content/en/docs/3.1/releaseNotes.yml +++ /dev/null @@ -1,1139 +0,0 @@ -# -*- fill-column: 100 -*- - -# This file should be placed in the folder for the version of the -# product that's meant to be documented. A `/release-notes` page will -# be automatically generated and populated at build time. -# -# Note that an entry needs to be added to the `doc-links.yml` file in -# order to surface the release notes in the table of contents. -# -# The YAML in this file should contain: -# -# changelog: An (optional) URL to the CHANGELOG for the product. -# items: An array of releases with the following attributes: -# - version: The (optional) version number of the release, if applicable. -# - date: The date of the release in the format YYYY-MM-DD. -# - notes: An array of noteworthy changes included in the release, each having the following attributes: -# - type: The type of change, one of `bugfix`, `feature`, `security` or `change`. -# - title: A short title of the noteworthy change. -# - body: >- -# Two or three sentences describing the change and why it -# is noteworthy. This is HTML, not plain text or -# markdown. It is handy to use YAML's ">-" feature to -# allow line-wrapping. -# - image: >- -# The URL of an image that visually represents the -# noteworthy change. This path is relative to the -# `release-notes` directory; if this file is -# `FOO/releaseNotes.yml`, then the image paths are -# relative to `FOO/release-notes/`. -# - docs: The path to the documentation page where additional information can be found. -# - href: A path from the root to a resource on the getambassador website, takes precedence over a docs link. - -changelog: https://github.com/emissary-ingress/emissary/blob/$branch$/CHANGELOG.md -items: - - 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.4.0 - date: 'TBD' - 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. - - - 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. - - - 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/content/en/docs/3.1/topics/concepts/architecture.md b/content/en/docs/3.1/topics/concepts/architecture.md deleted file mode 100644 index 1d0d4899..00000000 --- a/content/en/docs/3.1/topics/concepts/architecture.md +++ /dev/null @@ -1,27 +0,0 @@ -# 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). - -Architecture - -## 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/content/en/docs/3.1/topics/concepts/gitops-continuous-delivery.md b/content/en/docs/3.1/topics/concepts/gitops-continuous-delivery.md deleted file mode 100644 index 336a1c66..00000000 --- a/content/en/docs/3.1/topics/concepts/gitops-continuous-delivery.md +++ /dev/null @@ -1,66 +0,0 @@ -# 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/content/en/docs/3.1/topics/concepts/index.md b/content/en/docs/3.1/topics/concepts/index.md deleted file mode 100644 index 2d02a027..00000000 --- a/content/en/docs/3.1/topics/concepts/index.md +++ /dev/null @@ -1,10 +0,0 @@ -# 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/content/en/docs/3.1/topics/concepts/kubernetes-network-architecture.md b/content/en/docs/3.1/topics/concepts/kubernetes-network-architecture.md deleted file mode 100644 index 0d4ed0d4..00000000 --- a/content/en/docs/3.1/topics/concepts/kubernetes-network-architecture.md +++ /dev/null @@ -1,52 +0,0 @@ -# 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: - -
- -![Kubernetes Network Architecture](../../../../../../static/images/documentation/kubernetes-network.inline.svg) - -
- -Each of the components in this topology is discussed in further detail below. - -### Load balancer - -The load balancer is deployed outside of the Kubernetes cluster. Typically, the load balancer also has one or more static IP addresses assigned to it. A DNS entry is then created to map a domain name (e.g., example.com) to the static IP address. - -Cloud infrastructure providers such as Amazon Web Services, Azure, Digital Ocean, and Google make it easy to create these load balancers directly from Kubernetes. This is done by creating a Kubernetes service of `type: LoadBalancer`. When this service is created, the cloud provider will use the metadata contained in the Kubernetes service definition to provision a load balancer. - -If the Kubernetes cluster is deployed in a private data center, an external load balancer is still generally used. Provisioning of this load balancer usually requires the involvement of the data center operations team. - -In both the private data center and cloud infrastructure case, the external load balancer should be configured to point to the edge proxy. - -### Edge Proxy / ingress controller - -The Edge Proxy is typically a Layer 7 proxy that is deployed directly in the cluster. The core function of the edge proxy is to accept incoming traffic from the external load balancer and route the traffic to Kubernetes services. The edge proxy should be configured using Kubernetes manifests. This enables a common management workflow for both the edge proxy and Kubernetes services. - -The most popular approach to configuring edge proxies is with the Kubernetes ingress resource. When an edge proxy can process ingress resources, it is called an ingress controller. Not all edge proxies are ingress controllers (because they can't process ingress resources), but all ingress controllers are edge proxies. - -The ingress resource is a Kubernetes standard. As such, it is a lowest common denominator resource. In practice, users find that the ingress resource is insufficient in scope to address the requirements for edge routing. Semantics such as TLS termination, redirecting to TLS, timeouts, rate limiting, and authentication are all beyond the scope of the ingress resource. - -$productName$ can function as an ingress controller (i.e., it reads ingress resources), although it also includes many other capabilities that are beyond the scope of the ingress specification. Most $productName$ users find that the various additional capabilities of $productName$ are essential, and end up using $productName$'s extensions to the ingress resource, instead of using ingress resources themselves. - -### Kubernetes services and Pods - -Each instance of your application is deployed in a Kubernetes pod. As the workload on your application increases or decreases, Kubernetes can automatically add or remove pods. A Kubernetes _service_ represents a group of pods that comprise the same version of a given application. Traffic can be routed to the pods via a Kubernetes service, or it can be routed directly to the pods. - -When traffic is routed to the pods via a Kubernetes service, Kubernetes uses a built-in mechanism called `kube-proxy` to load balance traffic between the pods. Due to its implementation, `kube-proxy` is a Layer 4 proxy, i.e., it load balances at a connection level. For particular types of traffic such as HTTP/2 and gRPC, this form of load balancing is particularly problematic as it can easily result in a very uneven load balancing configuration. - -Traffic can also be routed directly to pods, bypassing the Kubernetes service. Since pods are much more ephemeral than Kubernetes services, this approach requires an edge proxy that is optimized for this use case. In particular, the edge proxy needs to support real-time discovery of pods, and be able to dynamically update pod locations without downtime. - -$productName$ supports routing both to Kubernetes services and directly to pods. - -## Further reading - -* [Kubernetes Ingress 101](https://blog.getambassador.io/kubernetes-ingress-nodeport-load-balancers-and-ingress-controllers-6e29f1c44f2d) -* [Envoy Proxy Performance on Kubernetes](/resources/envoyproxy-performance-on-k8s/) diff --git a/content/en/docs/3.1/topics/concepts/microservices-api-gateways.md b/content/en/docs/3.1/topics/concepts/microservices-api-gateways.md deleted file mode 100644 index ba95b8fc..00000000 --- a/content/en/docs/3.1/topics/concepts/microservices-api-gateways.md +++ /dev/null @@ -1,60 +0,0 @@ -# Microservices API gateways - -A microservices API gateway is an API gateway designed to accelerate the development workflow of independent services teams. A microservices API gateway provides all the functionality for a team to independently publish, monitor, and update a microservice. - -This focus on accelerating the development workflow is distinct from the purpose of traditional API gateways, which focus on the challenges of managing APIs. Over the past decade, organizations have worked to expose internal systems through well-defined APIs. The challenge of safely exposing hundreds or thousands of APIs to end-users (both internal and external) led to the emergence of API gateways. Over time, API gateways have become centralized, mission critical pieces of infrastructure that control access to these APIs. - -In this article, we'll discuss how the difference in business objective (productivity vs management) results in a very different API gateway. - -## Microservices organization - -In a microservices organization, small teams of developers work independently from each other to rapidly deliver functionality to the customer. In order for each service team to work independently, with a productive workflow, a services team needs to be able to: - -1. Publish their service, so that others can use the service -2. Monitor their service, to see how well it's working -3. Test and update their service, so they can keep on improving the service - -The team needs to do all of this *without* requiring assistance from another operations or platform team--as soon as a services team requires another team, they're no longer working independently, and this can lead to bottlenecks. - -For service publication, a microservices API gateway provides a static address for consumers, and dynamically route requests to the appropriate service address. In addition, providing authentication and TLS termination for security are typical considerations in exposing a service to other consumers. - -Understanding the end-user experience of a service is crucial to improving the service. For example, a software update could inadvertently impact the latency of certain requests. A microservices API gateway is well situated to collect key observability metrics on end-user traffic as it routes traffic to the end service. - -A microservices API gateway also supports dynamically routing user requests to different service versions for canary testing. By routing a small fraction of end-user requests to a new version of a service, service teams can safely test the impact of new updates to a small subset of users. - -## Microservices API Gateways vs. enterprise API Gateways - -At first glance, the use case described above may be fulfilled with an enterprise-focused API gateway. While this may be true, the actual emphasis of enterprise API gateways and microservices API gateways are somewhat different: - -| Use case | Traditional Enterprise API gateway | Microservices API gateway | -|---------------|-------------------|------------------------------| -| Primary Purpose | Expose, compose, and manage internal business APIs | Expose and observe internal business services | -| Publishing Functionality | API management team or service team registers / updates gateway via admin API | Service team registers / updates gateway via declarative code as part of the deployment process | -| Monitoring | Admin and operations focused e.g. meter API calls per consumer, report errors (e.g. internal 5XX). | Developer focused e.g. latency, traffic, errors, saturation | -| Handling and Debugging Issues | L7 error-handling (e.g. custom error page or payload). Run gateway/API with additional logging. Troubleshoot issue in staging environment | Configure more detailed monitoring. Enable traffic shadowing and / or canarying | -| Testing | Operate multiple environments for QA, Staging, and Production. Automated integration testing, and gated API deployment. Use client-driven API versioning for compatibility and stability (e.g. semver) | Facilitate canary routing for dynamic testing (taking care with data mutation side effects). Use developer-driven service versioning for upgrade management | -| Local Development | Deploy gateway locally (via installation script, Vagrant or Docker), and attempt to mitigate infrastructure differences with production. Use language-specific gateway mocking and stubbing frameworks | Deploy gateway locally via service orchestration platform (e.g. Kubernetes) | - -## Self-service publishing - -A team needs to be able to publish a new service to customers without requiring an operations or API management team. This ability to self-service for deployment and publication enables the team to keep the feature release velocity high. While a traditional enterprise API gateway may provide a simple mechanism (e.g., REST API) for publishing a new service, in practice, the usage is often limited to the use of a dedicated team that is responsible for the gateway. The primary reason for limiting publication to a single team is to provide an additional (human) safety mechanism: an errant API call could have potentially disastrous effects on production. - -Microservices API gateways utilize mechanisms that enable service teams to easily *and* safely publish new services, with the inherent understanding that the producing team are responsible for their service, and will fix an issue if one occurs. A microservices gateway provides configurable monitoring for issue detection, and provides hooks for debugging, such as inspecting traffic or traffic shifting/duplication. - -## Monitoring and rate limiting - -A common business model for APIs is metering, where a consumer is charged different fees depending on API usage. Traditional enterprise API gateways excel in this use case: they provide functionality for monitoring per-client usage of an API, and the ability to limit usage when the client exceeds their quota. - -A microservice gateway also requires monitoring and rate limiting, but for different reasons. Monitoring user-visible metrics such as throughput, latency, and availability, are important to ensure that new updates don't impact the end-user. Robust end-user metrics are critical to allowing rapid, incremental updates. Rate limiting is used to improve the overall resilience of a service. When a service is not responding as expected, an API gateway can throttle incoming requests to allow a service to recover and prevent a cascade failure. - -## Testing and updates - -A microservices application has multiple services, each of which is being independently updated. Automated pre-production testing of a moving target is necessary but not sufficient for microservices. Canary testing, where a small percentage of production traffic is routed to a new service version, is an important tool to help test an update. By limiting a new service version to a small percentage of users, the impact of a service failure is limited. - -In a traditional enterprise API gateway, routing is used to isolate or compose/aggregate changing API versions. Automated pre-production testing and manual post-production verification and exploration are required. - -## Summary - -Traditional enterprise API gateways are designed to solve the challenges of API management. While they may appear to solve some of the challenges of adopting microservices, the reality is that a microservices workflow creates a different set of requirements. Integrating a microservices API gateway into your development workflow empowers service teams to self-publish, monitor, and update their service, quickly and safely. This will enable your organization to ship software more rapidly, and with more reliability than ever before. - -For further reading on how an API Gateway can accelerate continuous delivery, read [this blog post](https://blog.getambassador.io/continuous-delivery-how-can-an-api-gateway-help-or-hinder-1ff15224ec4d). diff --git a/content/en/docs/3.1/topics/concepts/progressive-delivery.md b/content/en/docs/3.1/topics/concepts/progressive-delivery.md deleted file mode 100644 index b50b7c59..00000000 --- a/content/en/docs/3.1/topics/concepts/progressive-delivery.md +++ /dev/null @@ -1,47 +0,0 @@ -# Progressive delivery - -Today's cloud-native applications may consist of hundreds of services, each of which are being updated at any time. Thus, many cloud-native organizations augment regression test strategies with testing in production using progressive delivery techniques. - -Progressive Delivery is an approach for releasing software to production users. In the progressive delivery model, software is released to ever growing subsets of production users. This approach reduces the blast radius in the event of a failure. - -## Why test in production? - -Modern cloud applications are continuously deployed, as different teams rapidly update their respective services. Deploying and testing updates in a pre-production staging environment introduces a bottleneck to the speed of iteration. More importantly, staging environments are not representative of what will be running in production when the deployment actually occurs given the velocity of service updates and changes in production. Testing in production addresses both of these challenges: developers evaluate their changes in the real-world environment, enabling rapid iteration. - -## Progressive delivery strategies - -There are a number of different strategies for progressive delivery. These include: - -* Feature flags, where specific features are made available to specific user groups -* Canary releases, where a (small) percentage of traffic is routed to a new version of a service before the service is full production -* Traffic shadowing, where real user traffic is copied, or shadowed, from production to the service under test - -Observability is a critical requirement for testing in production. Regardless of progressive delivery strategy, collecting key metrics around latency, traffic, errors, and saturation (the [“Four Golden Signals of Monitoring”](https://landing.google.com/sre/sre-book/chapters/monitoring-distributed-systems/#xref_monitoring_golden-signals)) provides valuable insight into the stability and performance of a new version of the service. Moreover, application developers can compare the metrics (e.g., latency) between the production version and an updated version. If the metrics are similar, then updates can proceed with much greater confidence. - -$productName$ supports a variety of strategies for progressive delivery. These strategies are discussed in further detail below. - -### Canary releases - -Canary releases shifts a small amount of real user traffic from production to the service under test. - -The user will see the direct response from the canary version of the service from any traffic that is shifted to the canary release, and they will not trigger or see the response from the current production released version of the service. The canary results can also be verified (both the downstream response and associated upstream side effects), but it is key to understand that any side effects will be persisted. - -In addition to allowing verification that the service is not crashing or otherwise behaving badly from an operational perspective when dealing with real user traffic and behavior, canary releasing allows user validation. For example, if a business KPI performs worse for all canaried requests, then this most likely indicates that the canaried service should not be fully released in its current form. - -Canary tests can be automated, and are typically run after testing in a pre-production environment has been completed. The canary release is only visible to a fraction of actual users, and any bugs or negative changes can be reversed quickly by either routing traffic away from the canary or by rolling-back the canary deployment. - -Canary release process overview - -Canary releases are not a panacea. In particular, many services may not receive sufficient traffic in order for canary releases to provide useful information in an actionable timeframe. - -### Traffic shadowing - -This approach “shadows” or mirrors a small amount of real user traffic from production to the service under test. - -Although the shadowed results can be verified (both the downstream response and associated upstream side effects) they are not returned to the user -- the user only sees the results from the currently released service. Typically any side effects are not persisted or are executed as a no-op and verified (much like setting up a mock, and verifying that a method/function was called with the correct parameters). - -This allows verification that the service is not crashing or otherwise behaving badly from an operational perspective when dealing with real user traffic and behavior (and the larger the percentage of traffic shadowed, the higher the probability of confidence). - -## Further reading - -* [Canary release pattern](https://blog.getambassador.io/cloud-native-patterns-canary-release-1cb8f82d371a) diff --git a/content/en/docs/3.1/topics/concepts/rate-limiting-at-the-edge.md b/content/en/docs/3.1/topics/concepts/rate-limiting-at-the-edge.md deleted file mode 100644 index 1f849861..00000000 --- a/content/en/docs/3.1/topics/concepts/rate-limiting-at-the-edge.md +++ /dev/null @@ -1,33 +0,0 @@ -# Rate limiting concepts at the edge - -Rate limiting at the edge is a technique that is used to prevent a sudden or sustained increase in user traffic from breaking an API or underlying service. On the Internet, users can do whatever they want to your APIs, as you have no direct control over these end-users. Whether it’s intentional or not, these users can impact the availability, responsiveness, and scalability of your service. - -## Two approaches: Rate limiting and load shedding - -Rate limiting use cases that fall into this scenario range from implementing functional requirements related to a business scenario -- for example, where requests from paying customers is prioritized over requests from non-paying trial users -- to implementing cross-functional requirements, such as resilience from a malicious actor attempting to issue a denial-of-service (DoS) attack. - -A closely related technique to rate limiting is load shedding, and this can be used to selectively prioritize traffic (by dropping requests) based on the state of the entire system. For example, if a backend data store has become overloaded and slow to respond, it may be appropriate to drop (or “shed”) low priority requests or requests that are not time sensitive. - -## Use cases and scenarios - -The table below outlines several scenarios where rate limiting and load shedding can provide an effective solution to a range of functional and cross-functional requirements. The “Type of Rate Limiter” column provides a summary of the category of rate limiting that would be most appropriate for the scenario, and the “Specifics” column outlines what business or system properties would be involved in computing rate limiting decisions. - -| Scenario | Type of Rate Limiter |                            Specifics                        -| --- | --- | --- | -**Fairness.** One or more users are sending large volumes of requests, and thus impacting other users of the API | **User request rate limiting -** restricts each user to a predetermined number of requests per time unit.

**Concurrent user request limiting -** limits the number of concurrent user requests that can be inflight at any given point in time. |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
  • Geographic rate limiter
  • Time-based rate limiter
-**Prioritisation.** The business model depends on handling high priority requests over others | **User request rate limiting** |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device, free vs non-free user etc)
-**Resilience.** The API backend cannot scale rapidly enough to meet request demand due to a technical issue. | **Backend utilisation load shedder -** rate limit based upon utilisation of aggregate backend instances.

**Node/server utilisation load shedder -** rate limit based upon utilisation of individual or isolated groups of compute nodes/servers. |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
-**Security.** Prevent bad actors from using a DoS attack to overwhelm services, fuzzing, or brute force attacks |**User request rate limiting**

**Node/server utilisation load shedder** |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
  • Service identifier load shedder e.g. login service, audit service
-**Responsiveness.** As per the Reactive Manifesto, responsive systems focus on providing rapid and consistent response times, establishing reliable upper bounds so they deliver a consistent quality of service | **Concurrent user request limiting**

**Backend utilisation load shedder**

**Node/server utilisation load shedder** |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
  • Service identifier load shedder e.g. login service, audit service
- -## Avoiding contention with rate limiting configuration: Decoupling Dev and Ops - -One of the core features of $productName$ is the decentralization of configuration, allowing operations and development teams to independently control $productName$, as well as individual application development teams to minimize collaboration when configuring independently deployable services. This same approach applies to rate limiting configuration. - -The $productName$ rate limiting configuration allows centralized operations teams to define and implement global rate limiting and load shedding policies to protect the system, while still allowing individual application teams to define rate limiting policies that enforce business rules, for example, around paying and non-paying customers (perhaps implementing the so-called “freemium” model). See [Advanced Rate Limiting](../../../howtos/advanced-rate-limiting) documentation for examples. - -## Benefits of applying a rate limiter to the edge - -Modern applications and APIs can experience floods of traffic over a short time period (e.g. from achieving a HackerNews front page link), and increasingly bad actors and cyber criminals are targeting public-facing services. - -By implementing rate limiting and load shedding capabilities at the edge, a large amount of scenarios that are bad for business can be mitigated. These capabilities also make the life of the operations and development team that much easier, as the need to constantly firefight ingress traffic is reduced. diff --git a/content/en/docs/3.1/topics/install/ambassador-oss-community.md b/content/en/docs/3.1/topics/install/ambassador-oss-community.md deleted file mode 100644 index b53d1407..00000000 --- a/content/en/docs/3.1/topics/install/ambassador-oss-community.md +++ /dev/null @@ -1,14 +0,0 @@ -# Integration in community projects - -import Table from "../../../../../src/components/CommunityTable"; - -**$AESproductName$ is now available and includes additional functionality beyond the current $OSSproductName$.** -These features include automatic HTTPS, OAuth/OpenID Connect authentication support, integrated rate -limiting, a developer portal, and [more](/edge-stack-faq/). - -## $OSSproductName$ integrations - -If you still want to use just $OSSproductName$, don't worry! $OSSproductName$ -is currently available out-of-the-box in some Kubernetes installers and local environments. - -
\ No newline at end of file diff --git a/content/en/docs/3.1/topics/install/bare-metal.md b/content/en/docs/3.1/topics/install/bare-metal.md deleted file mode 100644 index 84ac1c8d..00000000 --- a/content/en/docs/3.1/topics/install/bare-metal.md +++ /dev/null @@ -1,93 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Install with bare metal - -In cloud environments, provisioning a readily available network load balancer with $productName$ is the best option for handling ingress into your Kubernetes cluster. When running Kubernetes on a bare metal setup, where network load balancers are not available by default, we need to consider different options for exposing $productName$. - -## Exposing $productName$ via NodePort - -The simplest way to expose an application in Kubernetes is via a `NodePort` service. In this configuration, we create the $productName$ service] and identify `type: NodePort` instead of `LoadBalancer`. Kubernetes will then create a service and assign that service a port to be exposed externally and direct traffic to $productName$ via the defined `port`. - -```yaml ---- -apiVersion: v1 -kind: Service -metadata: - name: ambassador -spec: - type: NodePort - ports: - - name: http - port: 8088 - targetPort: 8080 - nodePort: 30036 # Optional: Define the port you would like exposed - protocol: TCP - selector: - service: ambassador -``` - -Using a `NodePort` leaves $productName$ isolated from the host network, allowing the Kubernetes service to handle routing to $productName$ pods. You can drop-in this YAML to replace the `LoadBalancer` service in the [YAML installation guide](../yaml-install) and use `http://:/` as the host for requests. - -## Exposing $productName$ via host network - -When running $productName$ on a bare metal install of Kubernetes, you have the option to configure $productName$ pods to use the network of the host they are running on. This method allows you to bind $productName$ directly to port 80 or 443 so you won't need to identify the port in requests. - -i.e `http://:/` becomes `http:///` - -This can be configured by setting `hostNetwork: true` in the $productName$ deployment. `dnsPolicy: ClusterFirstWithHostNet` will also need to set to tell $productName$ to use *KubeDNS* when attempting to resolve mappings. - -```diff ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: ambassador -spec: - replicas: 1 - selector: - matchLabels: - service: ambassador - template: - metadata: - annotations: - sidecar.istio.io/inject: "false" - labels: - service: ambassador - app.kubernetes.io/managed-by: getambassador.io - spec: -+ hostNetwork: true -+ dnsPolicy: ClusterFirstWithHostNet - serviceAccountName: ambassador - containers: - - name: ambassador - image: docker.io/datawire/ambassador:$version$ - resources: - limits: - cpu: 1 - memory: 400Mi - requests: - cpu: 200m - memory: 100Mi - env: - - name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace - livenessProbe: - httpGet: - path: /ambassador/v0/check_alive - port: 8877 - initialDelaySeconds: 30 - periodSeconds: 3 - readinessProbe: - httpGet: - path: /ambassador/v0/check_ready - port: 8877 - initialDelaySeconds: 30 - periodSeconds: 3 - restartPolicy: Always -``` - -This configuration does not require a defined $productName$ service, so you can remove that service if you have defined one. - -**Note:** Before configuring $productName$ with this method, consider some of the functionality that is lost by bypassing the Kubernetes service including only having one $productName$ able to bind to port 8080 or 8443 per node and losing any load balancing that is typically performed by Kubernetes services. diff --git a/content/en/docs/3.1/topics/install/convert-to-v3alpha1.md b/content/en/docs/3.1/topics/install/convert-to-v3alpha1.md deleted file mode 100644 index bcb8002a..00000000 --- a/content/en/docs/3.1/topics/install/convert-to-v3alpha1.md +++ /dev/null @@ -1,278 +0,0 @@ ---- -title: "Convert Configuration Resources for V3" ---- -import Alert from '@material-ui/lab/Alert'; - -# Convert Configuration Resources to `getambassador.io/v3alpha1` - -Once your $productName$ $version$ installation is running, it is **strongly recommended** that -you convert your existing configuration resources from `getambassador.io/v2` to -`getambassador.io/v3alpha1`. - - - While it is not necessary to convert all your resources to getambassador.io/v3alpha1 - immediately, you should ultimately update them all for full functionality with $productName$ - - -In general, the best way to convert any resource is to start with `kubectl get`: using -`kubectl get -o yaml` on any `getambassador.io/v2` resource will cause $productName$ to -translate it to a `getambassador.io/v3alpha1` resource. You can then verify that the -`getambassador.io/v3alpha1` resource looks correct and re-apply it, which will convert the -stored copy to `getambassador.io/v3alpha1`. - -As you do the conversion, here are the things to bear in mind: - -## 1. `ambassador_id` must be an array, not a simple string. - -`getambassador.io/v2` allowed `ambassador_id` to be either an array of strings, or a simple -string. In `getambassador.io/v3alpha1`, only the array form is supported: instead of -`ambassador_id: "foo"`, use `ambassador_id: [ "foo" ]`. This applies to all $productName$ -resources, and is supported by all versions of Ambassador 1.X. - -## 2. You must have a `Listener` for each port on which $productName$ should listen. - - - Learn more about Listener - - -`Listener` is **mandatory**. Defining your own `Listener`(s) allows you to carefully -tailor the set of ports you actually need to use, and exactly which `Host` resources -are matched with them (see below). - -## 3. `Listener`, `Host`, and `Mapping` must be explicit about how they associate. - -You need to have `Listener`s, `Host`s, and `Mapping`s correctly associated with each other for $productName$ 2.X configuration. - -### 3.1. `Listener` and `Host` are associated through `Listener.hostBinding` - - - Learn more about Listener
- Learn more about Host - - -In a `Listener`, the `hostBinding` controls whether a given `Host` is associated with that `Listener`, as discussed in the [`Listener`](../../running/listener) documentation. -**The recommended setting is using `hostBinding.selector`** to choose only `Host`s that have a defined -Kubernetes label: - -```yaml -hostBinding: - selector: - matchLabels: - my-listener: listener-8080 -``` - -The above example shows a `Listener` configured to associate only with `Host`s that have a `my-listener: listener-8080` label. - -For migration purposes, it is possible to have a `Listener` associate with all of the `Host`s. This is not recommended for production environments, however, as it can resulting confusing behavior with large numbers of `Host`s, and it -can also result in larger Envoy configurations that slow reconfiguration. - -```yaml -hostBinding: - namespace: - from: ALL -``` - -but **this is not recommended in production**. Allowing every `Host` to associate -with every `Listener` can result in confusing behavior with large numbers of `Host`s, and it -can also result in larger Envoy configurations that slow reconfiguration. - -### 3.2. `Host` and `Mapping` are associated through `Host.mappingSelector` - - -In $productName$ 1.X, `Mapping`s were nearly always associated with every `Host`. Since this -tends to result in larger Envoy configurations that slow down reconfiguration, $productName$ 2.X -inverts this behavior: **`Host` and `Mapping` will not associate without explicit selection**. - -To have a `Mapping` associate with a `Host`, at least one of the following must hold: - -- Recommended: The `Host` must define a `mappingSelector` that matches a `label` on the `Mapping`. -- Alternately, the `Mapping` must define `hostname` that matches the `hostname` of the `Host`. - (Note that the `hostname` of both `Host` and `AmbasssadorMapping` is a DNS glob.) - -If the `Host` defines a `mappingSelector` and the `Mapping` also defines a `hostname`, both must match. - -As a migration aid: - -- A `Mapping` with a `hostname` of `"*"` will associate with any `Host` that -has no `mappingSelector`, and -- A `v3alpha1` `Mapping` will honor `host` if `hostname` is not present. - - - Learn more about Host
- Learn more about Mapping - - - - A Mapping that specifies host_regex: true is associated with  - all Hosts. This is generally far less desirable than using hostname - with a DNS glob. - - - - Support for host and host_regex will be removed before - v3alpha1 is promoted to v3. - - -## 4. Use `Host` to terminate TLS - - - Learn more about Host
- Learn more about TLSContext - - -In $productName$ 1.X, simply creating a `TLSContext` is sufficient to terminate TLS, but in -2.X you _must_ use a `Host`. The minimal setup to terminate TLS is now something like this: - -```yaml ---- -apiVersion: v1 -kind: Secret -metadata: - name: my-secret -type: kubernetes.io/tls -data: - tls.crt: base64-PEM - tls.key: base64-PEM ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: my-host -spec: - hostname: host.example.com - tlsSecret: my-secret -``` - -In the example above, TLS is terminated for `host.example.com`. A `TLSContext` is still right way to share data -about TLS configuration across `Host`s: set both `tlsSecret` and `tlsContext` in the `Host`. - -## 5. `Mapping` should use `hostname` if possible - - - Learn more about Mapping - - -The `getambassador.io/v3alpha1` `Mapping` introduces the new `hostname` element, which is always -a DNS glob. Using `hostname` instead of `host` is **strongly recommended** unless you absolutely -require regular expression matching: - -- if `host` is being used for an exact match, simply rename `host` to `hostname`. -- if `host` is being used for a regex that effects a prefix or suffix match, rename it - to `hostname` and rewrite the regex into a DNS glob, e.g. `host: .*\.example\.com` would become - `hostname: *.example.com`. - -Additionally, when `hostname` is used, the `Mapping` will be associated with a `Host` only -if `hostname` matches the hostname of the `Host`. If the `Host`'s `selector` is also set, -both the `selector` and the hostname must line up. - - - An 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. - - -## 6. `Mapping` added headers must not be simple strings - - - Learn more about Mapping - - -The `getambassador.io/v2` `Mapping` supported strings and dictionaries for `add_request_headers` and -`add_response_headers`, for example: - -```yaml -add_request_headers: - X-Add-String: bar - X-Add-Dict: - value: bar -``` - -In `getambassador.io/v2`, both `X-Add-String` and `X-Add-Dict` will be added with the value `bar`. - -The string form - shown with `X-Add-String` - is not supported in `getambassador.io/v3alpha1`. Use the -dictionary form instead (which works in both `getambassador.io/v2` and `getambassador.io/v3alpha1`). - -## 7. `Mapping` `headers` and `query_parameters` must not be `true` - - - Learn more about Mapping - - -`headers` and `query_parameters` in a `Mapping` control header matches and query-parameter matches. In -`getambassador.io/v2`, they support both strings and dictionaries, and each has a `_regex` variant. -For example: - - ```yaml - headers: - x-exact-match: foo - x-existence-match: true - headers_regex: - x-regex-match: "fo.*o" - ``` - -In this example, the `Mapping` requires the `x-exact-match` header to have the value `foo`, the -`x-regex-match` whose value starts with `fo` and ends with `o`. However, `x-existence-match` requires -simply that the `x-existence-match` header exists. - -In `getambassador.io/v3alpha1`, the `true` value for an existence match is not supported. Instead, -use `headers_regex` for the same header with value of `.*`. This is fully supported in 1.k) - -`query_parameters` and `query_parameters_regex` work exactly like `headers` and `headers_reex`. - -## 8. `Mapping` `labels` must be converted to new syntax - - - Learn more about Mapping - - -In `getambassador.io/v2`, the `labels` element in a `Mapping` supported several different types of -data. In `getambassador.io/v3alpha1`, all labels must have the same type, so labels must be converted -to the new syntax: - -| `getambassador.io/v2` | `getambassador.io/v3alpha1` | -| -------------------------------- | ----------------------------------------------------------- | -| `source_cluster` | `{ source_cluster: { key: source_cluster } }` | -| `destination_cluster` | `{ destination_cluster: { key: destination_cluster }` } | -| `remote_address` | `{ remote_address: { key: remote_address } }` | -| `{ my_key: { header: my_hdr } }` | `{ generic_key: { value: my_val } }` | -| `{ my_val }` | `{ generic_key: { value: my_val } }` | -| `{ my_key: { header: my_hdr } }` | `{ request_headers: { key: my_key, header_name: my_hdr } }` | - -You can check the [Rate Limiting Labels documentation](../../using/rate-limits#attaching-labels-to-requests) -for more examples. - -## 9. `tls` cannot be `true` in `AuthService`, `Mapping`, `RateLimitService`, and `TCPMapping` - - - Learn more about AuthService
- Learn more about Mapping
- Learn more about RateLimitService
- Learn more about TCPMapping - - -The `tls` element in `AuthService`, `Mapping`, `RateLimitService`, and `TCPMapping` controls TLS -origination. In `getambassador.io/v2`, it may be a string naming a `TLSContext` to use to determine -which client certificate is sent, or the boolean value `true` to request TLS origination with no -cluent certificate being sent. - -In `getambassador.io/v3alpha1`, only the string form is supported. To originate TLS with no client -certificate (the semantic of `tls: true`), omit the `tls` element and prefix the `service` with -`https://`. Note that `TCPMapping` in `getambassador.io/v2` does not support the `https://prefix`. - -## 10. Some `Module` settings have moved or changed - - - Learn more about Listener - - -A few settings have moved from the `Module` in 2.0. Make sure you review the following settings -and move them to their new locations if you are using them in a `Module`: - -- Configuration for the `PROXY` protocol is part of the `Listener` resource in $productName$ 2.0, -so the `use_proxy_protocol` element of the `ambassador` `Module` is no longer supported. - -- `xff_num_trusted_hops` has been removed from the `Module`, and its functionality has been moved -to the `l7Depth` setting in the `Listener` resource. - -- It is no longer possible to configure TLS using the `tls` element of the `Module`. Its -functionality is fully covered by the `TLSContext` resource. diff --git a/content/en/docs/3.1/topics/install/docker.md b/content/en/docs/3.1/topics/install/docker.md deleted file mode 100644 index e430a55c..00000000 --- a/content/en/docs/3.1/topics/install/docker.md +++ /dev/null @@ -1,73 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Run the demo with Docker - -In this Docker quickstart guide, we'll get $productName$ running locally -with a demo configuration. In the next section, we'll then walk through how to -deploy $productName$ in Kubernetes with a custom configuration. - -## 1. Running the demo configuration - -By default, $productName$ uses a demo configuration to show some of its basic features. Get it running with Docker, and expose $productName$ on port 8080: - -``` -docker run -it -p 8080:8080 --name=$productDeploymentName$ --rm docker.io/emissaryingress/emissary:$version$ --demo -``` - -## 2. $productName$'s diagnostics - -$productName$ provides live diagnostics viewable with a web browser. While this would normally not be exposed to the public network, the Docker demo publishes the diagnostics service at the following URL: - -`http://localhost:8080/ambassador/v0/diag/` - -You'll have to authenticate to view this page: use the username `admin`, -password `admin` (obviously this would be a poor choice in the real world!). -We'll talk more about authentication shortly. - -To access the Diagnostics page with authentication, use `curl http://localhost:8080/ambassador/v0/diag/ -u admin:admin` - -Some of the most important information - your $productName$ version, how recently $productName$'s configuration was updated, and how recently Envoy last reported status to $productName$ - is right at the top. The diagnostics overview can show you what it sees in your configuration map, and which Envoy objects were created based on your configuration. - -## 3. The Quote service - -Since $productName$ is a comprehensive, self-service edge stack, its primary purpose is to provide access and control to microservices for the teams that manage them. The demo is preconfigured with a mapping that connects the `/qotm/` resource to the "Quote" service -- a demo service that supplies quotations. You can try it out by opening - -`http://localhost:8080/qotm/` - -in your browser, or from the command line as - -``` -curl -L 'http://localhost:8080/qotm/?json=true' -``` - -This request will route to the `qotm` service at `demo.getambassador.io`, and return a random quote. - -You can see details of the mapping by clicking the blue `http://localhost:8080/qotm/` link at the very bottom of the `Ambassador Route Table` in the diagnostics overview. - -## 4. Authentication - -On the diagnostic overview, you can also see that $productName$ is configured to do authentication -- in the middle of the overview page, you'll see the `Ambassador Services In Use` section, and you can click the `tcp://127.0.0.1:5050` link for details on the `AuthService` configuration. This demo auth service is running inside the Docker container with $productName$ and the Quote service, and $productName$ uses it to mediate access to everything behind $productName$. - -You saw above that access to the diagnostic overview required you to authenticate as an administrator. Getting a random quote does not require authentication, but to get a specific quote, you'll have to authenticate as a demo user. To see this in action, open - -`http://localhost:8080/qotm/quote/5` - -in your browser. From the command line, you can see that: - -``` -curl -Lv 'http://localhost:8080/qotm/quote/5?json=true' -``` - -will return a 401, but - -``` -curl -Lv -u username:password 'http://localhost:8080/qotm/quote/5?json=true' -``` - -will succeed. (Note that that's literally "username" and "password" -- the demo auth service is deliberately not very secure!) - -Note that it's up to the auth service to decide what needs authentication -- teaming $productName$ with an authentication service can be as flexible or strict as you need it to be. - -## Next steps - -We've just walked through some of the core features of $productName$ in a local configuration. To see $productName$ in action on Kubernetes, check out the [Installation Guide](../). diff --git a/content/en/docs/3.1/topics/install/helm.md b/content/en/docs/3.1/topics/install/helm.md deleted file mode 100644 index 4c8a9836..00000000 --- a/content/en/docs/3.1/topics/install/helm.md +++ /dev/null @@ -1,102 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Install with Helm - - - - To migrate from $productName$ 1.X to $productName$ 2.X, see the - [$productName$ migration matrix](../migration-matrix/). This guide - **will not work** for that, due to changes to the configuration - resources used for $productName$ 2.X. - - - -[Helm](https://helm.sh) is a package manager for Kubernetes that automates the release and management of software on Kubernetes. $productName$ can be installed via a Helm chart with a few simple steps, depending on if you are deploying for the first time, upgrading $productName$ from an existing installation, or migrating from $productName$. - -## Before you begin - -The $productName$ Helm chart is hosted by Datawire and published at `https://app.getambassador.io`. - -Start by adding this repo to your helm client with the following command: - -``` -helm repo add datawire https://app.getambassador.io -helm repo update -``` - -## Install with Helm - -When you run the Helm chart, it installs $productName$. - -1. Install the $productName$ CRDs. - - Before installing $productName$ $version$ itself, you must configure your - Kubernetes cluster to support the `getambassador.io/v3alpha1` and `getambassador.io/v2` - configuration resources. This is required. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. Install the $productName$ Chart with the following command: - - ``` - helm install -n $productNamespace$ --create-namespace \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - -3. Next Steps - - $productName$ shold now be successfully installed and running, but in order to get started deploying Services and test routing to them you need to configure a few more resources. - - - [The `Listener` Resource](../../running/listener/) is required to configure which ports the $productName$ pods listen on so that they can begin responding to requests. - - [The `Mapping` Resouce](../../using/intro-mappings/) is used to configure routing requests to services in your cluster. - - [The `Host` Resource](../../running/host-crd/) configures TLS termination for enablin HTTPS communication. - - Explore how $productName$ [configures communication with clients](../../../howtos/configure-communications) - - - We strongly recommend following along with our Quickstart Guide to get started by creating a Listener, deploying a simple service to test with, and setting up a Mapping to route requests from $productName$ to the demo service. - - - - $productName$ $version$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - -For more advanced configuration and details about helm values, -[please see the helm chart.](https://artifacthub.io/packages/helm/datawire/emissary-ingress/) - -## Upgrading an existing installation - -See the [migration matrix](../migration-matrix) for instructions about upgrading -$productName$. diff --git a/content/en/docs/3.1/topics/install/index.less b/content/en/docs/3.1/topics/install/index.less deleted file mode 100644 index bc649e7c..00000000 --- a/content/en/docs/3.1/topics/install/index.less +++ /dev/null @@ -1,57 +0,0 @@ -@media (max-width: 769px) { - #index-installContainer { - flex-direction: column; - } - .index-dropdown { - width: auto; - } - .index-dropBtn { - width: 100%; - } -} - -.index-dropBtn { - background-color: #8e77ff; - color: white; - padding: 10px; - font-size: 16px; - border: none; - margin-top: -20px; -} - -.index-dropdown { - position: relative; - display: inline-block; -} - -.index-dropdownContent { - display: none; - position: absolute; - background-color: #f1f1f1; - width: 100%; - box-shadow: 0px 8px 16px 0px rgba(0, 0, 0, 0.2); - z-index: 1; -} - -.index-dropdownContent a { - color: black; - padding: 12px 16px; - text-decoration: none; - display: block; -} - -.index-dropdownContent a:hover { - background-color: #ddd; -} - -.index-dropdown:hover .index-dropdownContent { - display: block; -} - -.index-dropdown:hover .index-dropBtn { - background-color: #5f3eff; -} - -#index-installContainer { - display: flex; -} diff --git a/content/en/docs/3.1/topics/install/migrate-to-2-alternate.md b/content/en/docs/3.1/topics/install/migrate-to-2-alternate.md deleted file mode 100644 index d0b791a1..00000000 --- a/content/en/docs/3.1/topics/install/migrate-to-2-alternate.md +++ /dev/null @@ -1,36 +0,0 @@ -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/content/en/docs/3.1/topics/install/migrate-to-3-alternate.md b/content/en/docs/3.1/topics/install/migrate-to-3-alternate.md deleted file mode 100644 index d0b791a1..00000000 --- a/content/en/docs/3.1/topics/install/migrate-to-3-alternate.md +++ /dev/null @@ -1,36 +0,0 @@ -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/content/en/docs/3.1/topics/install/migration-matrix.md b/content/en/docs/3.1/topics/install/migration-matrix.md deleted file mode 100644 index ef20ed05..00000000 --- a/content/en/docs/3.1/topics/install/migration-matrix.md +++ /dev/null @@ -1,44 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrading $productName$ - - - Read the instructions below before making any changes to your cluster! - - -There are currently multiple paths for upgrading $productName$, depending on what version you're currently -running, what you want to be running, and whether you installed $productName$ using [Helm](../helm) or -YAML. - -(To check out if you installed $productName$ using Helm, run `helm list --all` and see if -$productName$ is listed. If so, you installed using Helm.) - - - Read the instructions below before making any changes to your cluster! - - -## If you are currently running $AESproductName$ - -See the [instructions on updating $AESproductName$](../../../../../edge-stack/$aesDocsVersion$/topics/install/migration-matrix). - -## If you installed $OSSproductName$ using Helm - -| If you're running. | You can upgrade to | -|----------------------------------|----------------------------------------------------------------------------------------------------------------------------| -| $OSSproductName$ $version$ | [$AESproductName$ $aesVersion$](/docs/edge-stack/$aesDocsVersion$/topics/install/upgrade/helm/emissary-3.1/edge-stack-3.1) | -| $OSSproductName$ $versionTwoX$ | [$OSSproductName$ $version$](../upgrade/helm/emissary-2.3/emissary-3.1) | -| $OSSproductName$ 2.2.X | [$OSSproductName$ $versionTwoX$](../upgrade/helm/emissary-2.2/emissary-2.3) | -| $OSSproductName$ 2.0.5 | [$OSSproductName$ $versionTwoX$](../upgrade/helm/emissary-2.0/emissary-2.3) | -| $OSSproductName$ $versionOneX$ | [$OSSproductName$ $versionTwoX$](../upgrade/helm/emissary-1.14/emissary-2.3) | -| $OSSproductName$ prior to $versionOneX$ | [$OSSproductName$ $versionOneX$](../../../../1.14/topics/install/upgrading) | - -## If you installed $OSSproductName$ manually by applying YAML - -| If you're running. | You can upgrade to | -|----------------------------------|----------------------------------------------------------------------------------------------------------------------------| -| $OSSproductName$ $version$ | [$AESproductName$ $aesVersion$](/docs/edge-stack/$aesDocsVersion$/topics/install/upgrade/yaml/emissary-3.1/edge-stack-3.1) | -| $OSSproductName$ $versionTwoX$ | [$OSSproductName$ $version$](../upgrade/yaml/emissary-2.3/emissary-3.1) | -| $OSSproductName$ 2.2.X | [$OSSproductName$ $versionTwoX$](../upgrade/yaml/emissary-2.2/emissary-2.3) | -| $OSSproductName$ 2.0.5 | [$OSSproductName$ $versionTwoX$](../upgrade/yaml/emissary-2.0/emissary-2.3) | -| $OSSproductName$ $versionOneX$ | [$OSSproductName$ $versionTwoX$](../upgrade/yaml/emissary-1.14/emissary-2.3) | -| $OSSproductName$ prior to $versionOneX$ | [$OSSproductName$ $versionOneX$](../../../../1.14/topics/install/upgrading) | diff --git a/content/en/docs/3.1/topics/install/upgrade/helm/emissary-1.14/emissary-2.3.md b/content/en/docs/3.1/topics/install/upgrade/helm/emissary-1.14/emissary-2.3.md deleted file mode 100644 index c5056daa..00000000 --- a/content/en/docs/3.1/topics/install/upgrade/helm/emissary-1.14/emissary-2.3.md +++ /dev/null @@ -1,315 +0,0 @@ ---- -title: Upgrade $productName$ 1.14.X to $versionTwoX$ (Helm) | Ambassador ---- -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 1.14.X to $productName$ $versionTwoX$ (Helm) - - - This guide covers migrating from $productName$ 1.14.X to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -We're pleased to introduce $productName$ $versionTwoX$! The 2.X family introduces a number of -changes to allow $productName$ to more gracefully handle larger installations (including -multitenant or multiorganizational installations), reduce memory footprint, and improve -performance. In keeping with [SemVer](https://semver.org), $productName$ 2.X introduces -some changes that aren't backward-compatible with 1.X. These changes are detailed in -[Major Changes in $productName$ 2.X](../../../../../../about/changes-2.x/). - -## Migration Overview - - - Read the migration instructions below before making any changes to your - cluster! - - -The recommended strategy for migration is to run $productName$ 1.14 and $productName$ -$versionTwoX$ side-by-side in the same cluster. This gives $productName$ $versionTwoX$ -and $productName$ 1.14 access to all the same configuration resources, with some -important caveats: - -1. **$productName$ 1.14 will not see any `getambassador.io/v3alpha1` resources.** - - This is intentional; it provides a way to apply configuration only to - $productName$ $versionTwoX$, while not interfering with the operation of your - $productName$ 1.14 installation. - -2. **If needed, you can use labels to further isolate configurations.** - - If you need to prevent your $productName$ $versionTwoX$ installation from - seeing a particular bit of $productName$ 1.14 configuration, you can apply - a Kubernetes label to the configuration resources that should be seen by - your $productName$ $versionTwoX$ installation, then set its - `AMBASSADOR_LABEL_SELECTOR` environment variable to restrict its 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$ $versionTwoX$, then set - `AMBASSADOR_LABEL_SELECTOR=version-two=true` in its Deployment. - -3. **Be careful about label selectors on Kubernetes Services!** - - If you have services in $productName$ 1.14 that use selectors that will match - Pods from $productName$ $versionTwoX$, traffic will be erroneously split between - $productName$ 1.14 and $productName$ $versionTwoX$. The labels used by $productName$ - $versionTwoX$ include: - - ```yaml - app.kubernetes.io/name: emissary-ingress - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/part-of: emissary-ingress - app.kubernetes.io/managed-by: getambassador.io - product: aes - profile: main - ``` - -4. **Be careful to only have one $productName$ Agent running at a time.** - - The $productName$ Agent is responsible for communications between - $productName$ and Ambassador Cloud. If multiple versions of the Agent are - running simultaneously, Ambassador Cloud could see conflicting information - about your cluster. - - The best way to avoid multiple agents when installing with Helm is to use - `--set agent.enabled=false` to tell Helm not to install a new Agent with - $productName$ $versionTwoX$. Once testing is done, you can switch Agents safely. - -You can also migrate by [installing $productName$ $versionTwoX$ in a separate cluster](../../../../migrate-to-2-alternate). -This permits absolute certainty that your $productName$ 1.14 configuration will not be -affected by changes meant for $productName$ $versionTwoX$, and it eliminates concerns about -ACME, but it is more effort. - -## Side-by-Side Migration Steps - -Migration is a seven-step process: - -1. **Make sure that older configuration resources are not present.** - - $productName$ 2.X does not support `getambassador.io/v0` or `getambassador.io/v1` - resources, and Kubernetes will not permit removing support for CRD versions that are - still in use for stored resources. To verify that no resources older than - `getambassador.io/v2` are active, run - - ``` - kubectl get crds -o 'go-template={{range .items}}{{.metadata.name}}={{.status.storedVersions}}{{"\n"}}{{end}}' | fgrep getambassador.io - ``` - - If `v1` is present in the output, **do not begin migration.** The old resources must be - converted to `getambassador.io/v2` and the `storedVersion` information in the cluster - must be updated. If necessary, contact Ambassador Labs on [Slack](http://a8r.io/slack) - for more information. - -2. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you must configure your - Kubernetes cluster to support its new `getambassador.io/v3alpha1` configuration - resources. Note that `getambassador.io/v2` resources are still supported, but **you - must install support for `getambassador.io/v3alpha1`** to run $productName$ $versionTwoX$, - even if you intend to continue using only `getambassador.io/v2` resources for some - time. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -3. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, you need to install $productName$ $versionTwoX$ itself - **in the same namespace as your existing $productName$ 1.14 installation**. It's important - to use the same namespace so that the two installations can see the same secrets, etc. - - Start by making sure that your `emissary` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Typically, $productName$ 1.14 was installed in the `ambassador` namespace. If you installed - $productName$ 1.14 in a different namespace, change the namespace in the commands below. - - - If you do not need to set `AMBASSADOR_LABEL_SELECTOR`: - - ```bash - helm install -n ambassador \ - --set agent.enabled=false \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - - - If you do need to set `AMBASSADOR_LABEL_SELECTOR`, use `--set`, for example: - - ```bash - helm install -n ambassador \ - --set agent.enabled=false \ - --set env.AMBASSADOR_LABEL_SELECTOR="version-two=true" \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 2.X. - Do not use the ambassador Helm chart. - - - - $productName$ $versionTwoX$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - -4. **Install `Listener`s and `Host`s as needed.** - - An important difference between $productName$ 1.14 and $productName$ $versionTwoX$ is the - new **mandatory** `Listener` CRD. Also, when running both installations side by side, - you will need to make sure that a `Host` is present for the new $productName$ $versionTwoX$ - Service. For example: - - ```bash - kubectl apply -f - < - Kubernetes will not allow you to have a 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.
-
- If you find that your $productName$ $versionTwoX$ installation and your $productName$ 1.14 - installation absolutely must have resources that are only seen by one version or the - other way, see overview section 2, "If needed, you can use labels to further isolate configurations". - - - **If you find that you need to roll back**, just reinstall your 1.14 CRDs and delete your - installation of $productName$ $versionTwoX$. - -6. **When ready, switch over to $productName$ $versionTwoX$.** - - You can run $productName$ 1.14 and $productName$ $versionTwoX$ side-by-side as long as you care - to. However, taking full advantage of $productName$ 2.X's capabilities **requires** - [updating your configuration to use `getambassador.io/v3alpha1` configuration resources](../../../../convert-to-v3alpha1), - since some useful features in $productName$ $versionTwoX$ are only available using - `getambassador.io/v3alpha1` resources. - - When you're ready to have $productName$ $versionTwoX$ handle traffic on its own, switch - your original $productName$ 1.14 Service to point to $productName$ $versionTwoX$. Use - `kubectl edit service ambassador` and change the `selectors` to: - - ``` - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/name: emissary-ingress - profile: main - ``` - - Repeat using `kubectl edit service ambassador-admin` for the `ambassador-admin` - Service. - -7. **Finally, install the $productName$ $versionTwoX$ Ambassador Agent.** - - First, scale the 1.14 agent to 0: - - ``` - kubectl scale -n ambassador deployment/ambassador-agent --replicas=0 - ``` - - Once that's done, install the new Agent. **Note that if you needed to set - `AMBASSADOR_LABEL_SELECTOR`, you must add that to this `helm upgrade` command.** - - ```bash - helm upgrade -n ambassador \ - --set agent.enabled=true \ - $productHelmName$ datawire/$productHelmName$ \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - -Congratulations! At this point, $productName$ $versionTwoX$ is fully running and it's safe to remove the `ambassador` and `ambassador-agent` Deployments: - -``` -kubectl delete deployment/ambassador deployment/ambassador-agent -``` - -Once $productName$ 1.14 is no longer running, you may [convert](../../../../convert-to-v3alpha1) -any remaining `getambassador.io/v2` resources to `getambassador.io/v3alpha1`. -You may also want to redirect DNS to the `edge-stack` Service and remove the -`ambassador` Service. diff --git a/content/en/docs/3.1/topics/install/upgrade/helm/emissary-2.0/emissary-2.3.md b/content/en/docs/3.1/topics/install/upgrade/helm/emissary-2.0/emissary-2.3.md deleted file mode 100644 index 5618ed8e..00000000 --- a/content/en/docs/3.1/topics/install/upgrade/helm/emissary-2.0/emissary-2.3.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Upgrade $productName$ 2.0.5 to $versionTwoX$ (Helm) | Ambassador ---- -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.0.5 to $productName$ $versionTwoX$ (Helm) - - - This guide covers migrating from $productName$ 2.0.5 to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster; Helm will not do this for you. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, use Helm to install $productName$ $versionTwoX$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 2.X. - Do not use the ambassador Helm chart. - diff --git a/content/en/docs/3.1/topics/install/upgrade/helm/emissary-2.2/emissary-2.3.md b/content/en/docs/3.1/topics/install/upgrade/helm/emissary-2.2/emissary-2.3.md deleted file mode 100644 index 4096f39c..00000000 --- a/content/en/docs/3.1/topics/install/upgrade/helm/emissary-2.2/emissary-2.3.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Upgrade $productName$ 2.2.X to $versionTwoX$ (Helm) | Ambassador ---- -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.2.X to $productName$ $versionTwoX$ (Helm) - - - This guide covers migrating from $productName$ 2.2.0 or 2.2.2 to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster; Helm will not do this for you. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, use Helm to install $productName$ $versionTwoX$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 2.X. - Do not use the ambassador Helm chart. - diff --git a/content/en/docs/3.1/topics/install/upgrade/helm/emissary-2.3/emissary-3.1.md b/content/en/docs/3.1/topics/install/upgrade/helm/emissary-2.3/emissary-3.1.md deleted file mode 100644 index 96fe902f..00000000 --- a/content/en/docs/3.1/topics/install/upgrade/helm/emissary-2.3/emissary-3.1.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: Upgrade $productName$ 2.3.X to $version$ (Helm) | Ambassador ---- - -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.3.Z to $productName$ $version$ (Helm) - - - This guide covers migrating from $productName$ 2.3.Z to $productName$ $version$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - - - Make sure that you have updated any 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$. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -$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. - -### Resources to check before migrating to $version$. - -$productName$ 3.X has been upgraded from Envoy 1.17.X to Envoy 1.22 which removed support for the Envoy V2 Transport Protocol. This means all `AuthService`, `RatelimitService`, and `LogServices` must be updated to use the V3 Protocol. Additionally support for some of the runtime bootstrap flags has been removed. - -You can refer to the [Major changes in $productName$ 3.x](../../../../../../about/changes-3.y/) guide for an overview of the changes. - -1. Check Transport Protocol usage on all resources before migrating. - - The `AuthService`, `RatelimitService`, and `LogServices` 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. - - `protocol_version` should be updated to `v3` for all of the above resources while still running $productName$ $versionTwoX$. As of version `2.3.z`+, support for `protocol_version` `v2` and `v3` is supported in order to allow migration from `protocol_version` `v2` to `v3` before upgrading to $productName$ $version$ where support for `v2` is removed. - - Upgrading any application code for your own implementations of these services is very straightforward. - - The following imports simply need to be updated to switch from Envoy's Transport Protocol `v2` to `v3`, and then the configuration for these resources can be updated to add the `protocl_version: "v3"` when the updated service is deployed. - - `v2` Imports: - ``` - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" - ``` - - `v3` Imports: - ``` - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" - ``` - -2. Check removed runtime changes - - ``` - # 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, - - # Developers 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, - ``` - -3. **Install new CRDs.** - - After reviewing the changes in 3.x and confirming that you are ready to upgrade, the process is the same as upgrading minor versions - in previous version of $productName$ and does not require the complex migration steps that the migration from 1.x tto 2.x required. - - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -4. **Install $productName$ $version$.** - - After installing the new CRDs, use Helm to install $productName$ $version$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 3.Y. - diff --git a/content/en/docs/3.1/topics/install/upgrade/yaml/emissary-1.14/emissary-2.3.md b/content/en/docs/3.1/topics/install/upgrade/yaml/emissary-1.14/emissary-2.3.md deleted file mode 100644 index bf29fb36..00000000 --- a/content/en/docs/3.1/topics/install/upgrade/yaml/emissary-1.14/emissary-2.3.md +++ /dev/null @@ -1,286 +0,0 @@ ---- -title: Upgrade $productName$ 1.14.X to $versionTwoX$ (YAML) | Ambassador ---- - -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 1.14.X to $productName$ $versionTwoX$ (YAML) - - - This guide covers migrating from $productName$ 1.14.X to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -We're pleased to introduce $productName$ $versionTwoX$! The 2.X family introduces a number of -changes to allow $productName$ to more gracefully handle larger installations (including -multitenant or multiorganizational installations), reduce memory footprint, and improve -performance. In keeping with [SemVer](https://semver.org), $productName$ 2.X introduces -some changes that aren't backward-compatible with 1.X. These changes are detailed in -[Major Changes in $productName$ 2.X](../../../../../../about/changes-2.x/). - -## Migration Overview - - - Read the migration instructions below before making any changes to your - cluster! - - -The recommended strategy for migration is to run $productName$ 1.14 and $productName$ -$versionTwoX$ side-by-side in the same cluster. This gives $productName$ $versionTwoX$ -and $productName$ 1.14 access to all the same configuration resources, with some -important caveats: - -1. **$productName$ 1.14 will not see any `getambassador.io/v3alpha1` resources.** - - This is intentional; it provides a way to apply configuration only to - $productName$ $versionTwoX$, while not interfering with the operation of your - $productName$ 1.14 installation. - -2. **If needed, you can use labels to further isolate configurations.** - - If you need to prevent your $productName$ $versionTwoX$ installation from - seeing a particular bit of $productName$ 1.14 configuration, you can apply - a Kubernetes label to the configuration resources that should be seen by - your $productName$ $versionTwoX$ installation, then set its - `AMBASSADOR_LABEL_SELECTOR` environment variable to restrict its 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$ $versionTwoX$, then set - `AMBASSADOR_LABEL_SELECTOR=version-two=true` in its Deployment. - -3. **Be careful about label selectors on Kubernetes Services!** - - If you have services in $productName$ 1.14 that use selectors that will match - Pods from $productName$ $versionTwoX$, traffic will be erroneously split between - $productName$ 1.14 and $productName$ $versionTwoX$. The labels used by $productName$ - $versionTwoX$ include: - - ```yaml - app.kubernetes.io/name: emissary-ingress - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/part-of: emissary-ingress - app.kubernetes.io/managed-by: getambassador.io - product: aes - profile: main - ``` - -4. **Be careful to only have one $productName$ Agent running at a time.** - - The $productName$ Agent is responsible for communications between - $productName$ and Ambassador Cloud. If multiple versions of the Agent are - running simultaneously, Ambassador Cloud could see conflicting information - about your cluster. - - The migration YAML used below to install $productName$ $versionTwoX$ will not - install a duplicate agent. If you are building your own YAML, make sure not - to include a duplicate agent. - -You can also migrate by [installing $productName$ $versionTwoX$ in a separate cluster](../../../../migrate-to-2-alternate). -This permits absolute certainty that your $productName$ 1.14 configuration will not be -affected by changes meant for $productName$ $versionTwoX$, and it eliminates concerns about -ACME, but it is more effort. - -## Side-by-Side Migration Steps - -Migration is a seven-step process: - -1. **Make sure that older configuration resources are not present.** - - $productName$ 2.X does not support `getambassador.io/v0` or `getambassador.io/v1` - resources, and Kubernetes will not permit removing support for CRD versions that are - still in use for stored resources. To verify that no resources older than - `getambassador.io/v2` are active, run - - ``` - kubectl get crds -o 'go-template={{range .items}}{{.metadata.name}}={{.status.storedVersions}}{{"\n"}}{{end}}' | fgrep getambassador.io - ``` - - If `v1` is present in the output, **do not begin migration.** The old resources must be - converted to `getambassador.io/v2` and the `storedVersion` information in the cluster - must be updated. If necessary, contact Ambassador Labs on [Slack](http://a8r.io/slack) - for more information. - -2. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you must configure your - Kubernetes cluster to support its new `getambassador.io/v3alpha1` configuration - resources. Note that `getambassador.io/v2` resources are still supported, but **you - must install support for `getambassador.io/v3alpha1`** to run $productName$ $versionTwoX$, - even if you intend to continue using only `getambassador.io/v2` resources for some - time. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -3. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, you need to install $productName$ $versionTwoX$ itself - **in the same namespace as your existing $productName$ 1.14 installation**. It's important - to use the same namespace so that the two installations can see the same secrets, etc. - - We publish two manifests for different namespaces. Use only the one that - matches the namespace into which you installed $productName$ 1.14: - - - [`emissary-emissaryns.yaml`] for the `emissary` namespace; or - - [`emissary-defaultns.yaml`] for the `default` namespace. - - If you installed $productName$ 1.14 into some other namespace, you'll need to - download one of the files and edit it to match your namespace. - - [`emissary-emissaryns.yaml`]: https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-emissaryns.yaml - [`emissary-defaultns.yaml`]: https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-defaultns.yaml - - **If you need to set `AMBASSADOR_LABEL_SELECTOR`**, you'll need to download - your chosen file and and edit it to do so. - - Assuming that you're using the `default` namespace: - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-defaultns.yaml && \ - kubectl rollout status -n default deployment/edge-stack -w - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - -4. **Install `Listener`s and `Host`s as needed.** - - An important difference between $productName$ 1.14 and $productName$ $versionTwoX$ is the - new **mandatory** `Listener` CRD. Also, when running both installations side by side, - you will need to make sure that a `Host` is present for the new $productName$ $versionTwoX$ - Service. For example: - - ```bash - kubectl apply -f - < - Kubernetes will not allow you to have a 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.
-
- If you find that your $productName$ $versionTwoX$ installation and your $productName$ 1.14 - installation absolutely must have resources that are only seen by one version or the - other way, see overview section 2, "If needed, you can use labels to further isolate configurations". - - - **If you find that you need to roll back**, just reinstall your 1.14 CRDs and delete your - installation of $productName$ $versionTwoX$. - -6. **When ready, switch over to $productName$ $versionTwoX$.** - - You can run $productName$ 1.14 and $productName$ $versionTwoX$ side-by-side as long as you care - to. However, taking full advantage of $productName$ 2.X's capabilities **requires** - [updating your configuration to use `getambassador.io/v3alpha1` configuration resources](../../../../convert-to-v3alpha1), - since some useful features in $productName$ $versionTwoX$ are only available using - `getambassador.io/v3alpha1` resources. - - When you're ready to have $productName$ $versionTwoX$ handle traffic on its own, switch - your original $productName$ 1.14 Service to point to $productName$ $versionTwoX$. Use - `kubectl edit service ambassador` and change the `selectors` to: - - ``` - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/name: emissary-ingress - profile: main - ``` - - Repeat using `kubectl edit service ambassador-admin` for the `ambassador-admin` - Service. - - -Congratulations! At this point, $productName$ $versionTwoX$ is fully running and it's safe to remove the `ambassador` and `ambassador-agent` Deployments: - -``` -kubectl delete deployment/ambassador deployment/ambassador-agent -``` - -Once $productName$ 1.14 is no longer running, you may [convert](../../../../convert-to-v3alpha1) -any remaining `getambassador.io/v2` resources to `getambassador.io/v3alpha1`. -You may also want to redirect DNS to the `edge-stack` Service and remove the -`ambassador` Service. diff --git a/content/en/docs/3.1/topics/install/upgrade/yaml/emissary-2.0/emissary-2.3.md b/content/en/docs/3.1/topics/install/upgrade/yaml/emissary-2.0/emissary-2.3.md deleted file mode 100644 index e311d6df..00000000 --- a/content/en/docs/3.1/topics/install/upgrade/yaml/emissary-2.0/emissary-2.3.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Upgrade $productName$ 2.0.5 to $versionTwoX$ (YAML) | Ambassador ---- - -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.0.5 to $productName$ $versionTwoX$ (YAML) - - - This guide covers migrating from $productName$ 2.0.5 to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, upgrade $productName$ $versionTwoX$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/3.1/topics/install/upgrade/yaml/emissary-2.2/emissary-2.3.md b/content/en/docs/3.1/topics/install/upgrade/yaml/emissary-2.2/emissary-2.3.md deleted file mode 100644 index d1d8f0fc..00000000 --- a/content/en/docs/3.1/topics/install/upgrade/yaml/emissary-2.2/emissary-2.3.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Upgrade $productName$ 2.2.X to $versionTwoX$ (YAML) | Ambassador ---- - -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.2.X to $productName$ $versionTwoX$ (YAML) - - - This guide covers migrating from $productName$ 2.2.0 or 2.2.2 to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, upgrade $productName$ $versionTwoX$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/3.1/topics/install/upgrade/yaml/emissary-2.3/emissary-3.1.md b/content/en/docs/3.1/topics/install/upgrade/yaml/emissary-2.3/emissary-3.1.md deleted file mode 100644 index 8ce8a547..00000000 --- a/content/en/docs/3.1/topics/install/upgrade/yaml/emissary-2.3/emissary-3.1.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -title: Upgrade $productName$ 2.3.Z to $version$ (YAML) | Ambassador ---- - -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.3.Z to $productName$ $version$ (YAML) - - - This guide covers migrating from $productName$ 2.3.Z to $productName$ $version$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - - - Make sure that you have updated any 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$. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading -between versions is straightforward. - -$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. - -### Resources to check before migrating to $version$. - -$productName$ 3.X has been upgraded from Envoy 1.17.X to Envoy 1.22 which removed support for the Envoy V2 Transport Protocol. This means all `AuthService`, `RatelimitService`, and `LogServices` must be updated to use the V3 Protocol. Additionally support for some of the runtime bootstrap flags has been removed. - -You can refer to the [Major changes in $productName$ 3.x](../../../../../../about/changes-3.y/) guide for an overview of the changes. - -1. Check Transport Protocol usage on all resources before migrating. - - The `AuthService`, `RatelimitService`, and `LogServices` 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. - - `protocol_version` should be updated to `v3` for all of the above resources while still running $productName$ $versionTwoX$. As of version `2.3.z`+, support for `protocol_version` `v2` and `v3` is supported in order to allow migration from `protocol_version` `v2` to `v3` before upgrading to $productName$ $version$ where support for `v2` is removed. - - Upgrading any application code for your own implementations of these services is very straightforward. - - The following imports simply need to be updated to switch from Envoy's Transport Protocol `v2` to `v3`, and then the configuration for these resources can be updated to add the `protocl_version: "v3"` when the updated service is deployed. - - `v2` Imports: - ``` - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" - ``` - - `v3` Imports: - ``` - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" - ``` - -2. Check removed runtime changes - - ``` - # 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, - - # Developers 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, - ``` - -3. **Install new CRDs.** - - After reviewing the changes in 3.x and confirming that you are ready to upgrade, the process is the same as upgrading minor versions - in previous version of $productName$ and does not require the complex migration steps that the migration from 1.x tto 2.x required. - - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -4. **Install $productName$ $version$.** - - After installing the new CRDs, upgrade $productName$ $version$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/3.1/topics/install/yaml-install.md b/content/en/docs/3.1/topics/install/yaml-install.md deleted file mode 100644 index b28e6265..00000000 --- a/content/en/docs/3.1/topics/install/yaml-install.md +++ /dev/null @@ -1,87 +0,0 @@ ---- - description: In this guide, we'll walk through the process of deploying $productName$ in Kubernetes for ingress routing. ---- - -import Alert from '@material-ui/lab/Alert'; - -# Install manually - - - - To migrate from $productName$ 1.X to $productName$ 2.X, see the - [$productName$ migration matrix](../migration-matrix/). This guide - **will not work** for that, due to changes to the configuration - resources used for $productName$ 2.X. - - - -In this guide, we'll walk you through installing $productName$ in your Kubernetes cluster. - -The manual install process does not allow for as much control over configuration -as the [Helm install method](../helm), so if you need more control over your $productName$ -installation, it is recommended that you use helm. - -## Before you begin - -$productName$ is designed to run in Kubernetes for production. The most essential requirements are: - -* Kubernetes 1.11 or later -* The `kubectl` command-line tool - -## Install with YAML - -$productName$ is typically deployed to Kubernetes from the command line. If you don't have Kubernetes, you should use our [Docker](../docker) image to deploy $productName$ locally. - -1. In your terminal, run the following command: - - ``` - kubectl create namespace $productNamespace$ || true - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml && \ - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-emissaryns.yaml && \ - kubectl -n $productNamespace$ wait --for condition=available --timeout=90s deploy $productDeploymentName$ - ``` - - - $productName$ $version$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. Determine the IP address or hostname of your cluster by running the following command: - - ``` - kubectl get -n $productNamespace$ service $productDeploymentName$ -o "go-template={{range .status.loadBalancer.ingress}}{{or .ip .hostname}}{{end}}" - ``` - - Your load balancer may take several minutes to provision your IP address. Repeat the provided command until you get an IP address. - -3. Next Steps - - $productName$ shold now be successfully installed and running, but in order to get started deploying Services and test routing to them you need to configure a few more resources. - - - [The `Listener` Resource](../../running/listener/) is required to configure which ports the $productName$ pods listen on so that they can begin responding to requests. - - [The `Mapping` Resouce](../../using/intro-mappings/) is used to configure routing requests to services in your cluster. - - [The `Host` Resource](../../running/host-crd/) configures TLS termination for enablin HTTPS communication. - - Explore how $productName$ [configures communication with clients](../../../howtos/configure-communications) - - - We strongly recommend following along with our Quickstart Guide to get started by creating a Listener, deploying a simple service to test with, and setting up a Mapping to route requests from $productName$ to the demo service. - - -## Upgrading an existing installation - -See the [migration matrix](../migration-matrix) for instructions about upgrading -$productName$. diff --git a/content/en/docs/3.1/topics/running/ambassador-deployment.md b/content/en/docs/3.1/topics/running/ambassador-deployment.md deleted file mode 100644 index fb559d69..00000000 --- a/content/en/docs/3.1/topics/running/ambassador-deployment.md +++ /dev/null @@ -1,21 +0,0 @@ -# Deployment architecture - -$productName$ can be deployed in a variety of configurations. The specific configuration depends on your data center. - -## Public cloud - -If you're using a public cloud provider such as Amazon, Azure, or Google, $productName$ can be deployed directly to a Kubernetes cluster running in the data center. Traffic is routed to $productName$ via a cloud-managed load balancer such as an Amazon Elastic Load Balancer or Google Cloud Load Balancer. Typically, this load balancer is transparently managed by Kubernetes in the form of the `LoadBalancer` service type. $productName$ then routes traffic to your services running in Kubernetes. - -## On-Premise data center - -In an on-premise data center, $productName$ is deployed on the Kubernetes cluster. Instead of exposing it via the `LoadBalancer` service type, $productName$ is exposed as a `NodePort`. Traffic is sent to a specific port on any of the nodes in the cluster, which route the traffic to $productName$, which then routes the traffic to your services running in Kubernetes. You'll also need to deploy a separate load balancer to route traffic from your core routers to $productName$. [MetalLB](https://metallb.universe.tf/) is an open-source external load balancer for Kubernetes designed for this problem. Other options are traditional TCP load balancers such as F5 or Citrix Netscaler. - -## Hybrid data center - -Many data centers include services that are running outside of Kubernetes on virtual machines. For $productName$ to route to services both inside and outside of Kubernetes, it needs the real-time network location of all services. This problem is known as "[service discovery](https://www.datawire.io/guide/traffic/service-discovery-microservices/)" and $productName$ supports using [Consul](https://www.consul.io). Services in your data center register themselves with Consul, and $productName$ uses Consul-supplied data to dynamically route requests to available services. - -## Hybrid on-premise data center - -The diagram below details a common network architecture for a hybrid on-premise data center. Traffic flows from core routers to MetalLB, which routes to $productName$ running in Kubernetes. $productName$ routes traffic to individual services running on both Kubernetes and VMs. Consul tracks the real-time network location of the services, which $productName$ uses to route to the given services. - -![Architecture](../../../images/consul-ambassador.png) diff --git a/content/en/docs/3.1/topics/running/ambassador-with-aws.md b/content/en/docs/3.1/topics/running/ambassador-with-aws.md deleted file mode 100644 index b321543a..00000000 --- a/content/en/docs/3.1/topics/running/ambassador-with-aws.md +++ /dev/null @@ -1,364 +0,0 @@ -# $productName$ with AWS - -$productName$ is a platform agnostic Kubernetes API gateway. It will run in any distribution of Kubernetes whether it is managed by a cloud provider or on homegrown bare-metal servers. - -This document serves as a reference for different configuration options available when running Kubernetes in AWS. See [Installing $productName$](../../install) for the various installation methods available. - -## Recommended configuration - -There are lot of configuration options available to you when running $productName$ in AWS. While you should read this entire document to understand what is best for you, the following is the recommended configuration when running $productName$ in AWS: - -It is recommended to terminate TLS at $productName$ so you can take advantage of all the TLS configuration options available in $productName$ including setting the allowed TLS versions, setting `alpn_protocol` options, enforcing HTTP -> HTTPS redirection, and [automatic certificate management](../host-crd) in the $productName$. - -When terminating TLS at $productName$, you should deploy a L4 [Network Load Balancer (NLB)](#network-load-balancer-nlb) with the proxy protocol enabled to get the best performance out of your load balancer while still preserving the client IP address. - -The following `Service` should be configured to deploy an NLB with cross zone load balancing enabled (see [NLB notes](#network-load-balancer-nlb) for caveat on the cross-zone-load-balancing annotation). You will need to configure the proxy protocol in the NLB manually in the AWS Console. - -```yaml -apiVersion: v1 -kind: Service -metadata: - name: ambassador - namespace: ambassador - annotations: - service.beta.kubernetes.io/aws-load-balancer-type: "nlb" - service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: "true" -spec: - type: LoadBalancer - ports: - - name: HTTP - port: 80 - targetPort: 8080 - - name: HTTPS - port: 443 - targetPort: 8443 - selector: - service: ambassador -``` - - After deploying the `Service` above and manually enabling the proxy protocol you will need to deploy the following [Ambassador `Module`](../ambassador) to tell $productName$ to use the proxy protocol and then restart $productName$ for the configuration to take effect. - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - use_proxy_proto: true - ``` - - $productName$ will now expect traffic from the load balancer to be wrapped with the proxy protocol so it can read the client IP address. - -## AWS load balancer notes - -AWS provides three types of load balancers: - -### "Classic" Elastic Load Balancer (ELB) - -The ELB is the first generation AWS Elastic Load Balancer. It is the default type of load balancer ensured by a `type: LoadBalancer` `Service` and routes directly to individual EC2 instances. It can be configured to run at layer 4 or layer 7 of the OSI model. See [What is a Classic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/introduction.html) for more details. - -* Ensured by default for a `type: LoadBalancer` `Service` -* Layer 4: TCP, TCP/SSL - * Protocol support - * HTTP(S) - * Websockets - * HTTP/2 - * Connection based load balancing - * Cannot modify the request -* Layer 7: HTTP, HTTPS - * Protocol support - * HTTP(S) - * Request based load balancing - * Can modify the request (append to `X-Forwarded-*` headers) -* Can perform TLS termination - -**Notes:** -- While it has been superseded by the `Network Load Balancer` and `Application Load Balancer` the ELB offers the simplest way of provisioning an L4 or L7 load balancer in Kubernetes. -- All of the [load balancer annotations](#load-balancer-annotations) are respected by the ELB. -- If using the ELB for TLS termination, it is recommended to run in L7 mode so it can modify `X-Forwarded-Proto` correctly. - -### Network Load Balancer (NLB) - -The NLB is a second generation AWS Elastic Load Balancer. It can be ensure by a `type: LoadBalancer` `Service` using an annotation. It can only run at layer 4 of the OSI model and load balances based on connection allowing it to handle millions of requests per second. See [What is a Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/introduction.html) for more details. - -* Can be ensured by a `type: LoadBalancer` `Service` -* Layer 4: TCP, TCP/SSL - * Protocol support - * HTTP(S) - * Websockets - * HTTP/2 - * Connection based load balacing - * Cannot modify the request -* Can perform TLS termination - -**Notes:** -- The NLB is the most efficient load balancer capable of handling millions of requests per second. It is recommended for streaming connections since it will maintain the connection stream between the client and $productName$. -- Most of the [load balancer annotations](#load-balancer-annotations) are respected by the NLB. You will need to manually configure the proxy protocol and take an extra step to enable cross zone load balancing. -- Since it operates at L4 and cannot modify the request, you will need to tell $productName$ if it is terminating TLS or not (see [TLS termination](#tls-termination) notes below). - -### Application Load Balancer (ALB) - -The ALB is a second generation AWS Elastic Load Balancer. It cannot be ensured by a `type: LoadBalancer` `Service` and must be deployed and configured manually. It can only run at layer 7 of the OSI model and load balances based on request information allowing it to perform fine-grained routing to applications. See [What is a Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/introduction.html) for more details. - -* Cannot be configured by a `type: LoadBalancer` `Service` -* Layer 7: HTTP, HTTPS - * Protocol support - * HTTP(S) - * Request based load balancing - * Can modify the request (append to `X-Forwarded-*` headers) -* Can perform TLS termination - -**Notes:** - -- The ALB can perform routing based on the path, headers, host, etc.. Since $productName$ performs this kind of routing in your cluster, unless you are using the same load balancer to route to services outside of Kubernetes, the overhead of provisioning an ALB is often not worth the benefits. -- If you would like to use an ALB, you will need to expose $productName$ with a `type: NodePort` service and manually configure the ALB to forward to the correct ports. -- None of the [load balancer annotations](#load-balancer-annotations) are respected by the ALB. You will need to manually configure all options. -- The ALB will properly set the `X-Forward-Proto` header if terminating TLS. See (see [TLS termination](#tls-termination) notes below). - -## Load balancer annotations - -Kubernetes on AWS exposes a mechanism to request certain load balancer configurations by annotating the `type: LoadBalancer` `Service`. The most complete set and explanations of these annotations can be found in this [Kubernetes document](https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer). This document will go over the subset that is most relevant when deploying $productName$. - -- `service.beta.kubernetes.io/aws-load-balancer-ssl-cert`: - - Configures the load balancer to use a valid certificate ARN to terminate TLS at the Load Balancer. - - Traffic from the client into the load balancer is encrypted but, since TLS is being terminated at the load balancer, traffic from the load balancer to $productName$ will be cleartext. You will need to configure $productName$ differently depending on whether the load balancer is running in L4 or L7 (see [TLS termination](#tls-termination) notes below). - -- `service.beta.kubernetes.io/aws-load-balancer-ssl-ports`: - - Configures which port the load balancer will be listening for SSL traffic on. Defaults to `"*"`. - - If you want to enable cleartext redirection, make sure to set this to `"443"` so traffic on port 80 will come in over cleartext. - -- `service.beta.kubernetes.io/aws-load-balancer-backend-protocol`: - - Configures the ELB to operate in L4 or L7 mode. Can be set to `"tcp"`/`"ssl"` for an L4 listener or `"http"`/`"https"` for an L7 listener. Defaults to `"tcp"` or `"ssl"` if `aws-load-balancer-ssl-cert` is set. - -- `service.beta.kubernetes.io/aws-load-balancer-type: "nlb"`: - - When this annotation is set it will launch a [Network Load Balancer (NLB)](#network-load-balancer-nlb) instead of a classic ELB. - -- `service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled`: - - Configures the load balancer to load balance across zones. For high availability, it is typical to deploy nodes across availability zones so this should be set to `"true"`. - - **Note:** You cannot configure this annotation and `service.beta.kubernetes.io/aws-load-balancer-type: "nlb"` at the same time. You must first deploy the `Service` with an NLB and then update it with the cross zone load balancing configuration. - -- `service.beta.kubernetes.io/aws-load-balancer-proxy-protocol`: - - Configures the ELB to enable the proxy protocol. `"*"`, which enables the proxy protocol on all ELB backends, is the only acceptable value. - - The proxy protocol can be used to preserve the client IP address. - - If setting this value, you need to make sure $productName$ is configured to use the proxy protocol (see [preserving the client IP address](#preserving-the-client-ip-address) below). - - **Note:** This annotation will not be recognized if `aws-load-balancer-type: "nlb"` is configured. Proxy protocol must be manually enabled for NLBs. - -## TLS termination - -TLS termination is an important part of any modern web app. $productName$ exposes a lot of TLS termination configuration options that make it a powerful tool for managing encryption between your clients and microservices. Refer to the [TLS Termination](../tls) documentation for more information on how to configure TLS termination at $productName$. - -With AWS, the AWS Certificate Manager (ACM) makes it easy to configure TLS termination at an AWS load balancer using the annotations explained above. - -This means that, when running $productName$ in AWS, you have the choice between terminating TLS at the load balancer using a certificate from the ACM or at $productName$ using a certificate stored as a `Secret` in your cluster. - -The following documentation will cover the different options available to you and how to configure $productName$ and the load balancer to get the most of each. - -### TLS termination at $productName$ - -Terminating TLS at $productName$ will guarantee you to be able to use all of the TLS termination options that $productName$ exposes including enforcing the minimum TLS version, setting the `alpn_protocols`, and redirecting cleartext to HTTPS. - -If terminating TLS at $productName$, you can provision any AWS load balancer that you want with the following (default) port assignments: - -```yaml -spec: - ports: - - name: http - port: 80 - targetPort: 8080 - - name: https - port: 443 - targetPort: 8443 -``` - -While terminating TLS at $productName$ makes it easier to expose more advanced TLS configuration options, it does have the drawback of not being able to use the ACM to manage certificates. You will have to manage your TLS certificates yourself or use the [automatic certificate management](../host-crd) available in $productName$ to have $productName$ do it for you. - -### TLS termination at the load balancer - -If you choose to terminate TLS at your Amazon load balancer you will be able to use the ACM to manage TLS certificates. This option does add some complexity to your $productName$ configuration, depending on which load balancer you are using. - -Terminating TLS at the load balancer means that $productName$ will be receiving all traffic as un-encrypted cleartext traffic. Since $productName$ expects to be serving both encrypted and cleartext traffic by default, you will need to make the following configuration changes to $productName$ to support this: - -#### L4 load balancer (default ELB or NLB) - -* **Load Balancer Service Configuration:** - The following `Service` will deploy a L4 ELB with TLS termination configured at the load balancer: - ```yaml - apiVersion: v1 - kind: Service - metadata: - name: ambassador - namespace: ambassador - annotations: - service.beta.kubernetes.io/aws-load-balancer-ssl-cert: {{ACM_CERT_ARN}} - service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "443" - spec: - type: LoadBalancer - ports: - - name: HTTP - port: 80 - targetPort: 8080 - - name: HTTPS - port: 443 - targetPort: 8080 - selector: - service: ambassador - ``` - - Note that the `spec.ports` has been changed so both the HTTP and HTTPS ports forward to the cleartext port 8080 on $productName$. - -* **`Host`:** - - The `Host` configures how $productName$ handles encrypted and cleartext traffic. The following `Host` configuration will tell $productName$ to `Route` cleartext traffic that comes in from the load balancer: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Host - metadata: - name: ambassador - spec: - hostname: "*" - selector: - matchLabels: - hostname: wildcard - acmeProvider: - authority: none - requestPolicy: - insecure: - action: Route - ``` - -**Important:** - -Because L4 load balancers do not set `X-Forwarded` headers, $productName$ will not be able to distinguish between traffic that came in to the load balancer as encrypted or cleartext. Because of this, **HTTP -> HTTPS redirection is not possible when terminating TLS at a L4 load balancer**. - -#### L7 load balancer (ELB or ALB) - -* **Load Balancer Service Configuration (L7 ELB):** - - The following `Service` will deploy a L7 ELB with TLS termination configured at the load balancer: - ```yaml - apiVersion: v1 - kind: Service - metadata: - name: ambassador - namespace: ambassador - annotations: - service.beta.kubernetes.io/aws-load-balancer-ssl-cert: {{ACM_CERT_ARN}} - service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "443" - service.beta.kubernetes.io/aws-load-balancer-backend-protocol: "http" - spec: - type: LoadBalancer - ports: - - name: HTTP - port: 80 - targetPort: 8080 - - name: HTTPS - port: 443 - targetPort: 8080 - selector: - service: ambassador - ``` - - Note that the `spec.ports` has been changed so both the HTTP and HTTPS ports forward to the cleartext port 8080 on $productName$. - -* **`Host`:** - - The `Host` configures how $productName$ handles encrypted and cleartext traffic. The following `Host` configuration will tell $productName$ to `Redirect` cleartext traffic that comes in from the load balancer: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Host - metadata: - name: ambassador - spec: - hostname: "*" - selector: - matchLabels: - hostname: wildcard - acmeProvider: - authority: none - requestPolicy: - insecure: - action: Redirect - ``` - -* **Module:** - - Since a L7 load balancer will be able to append to `X-Forwarded` headers, we need to configure $productName$ to trust the value of these headers. The following `Module` will configure $productName$ to trust a single L7 proxy in front of $productName$: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - xff_num_trusted_hops: 1 - use_remote_address: false - ``` - -**Note:** - -$productName$ uses the value of `X-Forwarded-Proto` to know if the request originated as encrypted or cleartext. Unlike L4 load balancers, L7 load balancers will set this header so HTTP -> HTTPS redirection is possible when terminating TLS at a L7 load balancer. - -## Preserving the client IP address - -Many applications will want to know the IP address of the connecting client. In Kubernetes, this IP address is often obscured by the IP address of the `Node` that is forwarding the request to $productName$ so extra configuration must be done if you need to preserve the client IP address. - -In AWS, there are two options for preserving the client IP address. - -1. Use a L7 Load Balancer that sets `X-Forwarded-For` - - A L7 load balancer will populate the `X-Forwarded-For` header with the IP address of the downstream connecting client. If your clients are connecting directly to the load balancer, this will be the IP address of your client. - - When using L7 load balancers, you must configure $productName$ to trust the value of `X-Forwarded-For` and not append its own IP address to it by setting `xff_num_trusted_hops` and `use_remote_address: false` in the [Ambassador `Module`](../ambassador): - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - xff_num_trusted_hops: 1 - use_remote_address: false - ``` - - After configuring the above `Module`, you will need to restart $productName$ for the changes to take effect. - -2. Use the proxy protocol - - The [proxy protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) is a wrapper around an HTTP request that, like `X-Forwarded-For`, lists the IP address of the downstream connecting client but is able to be set by L4 load balancers as well. - - In AWS, you can configure ELBs to use the proxy protocol by setting the `service.beta.kubernetes.io/aws-load-balancer-proxy-protocol: "*"` annotation on the service. You must manually configure this on ALBs and NLBs. - - After configuring the load balancer to use the proxy protocol, you need to tell $productName$ to expect it on the request. - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - use_proxy_proto: true - ``` - - After configuring the above `Module`, you will need to restart $productName$ for the changes to take effect. diff --git a/content/en/docs/3.1/topics/running/ambassador-with-gke.md b/content/en/docs/3.1/topics/running/ambassador-with-gke.md deleted file mode 100644 index 2b90581d..00000000 --- a/content/en/docs/3.1/topics/running/ambassador-with-gke.md +++ /dev/null @@ -1,187 +0,0 @@ -# $productName$ with GKE - -Google offers a [L7 load balancer](https://cloud.google.com/kubernetes-engine/docs/concepts/ingress) to -leverage network services such as managed SSL certificates, SSL offloading or the Google content delivery network. -A L7 load balancer in front of $productName$ can be configured by hand or by using the Ingress-GCE resource. Using the -Ingress resource also allows you to create Google-managed SSL certificates through Kubernetes. - -With this setup, HTTPS will be terminated at the Google load balancer. The load balancer will be created and configured by -the Ingress-GCE resource. The load balancer consists of a set of -[forwarding rules](https://cloud.google.com/load-balancing/docs/forwarding-rule-concepts#https_lb) and a set of -[backend services](https://cloud.google.com/load-balancing/docs/backend-service). -In this setup, the ingress resource creates two forwarding rules, one for HTTP and one for HTTPS. The HTTPS -forwarding rule has the SSL certificates attached. Also, one backend service will be created to point to -a list of instance groups at a static port. This will be the NodePort of the $productName$ service. - -With this setup, the load balancer terminates HTTPS and then directs the traffic to the $productName$ service -via the `NodePort`. $productName$ is then doing all the routing to the other internal/external services. - -# Overview of steps - -1. Install and configure the ingress with the HTTP(S) load balancer -2. Install $productName$ -3. Configure and connect $productName$ to ingress -4. Create an SSL certificate and enable HTTPS -5. Create BackendConfig for health checks -6. Configure $productName$ to do HTTP -> HTTPS redirection - -`ambassador` will be running as a `NodePort` service. Health checks will be configured to go to a BackendConfig resource. - -## 0. $productName$ - -This guide will install $OSSproductName$. You can also install $AESproductName$. Please note: -- The ingress and the `ambassador` service need to run in the same namespace -- The `ambassador` service needs to be of type `NodePort` and not `LoadBalancer`. Also remove the line with `externalTrafficPolicy: Local` -- Ambassador-Admin needs to be of type `NodePort` instead of `ClusterIP` since it needs to be available for health checks - -## 1 . Install and configure ingress with the HTTP(S) load balancer - -Create a GKE cluster through the web console. Use the release channel. When the cluster -is up and running follow [this tutorial from Google](https://cloud.google.com/kubernetes-engine/docs/tutorials/http-balancer) to configure -an ingress and a L7 load balancer. After you have completed these steps you will have a running L7 load balancer -and one service. - -## 2. Install $productName$ - -Follow the first section of the [$OSSproductName$ installation guide](../../install/) to install $OSSproductName$. -Stop before defining the `ambassador` service. - -$productName$ needs to be deployed as `NodePort` instead of `LoadBalancer` to work with the L7 load balancer and the ingress. - -Save the YAML below in ambassador.yaml and apply with `kubectl apply -f ambassador.yaml` - -```yaml -apiVersion: v1 -kind: Service -metadata: - name: ambassador -spec: - type: NodePort - ports: - - port: 8080 - targetPort: 8080 - selector: - service: ambassador -``` - -You will now have an `ambassador` service running next to your ingress. - -## 3. Configure and connect `ambassador` to the ingress - -You need to change the ingress for it to send traffic to `ambassador`. Assuming you have followed the tutorial, you should -have a file named basic-ingress.yaml. Change it to point to `ambassador` instead of web: - -```yaml -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - name: basic-ingress -spec: - backend: - serviceName: ambassador - servicePort: 8080 -``` - -Now let's connect the other service from the tutorial to `ambassador` by specifying a Mapping: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: web - namespace: default -spec: - hostname: "*" - prefix: / - service: web:8080 -``` - -All traffic will now go to `ambassador` and from `ambassador` to the `web` service. You should be able to hit your load balancer and get the output. It may take some time until the load balancer infrastructure has rolled out all changes and you might see gateway errors during that time. -As a side note: right now all traffic will go to the `web` service, including the load balancer health check. - -## 4. Create an SSL certificate and enable HTTPS - -Read up on [managed certificates on GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/managed-certs). You need -a DNS name and point it to the external IP of the load balancer. - -certificate.yaml: -```yaml -apiVersion: networking.gke.io/v1beta1 -kind: ManagedCertificate -metadata: - name: www-example-com -spec: - domains: - - www.example.com -``` - -Modify the ingress from before: -```yaml -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - name: basic-ingress - annotations: - networking.gke.io/managed-certificates: www-example-com -spec: - backend: - serviceName: ambassador - servicePort: 8080 -``` - -Please wait (5-15 minutes) until the certificate is created and all edge servers have the certificates ready. -`kubectl describe ManagedCertificate` will show you the status or go to the web console to view the load balancer. - -You should now be able to access the web service via `https://www.example.com`. - -## 5. Configure BackendConfig for health checks - -Create and apply a BackendConfig resource with a [custom health check](https://cloud.google.com/kubernetes-engine/docs/how-to/ingress-features#direct_health) specified: - -```yaml -apiVersion: cloud.google.com/v1 -kind: BackendConfig -metadata: - name: ambassador-hc-config - namespace: ambassador -spec: - # https://cloud.google.com/kubernetes-engine/docs/how-to/ingress-features - timeoutSec: 30 - connectionDraining: - drainingTimeoutSec: 30 - logging: - enable: true - sampleRate: 1.0 - healthCheck: - checkIntervalSec: 10 - timeoutSec: 10 - port: 8877 - type: HTTP - requestPath: /ambassador/v0/check_alive -``` - -Then edit your previous `ambassador.yaml` file to add an annotation referencing the BackendConfig and apply the file: - -``` -apiVersion: v1 -kind: Service -metadata: - name: ambassador - annotations: - cloud.google.com/backend-config: '{"default": "ambassador-hc-config"}' -spec: - type: NodePort - ports: - - port: 8080 - targetPort: 8080 - selector: - service: ambassador -``` - -## 6. Configure $productName$ to do HTTP -> HTTPS redirection - -Configure $productName$ to [redirect traffic from HTTP to HTTPS](../tls/cleartext-redirection/#http-https-redirection). You will need to restart $productName$ to effect the changes with `kubectl rollout restart deployment ambassador`. - -The result should be that `http://www.example.com` will redirect to `https://www.example.com`. - -You can now add more services by specifying the hostname in the Mapping. diff --git a/content/en/docs/3.1/topics/running/ambassador.md b/content/en/docs/3.1/topics/running/ambassador.md deleted file mode 100644 index 3af41d93..00000000 --- a/content/en/docs/3.1/topics/running/ambassador.md +++ /dev/null @@ -1,558 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# The `Ambassador` `Module` Resource - -
-

Contents

- -* [Envoy](#envoy) -* [General](#general) -* [gRPC](#grpc) -* [Header behavior](#header-behavior) -* [Observability](#observability) -* [Protocols](#protocols) -* [Security](#security) -* [Service health / timeouts](#service-health--timeouts) -* [Traffic management](#traffic-management) - - -
- -If present, the `ambassador` `Module` defines system-wide configuration for $productName$. You won't need it unless you need to change one of the system-wide configuration settings below. - -To use the `ambassador` `Module` to configure $productName$, it MUST be named `ambassador`, otherwise it will be ignored. To create multiple `ambassador` `Module`s in the same Kubernetes namespace, you will need to apply them as annotations with separate `ambassador_id`s: you will not be able to use multiple CRDs. - -There are many items that can be configured on the `ambassador` `Module`. They are listed below with examples and grouped by category. - -## Envoy - -##### Content-Length headers - -* `allow_chunked_length: true` tells Envoy to allow requests or responses with both `Content-Length` and `Transfer-Encoding` headers set. The default is `false`. - -By default, messages with both `Content-Length` and `Content-Transfer-Encoding` are rejected. If `allow_chunked_length` is `true`, $productName$ will remove the `Content-Length` header and process the message. See the [Envoy documentation for more details](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto.html?highlight=allow_chunked_length#config-core-v3-http1protocoloptions). - -##### Envoy access logs - -* `envoy_log_path` defines the path of Envoy's access log. By default this is standard output. -* `envoy_log_type` defines the type of access log Envoy will use. Currently, only `json` or `text` are supported. -* `envoy_log_format` defines the Envoy access log line format. - -These logs can be formatted using [Envoy operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) to display specific information about an incoming request. The example below will show only the protocol and duration of a request: - -```yaml -envoy_log_path: /dev/fd/1 -envoy_log_type: json -envoy_log_format: - { - "protocol": "%PROTOCOL%", - "duration": "%DURATION%" - } -``` - -See the Envoy documentation for the [standard log format](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#default-format-string) and a [complete list of log format operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/access_log). - -##### Envoy validation timeout - -* `envoy_validation_timeout` defines the timeout, in seconds, for validating a new Envoy configuration. The default is 10. - -A value of 0 disables Envoy configuration validation. Most installations will not need to change this setting. - -For example: - -```yaml -envoy_validation_timeout: 30 -``` - -would allow 30 seconds to validate the generated Envoy configuration. - -##### Error response overrides - -* `error_response_overrides` permits changing the status code and body text for 4XX and 5XX response codes. The default is not to override any error responses. - -By default, $productName$ will pass through error responses without modification, and errors generated locally will use Envoy's default response body, if any. - -See [using error response overrides](../custom-error-responses) for usage details. For example, this configuration: - -```yaml -error_response_overrides: - - on_status_code: 404 - body: - text_format: "File not found" -``` - -would explicitly modify the body of 404s to say "File not found". - -##### Forwarding client cert details - -Two attributes allow providing information about the client's TLS certificate to upstream certificates: - -* `forward_client_cert_details: true` will tell Envoy to add the `X-Forwarded-Client-Cert` to upstream - requests. The default is `false`. -* `set_current_client_cert_details` will tell Envoy what information to include in the - `X-Forwarded-Client-Cert` header. The default is not to include the `X-Forwarded-Client-Cert` header at all. - -$productName$ will not forward information about a certificate that it cannot validate. - -See the Envoy documentation on [X-Forwarded-Client-Cert](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers.html?highlight=xfcc#x-forwarded-client-cert) and [SetCurrentClientCertDetails](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto.html#extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-setcurrentclientcertdetails) for more information. - -```yaml -forward_client_cert_details: true -set_current_client_cert_details: SANITIZE -``` - -##### Server name - -* `server_name` allows overriding the server name that Envoy sends with responses to clients. The default is `envoy`. - -##### Suppress Envoy headers - -* `suppress_envoy_headers: true` will prevent $productName$ from emitting certain additional - headers to HTTP requests and responses. The default is `false`. - -For the exact set of headers covered by this config, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter#config-http-filters-router-headers-set) - ---- -## General - -##### Ambassador ID - -* `ambassador_id` allows using multiple instances of $productName$ in the same cluster. The default is unset. - -We recommend _not_ setting `ambassador_id` if you are running only one instance of $productName$ in your cluster. For more information, see the [Running and Deployment documentation](../running/#ambassador_id). - -If used, the `ambassador_id` value must be an array, for example: - -```yaml -ambassador_id: [ "test_environment" ] -``` - -##### Defaults - -* `defaults` provides a dictionary of default values that will be applied to various $productName$ resources. The default is to have no defaults configured. - -See [Using `ambassador` `Module` Defaults](../../using/defaults) for more information. - ---- - -## gRPC - -##### Bridges - -* `enable_grpc_http11_bridge: true` will enable the gRPC-HTTP/1.1 bridge. The default is `false`. -* `enable_grpc_web: true` will enable the gRPC-Web bridge. The default is `false`. - -gRPC is a binary HTTP/2-based protocol. While this allows high performance, it can be problematic for clients that are unable to speak HTTP/2 (such as JavaScript in many browsers, or legacy clients in difficult-to-update environments). - -The gRPC-HTTP/1.1 bridge can translate HTTP/1.1 calls with `Content-Type: application/grpc` into gRPC calls: $productName$ will perform buffering and translation as necessary. For more details on the translation process, see the [Envoy gRPC HTTP/1.1 bridge documentation](https://www.envoyproxy.io/docs/envoy/v1.11.2/configuration/http_filters/grpc_http1_bridge_filter.html). - -Likewise, gRPC-Web is a JSON and HTTP-based protocol that allows browser-based clients to take advantage of gRPC protocols. The gRPC-Web specification requires a server-side proxy to translate between gRPC-Web requests and gRPC backend services, and $productName$ can fill this role when the gRPC-Web bridge is enabled. For more details on the translation process, see the [Envoy gRPC HTTP/1.1 bridge documentation](https://www.envoyproxy.io/docs/envoy/v1.11.2/configuration/http_filters/grpc_http1_bridge_filter.html); for more details on gRPC-Web itself, see the [gRPC-Web client GitHub repo](https://github.com/grpc/grpc-web). - -##### Statistics - -* `grpc_stats` allows enabling telemetry for gRPC calls using Envoy's [gRPC Statistics Filter](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/grpc_stats_filter). The default is disabled. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - grpc_stats: - upstream_stats: true - services: - - name: . - method_names: [] -``` - -Supported parameters: -* `all_methods` -* `services` -* `upstream_stats` - -Available metrics: -* `envoy_cluster_grpc__` -* `envoy_cluster_grpc__request_message_count` -* `envoy_cluster_grpc__response_message_count` -* `envoy_cluster_grpc__success` -* `envoy_cluster_grpc__total` -* `envoy_cluster_grpc_upstream_` - **only when `upstream_stats: true`** - -Please note that `` will only be present if `all_methods` is set or the service and the method are present under `services`. If `all_methods` is false or the method is not on the list, the available metrics will be in the format `envoy_cluster_grpc_`. - -* `all_methods`: If set to true, emit stats for all service/method names. -If set to false, emit stats for all service/message types to the same stats without including the service/method in the name. -**This option is only safe if all clients are trusted. If this option is enabled with untrusted clients, the clients could cause unbounded growth in the number -of stats in Envoy, using unbounded memory and potentially slowing down stats pipelines.** - -* `services`: If set, specifies an allow list of service/methods that will have individual stats emitted for them. Any call that does not match the allow list will be counted in a stat with no method specifier (generic metric). - - - If both all_methods and services are present, all_methods will be ignored. - - -* `upstream_stats`: If true, the filter will gather a histogram for the request time of the upstream. - ---- - -## Header behavior - -##### Header case - -* `proper_case: true` forces headers to have their "proper" case as shown in RFC7230. The default is `false`. -* `header_case_overrides` allows forcing certain headers to have specific casing. The default is to override no headers. - -proper_case and header_case_overrides are mutually exclusive. - -RFC7230 specifies that HTTP header names are case-insensitive, but always shows and refers to headers as starting with a capital letter, continuing in lowercase, then repeating the single capital letter after each non-alpha character. This has become an established convention when working with HTTP: - -- `Host`, not `host` or `HOST` -- `Content-Type`, not `content-type`, `Content-type`, or `cOnTeNt-TyPe` - -Internally, Envoy typically uses [all lowercase](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/header_casing) for header names. This is fully compliant with RFC7230, but some services and clients may require headers to follow the stricter casing rules implied by RFC7230 section headers: in that situation, setting `proper_case: true` will tell Envoy to force all headers to use the casing above. - -Alternately, it is also possible - although less common - for services or clients to require some other specific casing for specific headers. `header_case_overrides` specifies an array of header names: if a case-insensitive match for a header is found in the list, the matching header will be replaced with the one in the list. For example, the following configuration will force headers that match `X-MY-Header` and `X-EXPERIMENTAL` to use that exact casing, regardless of the original case used in flight: - -```yaml -header_case_overrides: -- X-MY-Header -- X-EXPERIMENTAL -``` - -If the upstream service responds with `x-my-header: 1`, $productName$ will return `X-MY-Header: 1` to the client. Similarly, if the client includes `x-ExperiMENTAL: yes` in its request, the request to the upstream service will include `X-EXPERIMENTAL: yes`. Other headers will not be altered; $productName$ will use its default lowercase header. - -Please see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto.html#config-core-v3-http1protocoloptions-headerkeyformat) for more information. Note that in general, we recommend updating clients and services rather than relying on `header_case_overrides`. - -##### Linkerd interoperability - -* `add_linkerd_headers: true` will force $productName$ to include the `l5d-dst-override` header for Linkerd. The default is `false`. - -When using older Linkerd installations, requests going to an upstream service may need to include the `l5d-dst-override` header to ensure that Linkerd will route them correctly. Setting `add_linkerd_headers` does this automatically. See the [Mapping](../../using/mappings#linkerd-interoperability-add_linkerd_headers) documentation for more details. - -##### Max request headers size - -* `max_request_headers_kb` sets the maximum allowed request header size in kilobytes. If not set, the default is 60 KB. - -See [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto.html) for more information. - -##### Preserve external request ID - -* `preserve_external_request_id: true` will preserve any `X-Request-Id` header presented by the client. The default is `false`, in which case Envoy will always generate a new `X-Request-Id` value. - -##### Strip matching host port - -* `strip_matching_host_port: true` will tell $productName$ to strip any port number from the host/authority header before processing and routing the request if that port number matches the port number of Envoy's listener. The default is `false`, which will preserve any port number. - -In the default installation of $productName$ the public port is 443, which then maps internally to 8443, so this only works in custom installations where the public Service port and Envoy listener port match. - -A common reason to try using this property is if you are using gRPC with TLS and your client library appends the port to the Host header (i.e. `myurl.com:443`). We have an alternative solution in our [gRPC guide](../../../howtos/grpc#working-with-host-headers-that-include-the-port) that uses a [Lua script](#lua-scripts) to remove all ports from every Host header for that use case. - ---- - -## Miscellaneous - - -##### Envoy's admin port - -* `admin_port` specifies the port where $productName$'s Envoy will listen for low-level admin requests. The default is 8001; it should almost never need changing. - -##### Lua scripts - -* `lua_scripts` allows defining a custom Lua script to run on every request. The default is to run no script. - -This is useful for simple use cases that mutate requests or responses, for example to add a custom header: - -```yaml -lua_scripts: | - function envoy_on_response(response_handle) - response_handle:headers():add("Lua-Scripts-Enabled", "Processed") - end -``` - -For more details on the Lua API, see the [Envoy Lua filter documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/lua_filter.html). - -Some caveats around the embedded scripts: - -* They run in-process, so any bugs in your Lua script can break every request. -* They're run on every request/response to every URL. -* They're inlined in the $productName$ YAML; as such, we do not recommend using Lua scripts for long, complex logic. - -If you need more flexible and configurable options, $AESproductName$ supports a [pluggable Filter system](/docs/edge-stack/latest/topics/using/filters/). - -##### Merge slashes - -* `merge_slashes: true` will cause $productName$ to merge adjacent slashes in incoming paths when doing route matching and request filtering. The default is `false`. - -For example, with `merge_slashes: true`, a request for `//foo///bar` would be matched to a `Mapping` with prefix `/foo/bar`. - -##### Modify Default Buffer Size - -By default, the Envoy that ships with $productName$ uses a defailt of 1MiB soft limit for an upstream service's read and write buffer limits. This setting allows you to configure that buffer limit. See the [Envoy docs](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto.html?highlight=per_connection_buffer_limit_bytes) for more information. - -```yaml -buffer_limit_bytes: 5242880 # Sets the default buffer limit to 5 MiB -``` - -##### Use $productName$ namespace for service resolution - -* `use_ambassador_namespace_for_service_resolution: true` tells $productName$ to assume that unqualified services are in the same namespace as $productName$. The default is `false`. - -By default, when $productName$ sees a service name without a namespace, it assumes that the namespace is the same as the resource referring to the service. For example, for this `Mapping`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-1 - namespace: foo -spec: - hostname: "*" - prefix: / - service: upstream -``` - -$productName$ would look for a Service named `upstream` in namespace `foo`. - -However, if `use_ambassador_namespace_for_service_resolution` is `true`, this `Mapping` would look for a Service named `foo` in the namespace in which $productName$ is installed instead. - ---- - -## Observability - -##### Diagnostics - -* `diagnostics` controls access to the diagnostics interface. - -By default, $productName$ creates a `Mapping` that allows access to the diagnostic interface at `/ambassador/v0/diag` from anywhere in the cluster. To disable the `Mapping` entirely, set `diagnostics.enabled` to `false`: - - -```yaml -diagnostics: - enabled: false -``` - -With diagnostics disabled, `/ambassador/v0/diag` will respond with 404; however, the service itself is still running, and `/ambassador/v0/diag/` is reachable from inside the $productName$ Pod at `https://localhost:8877`. You can use Kubernetes port forwarding to set up remote access to the diagnostics page temporarily: - -``` -kubectl port-forward -n ambassador deploy/ambassador 8877 -``` - -Alternately, to leave the `Mapping` intact but restrict access to only the local Pod, set `diagnostics.allow_non_local` to `false`: - -```yaml -diagnostics: - allow_non_local: true -``` - -See [Protecting Access to the Diagnostics Interface](../../../howtos/protecting-diag-access) for more information. - ---- -## Protocols - -##### Enable IPv4 and IPv6 - -* `enable_ipv4` determines whether IPv4 DNS lookups are enabled. The default is `true`. -* `enable_ipv6` determines whether IPv6 DNS lookups are enabled. The default is `false`. - -If both IPv4 and IPv6 are enabled, $productName$ will prefer IPv6. This can have strange effects if $productName$ receives `AAAA` records from a DNS lookup, but the underlying network of the pod doesn't actually support IPv6 traffic. For this reason, the default is IPv4 only. - -An [`Mapping`](../../using/mappings) can override both `enable_ipv4` and `enable_ipv6`, but if either is not stated explicitly in a `Mapping`, the values here are used. Most $productName$ installations will probably be able to avoid overriding these settings in Mappings. - -##### HTTP/1.0 support - -* `enable_http10: true` will enable handling incoming HTTP/1.0 and HTTP/0.9 requests. The default is `false`. - ---- -## Security - -##### Cross origin resource sharing (CORS) - -* `cors` sets the default CORS configuration for all mappings in the cluster. The default is that CORS is not configured. - -For example: - -```yaml -cors: - origins: http://foo.example,http://bar.example - methods: POST, GET, OPTIONS - ... -``` - -See the [CORS syntax](../../using/cors) for more information. - -##### IP allow and deny - -* `ip_allow` and `ip_deny` define HTTP source IP address ranges to allow or deny. The default is to allow all traffic. - -Only one of ip_allow and ip_deny may be specified. - -If `ip_allow` is specified, any traffic not matching a range to allow will be denied. If `ip_deny` is specified, any traffic not matching a range to deny will be allowed. A list of ranges to allow and a separate list to deny may not both be specified. - -Both take a list of IP address ranges with a keyword specifying how to interpret the address, for example: - -```yaml -ip_allow: -- peer: 127.0.0.1 -- remote: 99.99.0.0/16 -``` - -The keyword `peer` specifies that the match should happen using the IP address of the other end of the network connection carrying the request: `X-Forwarded-For` and the `PROXY` protocol are both ignored. Here, our example specifies that connections originating from the $productName$ pod itself should always be allowed. - -The keyword `remote` specifies that the match should happen using the IP address of the HTTP client, taking into account `X-Forwarded-For` and the `PROXY` protocol if they are allowed (if they are not allowed, or not present, the peer address will be used instead). This permits matches to behave correctly when, for example, $productName$ is behind a layer 7 load balancer. Here, our example specifies that HTTP clients from the IP address range `99.99.0.0` - `99.99.255.255` will be allowed. - -You may specify as many ranges for each kind of keyword as desired. - -##### Rejecting Client Requests With Escaped Slashes - -* `reject_requests_with_escaped_slashes: true` will tell $productName$ to reject requests containing escaped slashes. The default is `false`. - -When set to `true`, $productName$ will reject any client requests that contain escaped slashes (`%2F`, `%2f`, `%5C`, or `%5c`) in their URI path by returning HTTP 400. By default, $productName$ will forward these requests unmodified. - -In general, a request with an escaped slash will _not_ match a `Mapping` prefix with an unescaped slash. However, external authentication services and other upstream services may handle escaped slashes differently, which can lead to security issues if paths with escaped slashes are allowed. By setting `reject_requests_with_escaped_slashes: true`, this class of security concern can be largely avoided. - -##### Trust downstream client IP - -* `use_remote_address: false` tells $productName$ that it cannot trust the remote address of incoming connections, and must instead rely exclusively on the `X-Forwarded-For` header. The default is `true`. - -When `true` (the default), $productName$ will append its own IP address to the `X-Forwarded-For` header so that upstream services of $productName$ can get the full set of IP addresses that have propagated a request. You may also need to set `externalTrafficPolicy: Local` on your `LoadBalancer` to propagate the original source IP address. - -See the [Envoy documentation on the `X-Forwarded-For header` ](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers) and the [Kubernetes documentation on preserving the client source IP](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/#preserving-the-client-source-ip) for more details. - -##### `X-Forwarded-For` trusted hops - -* `xff_num_trusted_hops` sets the default value for [the `l7Depth` setting of a `Listener`](../listener/#securitymodel). The default is 0. - -See the [`Listener` documentation](../listener/#securitymodel) for more details. - ---- - -## Service health / timeouts - -##### Incoming connection idle timeout - -* `listener_idle_timeout_ms` sets the idle timeout for incoming connections. The default is no timeout, meaning that incoming connections may remain idle forever. - -If set, this specifies the length of time (in milliseconds) that an incoming connection is allowed to be idle before being dropped. This can useful if you have proxies and/or firewalls in front of $productName$ and need to control how $productName$ initiates closing an idle TCP connection. - -Please see the [Envoy documentation on HTTP protocol options](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#config-core-v3-httpprotocoloptions) for more information. - -##### Keepalive - -* `keepalive` sets the global TCP keepalive settings. - -$productName$ will use these settings for all `AmbasasdorMapping`s unless overridden in a `Mapping`'s configuration. Without `keepalive`, $productName$ follows the operating system defaults. - -For example, the following configuration: - -```yaml -keepalive: - time: 2 - interval: 2 - probes: 100 -``` - -would enable keepalives every two seconds (`interval`), starting after two seconds of idleness (`time`), with the connection being dropped if 100 keepalives are sent with no response (`probes`). For more information, see the [Envoy keepalive documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/address.proto.html#config-core-v3-tcpkeepalive). - -##### Upstream idle timeout - -* `cluster_idle_timeout_ms` sets the default idle timeout for upstream connections (by default, one hour). - -If set, this specifies the timeout (in milliseconds) after which an idle connection upstream is closed. The idle timeout can be completely disabled by setting `cluster_idle_timeout_ms: 0`, which risks idle upstream connections never getting closed. - -If not set, the default idle timeout is one hour. - -You can override this setting with [`idle_timeout_ms` on a `Mapping`](../../using/timeouts/). - -##### Upstream max lifetime - -* `cluster_max_connection_lifetime_ms` sets the default maximum lifetime of an upstream connection. - -If set, this specifies the maximum amount of time (in milliseconds) after which an upstream connection is drained and closed, regardless of whether it is idle or not. Connection recreation incurs additional overhead when processing requests. The overhead tends to be nominal for plaintext (HTTP) connections within the same cluster, but may be more significant for secure HTTPS connections or upstreams with high latency. For this reason, it is generally recommended to set this value to at least 10000 ms to minimize the amortized cost of connection recreation while providing a reasonable bound for connection lifetime. - -If not set (or set to zero), then upstream connections may remain open for arbitrarily long. - -You can override this setting with [`cluster_max_connection_lifetime_ms` on a `Mapping`](../../using/timeouts/). - -##### Request timeout - -* `cluster_request_timeout_ms` sets the default end-to-end timeout for a single request. - -If set, this specifies the default end-to-end timeout for every request. - -If not set, the default is three seconds. - -You can override this setting with [`timeout_ms` on a `Mapping`](../../using/timeouts/). - -##### Readiness and liveness probes - -* `readiness_probe` sets whether `/ambassador/v0/check_ready` is automatically mapped -* `liveness_probe` sets whether `/ambassador/v0/check_alive` is automatically mapped - -By default, $productName$ creates `Mapping`s that support readiness and liveness checks at `/ambassador/v0/check_ready` and `/ambassador/v0/check_alive`. To disable the readiness `Mapping` entirely, set `readiness_probe.enabled` to `false`: - - -```yaml -readiness_probe: - enabled: false -``` - -Likewise, to disable the liveness `Mapping` entirely, set `liveness_probe.enabled` to `false`: - - -```yaml -liveness_probe: - enabled: false -``` - -A disabled probe endpoint will respond with 404; however, the service is still running, and will be accessible on localhost port 8877 from inside the $productName$ Pod. - -You can change these to route requests to some other service. For example, to have the readiness probe map to the `quote` application's health check: - -```yaml -readiness_probe: - enabled: true - service: quote - rewrite: /backend/health -``` - -The liveness and readiness probes both support `prefix` and `rewrite`, with the same meanings as for [Mappings](../../using/mappings). - -##### Retry policy - -This lets you add resilience to your services in case of request failures by performing automatic retries. - -```yaml -retry_policy: - retry_on: "5xx" -``` - ---- - -## Traffic management - -##### Circuit breaking - -* `circuit_breakers` sets the global circuit breaking configuration defaults - -You can override the circuit breaker settings for individual `Mapping`s. By default, $productName$ does not configure any circuit breakers. For more information, see the [circuit breaking reference](../../using/circuit-breakers). - -##### Default label domain and labels - -* `default_labels` sets default domains and labels to apply to every request. - -For more on how to use the default labels, , see the [Rate Limit reference](../../using/rate-limits/#attaching-labels-to-requests). - -##### Default load balancer - -* `load_balancer` sets the default load balancing type and policy - -For example, to set the default load balancer to `least_request`: - -```yaml -load_balancer: - policy: least_request -``` - -If not set, the default is to use round-robin load balancing. For more information, see the [load balancer reference](../load-balancer). diff --git a/content/en/docs/3.1/topics/running/custom-error-responses.md b/content/en/docs/3.1/topics/running/custom-error-responses.md deleted file mode 100644 index b0ad9877..00000000 --- a/content/en/docs/3.1/topics/running/custom-error-responses.md +++ /dev/null @@ -1,217 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Custom error responses - -Custom error responses set overrides for HTTP response statuses generated either -by $productName$ or upstream services. - -They can be configured either on the $productName$ -[`Module`](../ambassador) -or on an [`Mapping`](../../using/intro-mappings/), the schema is identical. See -below for more information on [rule precedence](#rule-precedence). - -- `on_status_code`: HTTP status code to match for this rewrite - rule. Only 4xx and 5xx classes are supported. -- `body`: Describes the response body contents and format. - + `content_type`: A string that sets the content type of the - response. - + `text_format`: A string whose value will be used as the new - response body. `Content-Type` will default to `text/plain` if - unspecified. - + `json_format`: A config object whose keys and values will be - serialized as JSON and used as the new response body. - + `text_format_source`: Describes a file to be used as the - response. If used, `filename` must be set and the file must exist - on the $productName$ pod. - * `filename`: A file path on the $productName$ pod that will be used - as the new response body. - -Only one of `text_format`, `json_format`, or `text_format_source` may be provided. - -Custom response bodies are subject to Envoy's AccessLog substitution syntax -and variables, see [Envoy's documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#config-access-log-format-strings) for more information. - -Note that the AccessLog substitutions use `%` as a delimiter (for example, -`%RESPONSE_CODE%`). To include a literal `%` in a custom response body, use `%%`. -For example, - -``` -%%RESPONSE_CODE%% %RESPONSE_CODE% -``` - -would render as - -``` -%RESPONSE_CODE% 401 -``` - -for a request that resulted in a response code of 401. - - - If the % 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. - - -## Simple response bodies - -Simple responses can be be added quickly for convenience. They are inserted into -the manifest as either text or JSON: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador - namespace: ambassador -spec: - config: - error_response_overrides: - - on_status_code: 404 - body: - text_format: "File not found" - - on_status_code: 500 - body: - json_format: - error: "Application error" - status: "%RESPONSE_CODE%" - cluster: "%UPSTREAM_CLUSTER%" -``` -## File response bodies - -For more complex response bodies a file can be returned as the response. -This could be used for a customer friendly HTML document for example. Use -`text_format_source` with a `filename` set as a path on the $productName$ pod. -`content_type` should be used set the specific file type, such as `text/html`. - -First configure the $productName$ module: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador - namespace: ambassador -spec: - config: - error_response_overrides: - - on_status_code: 404 - body: - content_type: "text/html" - text_format_source: - filename: '/ambassador/ambassador-errorpages/404.html' -``` - -Then create the config map containing the HTML file: - -```yaml ---- -apiVersion: v1 -kind: ConfigMap -metadata: - name: ambassador-errorpages - namespace: ambassador -data: - 404.html: | - -

File not found

-

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/content/en/docs/3.1/topics/running/debugging.md b/content/en/docs/3.1/topics/running/debugging.md deleted file mode 100644 index bd376483..00000000 --- a/content/en/docs/3.1/topics/running/debugging.md +++ /dev/null @@ -1,192 +0,0 @@ -# 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. - - - Enabling debug-level logging can produce a lot of log output — enough to - potentially impact the performance of $productName$. We don't recommend running with debug - logging enabled as a matter of course; it's usually better to enable it only when needed, - then reset logging to normal once you're finished debugging. - - -### $productName$ debug logging - -Much of $productName$'s logging is concerned with the business of noticing changes to -Kubernetes resources that specify the $productName$ configuration, and generating new -Envoy configuration in response to those changes. Enabling debug logging for this part -of the system is under the control of two environment variables: - -- Set `AES_LOG_LEVEL=debug` to debug the early boot sequence and $productName$'s interactions - with the Kubernetes cluster (finding changed resources, etc.). -- Set `AMBASSADOR_DEBUG=diagd` to debug the process of generating an Envoy configuration from - the input resources. - -### $productName$ Envoy logging - -Envoy logging is concerned with the actions Envoy is taking for incoming requests. -Typically, Envoy will only output access logs, and certain errors, but enabling Envoy -debug logging will show very verbose information about the actions Envoy is actually -taking. It can be useful for understanding why connections are being closed, or whether -an error status is coming from Envoy or from the upstream service. - -It is possible to enable Envoy logging at boot, but for the most part, it's safer to -enable it at runtime, right before sending a request that is known to have problems. -To enable Envoy debug logging, use `kubectl exec` to get a shell on the $productName$ -pod, then: - - ``` - curl -XPOST http://localhost:8001/logging?level=trace && \ - sleep 10 && \ - curl -XPOST http://localhost:8001/logging?level=warning - ``` - -This will turn on Envoy debug logging for ten seconds, then turn it off again. - -### Viewing logs - -To view the logs from $productName$: - -1. Use the following command to target an individual $productName$ Pod: `kubectl get pods -n $productNamespace$` - - The terminal will print something similar to the following: - - ``` - $ kubectl get pods -n $productNamespace$ - NAME READY STATUS RESTARTS AGE - $productDeploymentName$-85c4cf67b-4pfj2 1/1 Running 0 3m - ``` - -2. Then, run the following: `kubectl logs -n $productNamespace$ <$productDeploymentName$-pod-name>` - -The terminal will print something similar to the following: - - ``` - $ kubectl logs -n $productNamespace$ $productDeploymentName$-85c4cf67b-4pfj2 - 2018-10-10 12:26:50 kubewatch 0.40.0 INFO: generating config with gencount 1 (0 changes) - /usr/lib/python3.6/site-packages/pkg_resources/__init__.py:1235: UserWarning: /ambassador is writable by group/others and vulnerable to attack when used with get_resource_filename. Consider a more secure location (set with .set_extraction_path or the PYTHON_EGG_CACHE environment variable). - warnings.warn(msg, UserWarning) - 2018-10-10 12:26:51 kubewatch 0.40.0 INFO: Scout reports {"latest_version": "0.40.0", "application": "ambassador", "notices": [], "cached": false, "timestamp": 1539606411.061929} - - 2018-10-10 12:26:54 diagd 0.40.0 [P15TMainThread] INFO: thread count 3, listening on 0.0.0.0:8877 - [2018-10-10 12:26:54 +0000] [15] [INFO] Starting gunicorn 19.8.1 - [2018-10-10 12:26:54 +0000] [15] [INFO] Listening at: http://0.0.0.0:8877 (15) - [2018-10-10 12:26:54 +0000] [15] [INFO] Using worker: threads - [2018-10-10 12:26:54 +0000] [42] [INFO] Booting worker with pid: 42 - 2018-10-10 12:26:54 diagd 0.40.0 [P42TMainThread] INFO: Starting periodic updates - [2018-10-10 12:27:01.977][21][info][main] source/server/drain_manager_impl.cc:63] shutting down parent after drain - ``` - -Note that many deployments will have multiple logs, and the logs are independent for each Pod. - -## Examine Pod and container contents - -You can examine the contents of the $productName$ Pod for issues, such as if volume mounts are correct and TLS certificates are present in the required directory, to determine if the Pod has the latest $productName$ configuration, or if the generated Envoy configuration is correct or as expected. In these instructions, we will look for problems related to the Envoy configuration. - -1. To look into an $productName$ Pod, get a shell on the Pod using `kubectl exec`. For example, - - ``` - kubectl exec -it -n $productNamespace$ <$productDeploymentName$-pod-name> -- bash - ``` - -2. Determine the latest configuration. If you haven't overridden the configuration directory, the latest configuration will be in `/ambassador/snapshots`. If you have overridden it, $productName$ saves configurations in `$AMBASSADOR_CONFIG_BASE_DIR/snapshots`. - - In the snapshots directory: - - * `snapshot.yaml` contains the full input configuration that $productName$ has found; - * `aconf.json` contains the $productName$ configuration extracted from the snapshot; - * `ir.json` contains the IR constructed from the $productName$ configuration; and - * `econf.json` contains the Envoy configuration generated from the IR. - - In the snapshots directory, the current configuration will be stored in files with no digit suffix, and older configurations have increasing numbers. For example, `ir.json` is current, `ir-1.json` is the next oldest, then `ir-2.json`, etc. - -3. If something is wrong with `snapshot` or `aconf`, there is an issue with your configuration. If something is wrong with `ir` or `econf`, you should [open an issue on Github](https://github.com/emissary-ingress/emissary/issues/new/choose). - -4. The actual input provided to Envoy is split into `$AMBASSADOR_CONFIG_BASE_DIR/bootstrap-ads.json` and `$AMBASSADOR_CONFIG_BASE_DIR/envoy/envoy.json`. - - - The `bootstrap-ads.json` file contains details about Envoy statistics, logging, authentication, etc. - - The `envoy.json` file contains information about request routing. - - You may generally find it simplest to just look at the `econf.json` files in the `snapshot` - directory, which includes both kinds of configuration. diff --git a/content/en/docs/3.1/topics/running/diagnostics.md b/content/en/docs/3.1/topics/running/diagnostics.md deleted file mode 100644 index 61e57ed2..00000000 --- a/content/en/docs/3.1/topics/running/diagnostics.md +++ /dev/null @@ -1,41 +0,0 @@ -# Diagnostics - -If you're experiencing issues with $productName$, log in to your Edge Policy Console and choose from the left menu whether you want to: - -* Debug issues from the Debugging tab -* Check the health status of your services from the Mappings tab - -## Debugging - -If $productName$ is not routing your services as you'd expect, your first step should be $productName$ Diagnostics in the Edge Policy Console. Login to your Edge Policy Console and select the "Debugging" tab from the left menu. - -Some of the most important information (your $productName$ version, how recently $productName$'s configuration was updated, and how recently Envoy last reported status to $productName$) is right at the top. See [Debugging](../debugging) for more information. - -## Health status - -$productName$ displays the health of your services on the Dashboard of your Edge Policy Console. Health is computed as successful requests / total requests and expressed as a percentage. The "total requests" comes from Envoy `upstream_rq_pending_total` stat. "Successful requests" is calculated by substracting `upstream_rq_4xx` and `upstream_rq_5xx` from the total. - -* Red is used when the success rate ranges from 0% - 70%. -* Yellow is used when the success rate ranges from 70% - 90%. -* Green is used when the success rate is > 90%. -* Grey is used when a service is "waiting". This means the success rate cannot be determined because the service has not recieved any requests yet. - -Health status - -The LEFT image shows what a list of services under the `Debugging tab` in the Edge Policy Consul will look like for each level of health. - -The RIGHT image shows the dial on the hompage of the Edge Policy Console, this will display the ratio of services that are healthy according to these measurements. - - -## Troubleshooting - -If the diagnostics service does not provide sufficient information, Kubernetes and Envoy provide additional debugging information. - -If $productName$ isn't working at all, start by looking at the data from the following: - -* `kubectl describe pod ` will give you a list of all events on the $productName$ pod -* `kubectl logs ambassador` will give you a log from $productName$ itself - -If you need additional help, feel free to join our [Slack channel](http://a8r.io/slack) with the above information (along with your Kubernetes manifest). - -You can also increase the debug of Envoy through the button in the diagnostics panel. Turn on debug logging, issue a request, and capture the log output from the $productName$ pod using `kubectl logs` as described above. diff --git a/content/en/docs/3.1/topics/running/environment.md b/content/en/docs/3.1/topics/running/environment.md deleted file mode 100644 index 879c0425..00000000 --- a/content/en/docs/3.1/topics/running/environment.md +++ /dev/null @@ -1,63 +0,0 @@ -# The $productName$ container - -To give you flexibility and independence from a hosting platform's uptime, you can pull the `ambassador` and `aes` images from any of the following registries: -- `docker.io/datawire/` - * **Note**: In rare occasions, you may experience rate limits when using Docker Hub. See [this page](https://www.docker.com/increase-rate-limits) to learn how to deal with them. -- `quay.io/datawire/` -- `gcr.io/datawire/` - -For an even more robust installation, consider using a [local registry as a pull through cache](https://docs.docker.com/registry/recipes/mirror/) or configure a [publicly accessible mirror](https://cloud.google.com/container-registry/docs/using-dockerhub-mirroring). - -## Environment variables - -Use the following variables for the environment of your $productName$ container: - -| Purpose | Variable | Default value | Value type | -|-----------------------------------|----------------------------------------------------------------------------------------- |-----------------------------------------------------|-------------------------------------------------------------------------------| -| Core | `AMBASSADOR_ID` | `[ "default" ]` | List of strings | -| Core | `AMBASSADOR_NAMESPACE` | `default` ([^1]) | Kubernetes namespace | -| Core | `AMBASSADOR_SINGLE_NAMESPACE` | Empty | Boolean; non-empty=true, empty=false | -| Core | `AMBASSADOR_ENVOY_BASE_ID` | `0` | Integer | -| Core | `AMBASSADOR_LEGACY_MODE` | `false` | Boolean; [Go `strconv.ParseBool`][] | -| Core | `AMBASSADOR_FAST_RECONFIGURE` | `false` | EXPERIMENTAL -- Boolean; `true`=true, any other value=false | -| Core | `AMBASSADOR_UPDATE_MAPPING_STATUS` | `false` | Boolean; `true`=true, any other value=false | -| Core | `AMBASSADOR_DISABLE_SNAPSHOT_SERVER` | `false` | Boolean; non-empty=true, empty=false | -| Core | `AMBASSADOR_JSON_LOGGING` | `false` | Boolean; non-empty=true, empty=false | -| Core | `AMBASSADOR_FORCE_SECRET_VALIDATION` | `false` | Boolean: `true`=true, any other value=false | -| $AESproductName$ | `AES_LOG_LEVEL` | `warn` | Log level | -| Developer Portal | `DEVPORTAL_CONTENT_URL` | `https://github.com/datawire/devportal-content` | git-remote URL | -| Developer Portal | `DEVPORTAL_CONTENT_DIR` | `/` | Rooted Git directory | -| Developer Portal | `DEVPORTAL_CONTENT_BRANCH` | `master` | Git branch name | -| Developer Portal | `POLL_EVERY_SECS` | `60` | Integer | -| Envoy | `STATSD_ENABLED` | `false` | Boolean; Python `value.lower() == "true"` | -| Envoy | `DOGSTATSD` | `false` | Boolean; Python `value.lower() == "true"` | -| Envoy | `DD_ENTITY_ID` | Empty | String | -| Envoy | `ENVOY_CONCURRENCY` | Empty | Integer - -Log level names are case-insensitive. From least verbose to most -verbose, valid log levels are `error`, `warn`/`warning`, `info`, -`debug`, and `trace`. - -## 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 when `AMBASSADOR_FAST_RECONFIGURE` is set; 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` when `AMBASSADOR_FAST_RECONFIGURE` is set | - -[^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/content/en/docs/3.1/topics/running/gzip.md b/content/en/docs/3.1/topics/running/gzip.md deleted file mode 100644 index e3005c83..00000000 --- a/content/en/docs/3.1/topics/running/gzip.md +++ /dev/null @@ -1,55 +0,0 @@ -# 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/content/en/docs/3.1/topics/running/host-crd.md b/content/en/docs/3.1/topics/running/host-crd.md deleted file mode 100644 index db561ee1..00000000 --- a/content/en/docs/3.1/topics/running/host-crd.md +++ /dev/null @@ -1,262 +0,0 @@ -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` - - - Remember that Listener resources are required for a functioning - $productName$ installation!
- Learn more about Listener. - - - - Remember than $productName$ does not make sure that a wildcard Host exists! If the - wildcard behavior is needed, a Host with a hostname of "*" - must be defined by the user. - - -A minimal `Host` resource, assuming no TLS configuration, would be: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: minimal-host -spec: - hostname: host.example.com -``` - -This `Host` tells $productName$ to expect to be reached at `host.example.com`, -with no TLS termination, and only associating with `Mapping`s that also set a -`hostname` that matches `host.example.com`. - -Remember that a 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. - -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 `selector` is a Kubernetes [label selector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#labelselector-v1-meta), but **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. - -## 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/content/en/docs/3.1/topics/running/http3.md b/content/en/docs/3.1/topics/running/http3.md deleted file mode 100644 index 9aeb6cac..00000000 --- a/content/en/docs/3.1/topics/running/http3.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -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`. - - -The protocolStack elements need to be entered in the specific order of TLS, HTTP, UDP. - - -The `Listener` configured for HTTP/3 can be bound to the same address and port (`0.0.0.0:8443`) as the `Listener` that supports HTTP/2 and HTTP/1.1. This is not required, but it allows $productName$ to inject the default `alt-svc: h3=":443"; ma=86400, h3-29=":443"; ma=86400` header into the responses returned over the TCP connection with no additional configuration needed. **Most clients such as browsers require the `alt-svc` header to upgrade to HTTP/3**. - - -The current default of 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. - - -```yaml -# This is a standard Listener that leverages TCP to serve HTTP/2 and HTTP/1.1 traffic. -# It is bound to the same address and port (0.0.0.0:8443) as the UDP listener. -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: $productDeploymentName$-https-listener - namespace: $productNamespace$ -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: - namespace: - from: ALL ---- -# This is a Listener that leverages UDP and HTTP to serve HTTP/3 traffic. -# NOTE: Raw UDP traffic is not supported. UDP and HTTP must be used together. -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: $productDeploymentName$-https-listener-udp - namespace: $productNamespace$ -spec: - port: 8443 - # Order is important here. HTTP is required. - protocolStack: - - TLS - - HTTP - - UDP - securityModel: XFP - hostBinding: - namespace: - from: ALL -``` - -### Configuring the Host resource - -Because the QUIC network requires TLS, the certificate needs to be valid so the client can upgrade a connection to HTTP/3. See the [Host documentation](./host-crd.md) for more information on how to configure TLS for a `Host`. - -### Certificate verification - -Clients can only upgrade to an HTTP/3 connection with a valid certificate. If the client won’t upgrade to HTTP/3, verify that you have a valid TLS certificate and that your client can speak **TLS v1.3**. Your `Host` resource should be configured similar to the following: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: my-domain-host -spec: - hostname: your-hostname - # acme isn't required but just shown as an example of how to manage a valid TLS cert - acmeProvider: - email: your-email@example.com - authority: https://acme-v02.api.letsencrypt.org/directory - tls: - # QUIC requires TLS v1.3 version. Verify your client supports it. - min_tls_version: v1.3 - # Either protocol can be upgraded, but http/2 is recommended. - alpn_protocols: h2,http/1.1 -``` - -### External load balancers - -The two most common service types to expose traffic outside of a Kubernetes cluster are: - -- `LoadBalancer`: A load balancer controller generates and manages the cloud provider-specific external load balancer. -- `NodePort`: The platform administrator has to manually set up things like the external load balancer, firewall rules, and health checks. - -#### LoadBalancer setup - -The ideal setup would be to configure a single service of type `LoadBalancer`, but this comes with some current restrictions: -- You need version 1.24 or later of Kubernetes with the [`MixedProtocolLBService` feature enabled](https://kubernetes.io/docs/concepts/services-networking/service/#load-balancers-with-mixed-protocol-types). -- Your cloud service provider needs to support the creation of an external load balancer with mixed protocol types (TCP/UDP), port reuse, and port forwarding. Support for Kubernetes feature flags may vary between cloud service providers. Refer to your provider’s documentation to see if they support this scenario. - -An example `LoadBalancer` configuration that fits the criteria listed above: - -```yaml - -# note: extra fields such as labels and selectors removed for clarity -apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$ - namespace: $productNamespace$ -spec: - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - - name: http3 - port: 443 - targetPort: 8443 - protocol: UDP - type: LoadBalancer -``` - -## Cloud service provider setup - -Once you've completed the steps above, you need to configure HTTP/3 support through your cloud service provider. The configuration processes for each provider can be found here: - -- HTTP/3 setup for [Amazon Elastic Kubernetes Service (EKS)](../../../howtos/http3-eks) -- HTTP/3 setup for [Azure Kubernetes Service (AKS)](../../../howtos/http3-aks) -- HTTP/3 setup for [Google Kubernetes Engine (GKE)](../../../howtos/http3-gke) diff --git a/content/en/docs/3.1/topics/running/index.md b/content/en/docs/3.1/topics/running/index.md deleted file mode 100644 index c196e969..00000000 --- a/content/en/docs/3.1/topics/running/index.md +++ /dev/null @@ -1,16 +0,0 @@ -# Running $productName$ in production - -This section of the documentation is designed for operators and site reliability engineers who are managing the deployment of $productName$. Learn more below: - -* *Global Configuration:* The [Ambassador module](ambassador) is used to set system-wide configuration. -* *Exposing $productName$ to the Internet:* The [`Listener` CRD](listener) defines which ports are exposed, including their protocols and security models. The [`Host` CRD](host-crd) defines how $productName$ manages TLS, domains, and such. -* *Load Balancing:* $productName$ supports a number of different [load balancing strategies](load-balancer) as well as different ways to configure [service discovery](resolvers) -* [Gzip Compression](gzip) -* *Deploying $productName$:* On [Amazon Web Services](ambassador-with-aws) | [Google Cloud](ambassador-with-gke) | [general security and operational notes](running), including running multiple $productNamePlural$ on a cluster -* *TLS/SSL:* [Simultaneously Routing HTTP and HTTPS](tls/cleartext-redirection#cleartext-routing) | [HTTP -> HTTPS Redirection](tls/cleartext-redirection#http-https-redirection) | [Mutual TLS](tls/mtls) | [TLS origination](tls/origination) -* *Statistics and Monitoring:* [Integrating with Prometheus, DataDog, and other monitoring systems](statistics) -* *Extending $productName$* $productName$ can be extended with custom plug-ins that connect via HTTP/gRPC interfaces. [Custom Authentication](services/auth-service) | [The External Auth protocol](services/ext_authz) | [Custom Logging](services/log-service) | [Rate Limiting](services/rate-limit-service) | [Distributed Tracing](services/tracing-service) -* *Troubleshooting:* [Diagnostics](diagnostics) | [Debugging](debugging) -* *Scaling $productName$:* [Scaling $productName$](scaling) -* *Ingress:* $productName$ can function as an [Ingress Controller](ingress-controller) -* *Error Response Overrides:* $productName$ can override 4xx and 5xx responses with [custom response bodies](custom-error-responses) diff --git a/content/en/docs/3.1/topics/running/ingress-controller.md b/content/en/docs/3.1/topics/running/ingress-controller.md deleted file mode 100644 index 9b7afb82..00000000 --- a/content/en/docs/3.1/topics/running/ingress-controller.md +++ /dev/null @@ -1,325 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Ingress controller - -
-

Contents

- -- [When and how to use the Ingress resource](#when-and-how-to-use-the-ingress-resource) -- [What is required to use the Ingress resource?](#what-is-required-to-use-the-ingress-resource) -- [When to use an Ingress instead of annotations or CRDs](#when-to-use-an-ingress-instead-of-annotations-or-crds) -- [Ingress support](#ingress-support) -- [Examples of Ingress configs vs Mapping configs](#examples-of-ingress-configs-vs-mapping-configs) -- [Ingress routes and mappings](#ingress-routes-and-mappings) -- [The Minimal Ingress](#the-minimal-ingress) -- [Name based virtual hosting with an Ambassador ID](#name-based-virtual-hosting-with-an-ambassador-id) -- [TLS Termination](#tls-termination) - -
- -An Ingress resource is a popular way to expose Kubernetes services to the Internet. In order to use Ingress resources, you need to install an [ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/). $productName$ can function as a fully-fledged Ingress controller, making it easy to work with other Ingress-oriented tools within the Kubernetes ecosystem. - -## When and how to use the Ingress resource - -If you're new to $productName$ and to Kubernetes, we'd recommend you start with our [quickstart](../../../tutorials/getting-started/) instead of this Ingress guide. If you're a power user and need to integrate with other software that leverages the Ingress resource, read on. The Ingress specification is very basic and does not support many of the features of $productName$, so you'll be using both the Ingress resource and $productName$'s Mapping resource to manage your Kubernetes services. - -### What is required to use the Ingress resource? - -- Know what version of Kubernetes you are using. - - - In Kubernetes 1.13 and below, the Ingress was only included in the `extensions` API. - - - Starting in Kubernetes 1.14, the Ingress was added to the new `networking.k8s.io` API. - - - Kubernetes 1.18 introduced the IngressClass resource to the existing `networking.k8s.io/v1beta1` API. - - If you are using 1.14 and above, it is recommended to use 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. - - -- You will need RBAC permissions to create Ingress resources in either - the `extensions` `apiGroup` (present in all supported versions of - Kubernetes) or the `networking.k8s.io` `apiGroup` (introduced in - Kubernetes 1.14). - -- $productName$ will need RBAC permissions to get, list, watch, and update Ingress resources. - - You can see this in the [`aes-crds.yaml`](https://app.getambassador.io/yaml/ambassador-docs/latest/aes.yaml) - file, but this is the critical rule to add to $productName$'s `Role` or `ClusterRole`: - - ```yaml - - apiGroups: ['extensions', 'networking.k8s.io'] - resources: ['ingresses', 'ingressclasses'] - verbs: ['get', 'list', 'watch'] - - apiGroups: ['extensions', 'networking.k8s.io'] - resources: ['ingresses/status'] - verbs: ['update'] - ``` - - - This is included by default in all $productName$ installations. - - -- You must create your Ingress resource with the correct `ingress.class`. - - $productName$ will automatically read Ingress resources with the annotation - `kubernetes.io/ingress.class: ambassador`. - -- You may need to set your Ingress resource's `ambassador-id`. - - If you are [using `amabssador-id` on your Module](../running/#ambassador_id), you'll need to add the `getambassador.io/ambassador-id` - annotation to your Ingress. See the [examples below](#name-based-virtual-hosting-with-an-ambassador-id). - -- You must create a Service resource with the correct `app.kubernetes.io/component` label. - - $productName$ will automatically load balance Ingress resources using the endpoint exposed - from the Service with the annotation `app.kubernetes.io/component: ambassador-service`. - - ```yaml - --- - kind: Service - apiVersion: v1 - metadata: - name: ingress-ambassador - labels: - app.kubernetes.io/component: ambassador-service - spec: - externalTrafficPolicy: Local - type: LoadBalancer - selector: - service: ambassador - ports: - - name: http - port: 80 - targetPort: http - - name: https - port: 443 - targetPort: https - ``` - -### When to use an Ingress instead of annotations or CRDs - -We recommend that $productName$ be configured using CRDs. The Ingress resource is available to users who need it for integration with other ecosystem tools, or who feel that it more closely matches their workflows. However, it is important to recognize that the Ingress resource is rather more limited than the $productName$ Mapping is (for example, the Ingress spec has no support for rewriting or for TLS origination). **When in doubt, use CRDs.** - -## Ingress support - -$productName$ supports basic core functionality of the Ingress resource, as defined by the [Ingress resource](https://kubernetes.io/docs/concepts/services-networking/ingress/) itself: - -- Basic routing is supported, including the `route` specification and the default backend functionality. It's particularly easy to use a minimal Ingress to the $productName$ diagnostic UI. -- [TLS termination](../tls/) is supported. You can use multiple Ingress resources for SNI. -- Using the Ingress resource in concert with $productName$ CRDs or annotations is supported. This includes $productName$ annotations on the Ingress resource itself. - -$productName$ does **not** extend the basic Ingress specification with the following exceptions: - -- The `getambassador.io/ambassador-id` annotation allows you to set [the Ambassador ID](../running/#ambassador_id) for the Ingress itself. - -- The `getambassador.io/config` annotation can be provided on the Ingress resource, just as on a Service. - -Note that if you need to set `getambassador.io/ambassador-id` on the Ingress, you will also need to set `ambassador-id` on resources within the annotation. - -## Examples of Ingress configs vs Mapping configs - -### Ingress routes and Mappings - -$productName$ actually creates Mapping objects from the Ingress route rules. These Mapping objects interact with Mappings defined in CRDs **exactly** as they would if the Ingress route rules had been specified with CRDs originally. - -For example, this Ingress resource routes traffic to `/foo/` to `service1`: - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: test-ingress -spec: - rules: - - http: - paths: - - path: /foo/ - backend: - serviceName: service1 - servicePort: 80 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: test-ingress-0-0 -spec: - hostname: '*' - prefix: /foo/ - service: service1:80 -``` - -This YAML will set up $productName$ to do canary routing where 50% of the traffic will go to `service1` and 50% will go to `service2`. - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: test-ingress -spec: - rules: - - http: - paths: - - path: /foo/ - backend: - serviceName: service1 - servicePort: 80 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: my-mapping -spec: - hostname: '*' - prefix: /foo/ - service: service2 -``` - -### The minimal Ingress - -An Ingress resource must provide at least some routes or a [default backend](https://kubernetes.io/docs/concepts/services-networking/ingress/#default-backend). The default backend provides for a simple way to direct all traffic to some upstream service: - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: test-ingress -spec: - backend: - serviceName: exampleservice - servicePort: 8080 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: test-ingress -spec: - hostname: '*' - prefix: / - service: exampleservice:8080 -``` - -### Name based virtual hosting with an Ambassador ID - -This Ingress resource will result in all requests to `foo.bar.com` going to `service1`, and requests to `bar.foo.com` going to `service2`: - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - getambassador.io/ambassador-id: externalid - name: name-virtual-host-ingress -spec: - rules: - - host: foo.bar.com - http: - paths: - - backend: - serviceName: service1 - servicePort: 80 - - host: bar.foo.com - http: - paths: - - backend: - serviceName: service2 - servicePort: 80 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: host-foo-mapping -spec: - ambassador_id: ['externalid'] - prefix: / - host: foo.bar.com - service: service1 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: host-bar-mapping -spec: - ambassador_id: ['externalid'] - prefix: / - host: bar.foo.com - service: service2 -``` - -Read more on the [Kubernetes documentation on name based virtual routing](https://kubernetes.io/docs/concepts/services-networking/ingress/#name-based-virtual-hosting). - -### TLS termination - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: tls-example-ingress -spec: - tls: - - hosts: - - sslexample.foo.com - secretName: testsecret-tls - rules: - - host: sslexample.foo.com - http: - paths: - - path: / - backend: - serviceName: service1 - servicePort: 80 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: sslexample-termination-context -spec: - hosts: - - sslexample.foo.com - secret: testsecret-tls ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: sslexample-mapping -spec: - host: sslexample.foo.com - prefix: / - service: service1 -``` - -Note that this shows TLS termination, not origination: the Ingress spec does not support origination. Read more on the [Kubernetes docs on TLS termination](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls). diff --git a/content/en/docs/3.1/topics/running/listener.md b/content/en/docs/3.1/topics/running/listener.md deleted file mode 100644 index 152e1b74..00000000 --- a/content/en/docs/3.1/topics/running/listener.md +++ /dev/null @@ -1,218 +0,0 @@ -# The `Listener` CRD - -The `Listener` CRD defines where, and how, $productName$ should listen for requests from the network, and which `Host` definitions should be used to process those requests. For further examples of how to use `Listener`, see [Configuring $productName$ Communications](../../../howtos/configure-communications). - -**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. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 # int32, port number on which to listen - protocol: HTTPS # HTTP, HTTPS, HTTPPROXY, HTTPSPROXY, TCP - securityModel: XFP # XFP (for X-Forwarded-Proto), SECURE, INSECURE - statsPrefix: example-listener # default depends on protocol; see below - l7Depth: 0 # int32 - hostBinding: - namespace: - from: SELF # SELF, ALL - selector: ... # Kubernetes label selector -``` - -| Element | Type | Definition | -| :------ | :--- | :--------- | -| `port` | `int32` | The network port on which $productName$ should listen. *Required.* | -| `protocol` | `enum`; see below | A high-level protocol type, like "HTTPS". *Exactly one of `protocol` and `protocolStack` must be supplied.* | -| `protocolStack` | array of `enum`; see below | A sequence of low-level protocols to layer together. *Exactly one of `protocol` and `protocolStack` must be supplied.* | -| `securityModel` | `enum`; see below | How does $productName$ decide whether requests here are secure? *Required.* | -| `statsPrefix` | `string`; see below | Under what name do statistics for this `Listener` appear? *Optional; default depends on protocol.* | -| `l7Depth` | `int32` | How many layer 7 load balancers are between the edge of the network and $productName$? *Optional; default is 0.*| -| `hostBinding` | `struct`, see below | Mechanism for determining which `Host`s will be associated with this `Listener`. *Required* | - -### `protocol` and `protocolStack` - -`protocol` is the **recommended** way to tell $productName$ that a `Listener` expects connections using a well-known protocol. When using `protocol`, `protocolStack` may not also be supplied. - -Valid `protocol` values are: - -| `protocol` | Description | -| :--------- | :---------- | -| `HTTP` | Cleartext-only HTTP. HTTPS is not allowed. | -| `HTTPS` | Either HTTPS or HTTP -- Envoy's TLS support can tell whether or not TLS is in use, and it will set `X-Forwarded-Proto` correctly for later decision-making. | -| `HTTPPROXY` | Cleartext-only HTTP, using the HAProxy `PROXY` protocol. | -| `HTTPSPROXY` | Either HTTPS or HTTP, using the HAProxy `PROXY` protocol. | -| `TCP` | TCP sessions without HTTP at all. You will need to use `TCPMapping`s to route requests for this `Listener`. | -| `TLS` | TLS sessions without HTTP at all. You will need to use `TCPMapping`s to route requests for this `Listener`. | - -### `securityModel` - -`securityModel` defines how the `Listener` will decide whether a request is secure or insecure: - -| `securityModel` | Description | -| :--------- | :---------- | -| `XFP` | Requests are secure if, and only if, `X-Forwarded-Proto` indicates HTTPS. This is common; see below. | -| `SECURE` | Requests are always secure. You might set this if your load balancer always terminates TLS for you, and you can trust the clients. | -| `INSECURE` | Requests are always insecure. You might set this for an HTTP-only `Listener`, or a `Listener` for clients that are expected to be hostile. | - -The `X-Forwarded-Proto` header mentioned above is meant to reflect the protocol the _original client_ -used to contact $productName$. When no layer 7 proxies are in use, Envoy will make certain that the -`X-Forwarded-Proto` header matches the wire protocol of the connection the client made to Envoy, -which allows $productName$ to trust `X-Forwarded-Proto` for routing decisions such as deciding to -redirect requests made using HTTP over to HTTPS for greater security. When using $productName$ as an -edge proxy or a typical API gateway, this is a desirable configuration; setting `securityModel` to -`XFP` makes this easy. - -When layer proxies _are_ in use, the `XFP` setting is often still desirable; however, you will also -need to set `l7Depth` to allow it to function. See below. - -`SECURE` and `INSECURE` are helpful for cases where something downstream of $productName$ should be -allowing only one kind of request to reach $productName$. For example, a `Listener` behind a load -balancer that terminates TLS and checks client certificates might use -`SecurityModel: SECURE`, then use `Host`s to reject insecure requests if one somehow -arrives. - -### `l7Depth` - -When layer 7 (L7) proxies are in use, the connection to $productName$ comes from the L7 proxy itself -rather than from the client. Examining the protocol and IP address of that connection is useless, and -instead you need to configure the L7 proxy to pass extra information about the client to $productName$ -using the `X-Forwarded-Proto` and `X-Forwarded-For` headers. - -However, if $productName$ always trusted `X-Forwarded-Proto` and `X-Forwarded-For`, any client could -use them to lie about itself to $productName$. As a security mechanism, therefore, you must _also_ -set `l7Depth` in the `Listener` to the number of trusted L7 proxies in front of $productName$. If -`l7Depth` is not set in the `Listener`, the `xff_num_trusted_hops` value from the `ambassador` `Module` -will be used. If neither is set, the default `l7Depth` is 0. - -When `l7Depth` is 0, any incoming `X-Forwarded-Proto` is stripped: Envoy always provides an -`X-Forwarded-Proto` matching the wire protocol of the incoming connection, so that `X-Forwarded-Proto` -can be trusted. When `l7Depth` is non-zero, `X-Forwarded-Proto` is accepted from the L7 proxy, and -trusted. The actual wire protocol in use from the L7 proxy to $productName$ is ignored. - -`l7Depth` also affects $productName$'s view of the client's source IP address, which is used as the -`remote_address` field when rate limiting, and for the `X-Envoy-External-Address` header: - -- When `l7Depth` is 0, $productName$ uses the IP address of the incoming connection. -- When `l7Depth` is some value N that is non-zero, the behavior is determined by the value of - `use_remote_address` in the `ambassador` `Module`: - - - When `use_remote_address` is true (the default) then the trusted client address will be the Nth - address from the right end of the `X-Forwarded-For` header. (If the XFF contains fewer than N - addresses, Envoy falls back to using the immediate downstream connection’s source address as a - trusted client address.) - - - When `use_remote_address` is false, the trusted client address is the (N+1)th address from the - right end of XFF. (If the XFF contains fewer than N+1 addresses, Envoy falls back to using the - immediate downstream connection’s source address as a trusted client address.) - - For more detailed examples of this interaction, refer to [Envoy's documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers.html#x-forwarded-for). - - -### `hostBinding` - -`hostBinding` specifies how this `Listener` should determine which `Host`s are associated with it: - -- `namespace.from` allows filtering `Host`s by the namespace of the `Host`: - - `namespace.from: SELF` accepts only `Host`s in the same namespace as the `Listener`. - - `namespace.from: ALL` accepts `Host`s in any namespace. -- `selector` accepts only `Host`s that has labels matching the selector. - -`hostBinding` is mandatory, and at least one of `namespace.from` and `selector` must be set. If both are set, both must match for a `Host` to be accepted. - -### `statsPrefix` - -$productName$ produces detailed [statistics](../statistics) which can be monitored in a variety of ways. Statistics have hierarchical names, and the `Listener` will cause a set of statistics to be logged under the name specified by `statsPrefix`. - -The default `statsPrefix` depends on the protocol for this `Listener`: - -- If the `Listener` speaks HTTPS, the default is `ingress-https`. -- Otherwise, if the `Listener` speaks HTTP, the default is `ingress-http`. -- Otherwise, if the `Listener` speaks TLS, the default is `ingress-tls-$port`. -- Otherwise, the default is `ingress-$port`. - -Note that it doesn't matter whether you use `protocol` or `protocolStack`: what matters is what protocol is actually configured. Also note that the default doesn't take the HAProxy `PROXY` protocol into account. - -Some examples: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 - protocol: HTTPS - ... -``` - -will use a `statsPrefix` of `ingress-https`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 - protocol: TCP - ... -``` - -will use `statsPrefix` of `ingress-8080`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 - protocol: HTTPSPROXY - statsPrefix: proxy-8080 - ... -``` - -would also use `ingress-https`, but it explicitly overrides `statsPrefix` to `proxy-8080`. - -For complete information on which statistics will appear for the `Listener`, see [the Envoy listener statistics documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/listeners/stats.html). Some important statistics include - -| Statistic name | Type | Description | -| :-----------------------------------------------| :-------- | :-------------------------------- | -| `listener.$statsPrefix.downstream_cx_total` | Counter | Total connections | -| `listener.$statsPrefix.downstream_cx_active` | Gauge | Total active connections | -| `listener.$statsPrefix.downstream_cx_length_ms` | Histogram | Connection length in milliseconds | - -### `protocolStack` - -**`protocolStack` is not recommended if you can instead use `protocol`.** - -Where `protocol` allows configuring the `Listener` to use well-known protocol stacks, `protocolStack` allows configuring exactly which protocols will be layered together. If `protocol` allows what you need, it is safer to use `Protocol` than to risk having the stack broken with an incorrect `protocolStack`. - -The possible stack elements are: - -| `ProtocolStack` Element | Description | -| :---------------------- | :---------- | -| `HTTP` | Cleartext-only HTTP; must be layered with `TLS` for HTTPS | -| `PROXY` | The HAProxy `PROXY` protocol | -| `TLS` | TLS | -| `TCP` | Raw TCP | - -`protocolStack` supplies a list of these elements to describe the protocol stack. **Order matters.** Some examples: - -| `protocolStack` | Description | -| :-------------- | :---------- | -| [ `HTTP`, `TCP` ] | Cleartext-only HTTP, exactly equivalent to `protocol: HTTP`. | -| [ `TLS`, `HTTP`, `TCP` ] | HTTPS or HTTP, exactly equivalent to `protocol: HTTPS`. | -| [ `PROXY`, `TLS`, `TCP` ] | The `PROXY` protocol, wrapping `TLS` _afterward_, wrapping raw TCP. This isn't equivalent to any `protocol` setting, and may be nonsensical. | - -## Examples - -For further examples of how to use `Listener`, see [Configuring $productName$ to Communicate](../../../howtos/configure-communications). diff --git a/content/en/docs/3.1/topics/running/load-balancer.md b/content/en/docs/3.1/topics/running/load-balancer.md deleted file mode 100644 index 987a910b..00000000 --- a/content/en/docs/3.1/topics/running/load-balancer.md +++ /dev/null @@ -1,209 +0,0 @@ -# Load balancing - -Load balancing configuration can be set for all $productName$ mappings in the [`ambassador` `Module`](../ambassador), or set per [`Mapping`](../../using/mappings). If nothing is set, simple round robin balancing is used via Kubernetes services. - -To use advanced load balancing, you must first configure a [resolver](../resolvers) that supports advanced load balancing (e.g., the Kubernetes Endpoint Resolver or Consul Resolver). Once a resolver is configured, you can use the `load_balancer` attribute. The following fields are supported: - -```yaml -load_balancer: - policy: -``` - -Supported load balancer policies: - -- `round_robin` -- `least_request` -- `ring_hash` -- `maglev` - -For more information on the different policies and the implications, see [load balancing strategies in Kubernetes](https://blog.getambassador.io/load-balancing-strategies-in-kubernetes-l4-round-robin-l7-round-robin-ring-hash-and-more-6a5b81595d6c). - -## Round robin -When `policy` is set to `round_robin`, $productName$ discovers healthy endpoints for the given mapping, and load balances the incoming L7 requests with round robin scheduling. To specify this: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - resolver: my-resolver - load_balancer: - policy: round_robin -``` - -or, per mapping: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - resolver: my-resolver - hostname: '*' - load_balancer: - policy: round_robin -``` - -Note that load balancing may not appear to be "even" due to Envoy's threading model. For more details, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/faq/load_balancing/concurrency_lb). - -## Least request - -When `policy` is set to `least_request`, $productName$ discovers healthy endpoints for the given mapping, and load balances the incoming L7 requests to the endpoint with the fewest active requests. To specify this: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - resolver: my-resolver - load_balancer: - policy: least_request -``` - -or, per mapping: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend/ -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: least_request -``` - -## Sticky sessions / session affinity - -Configuring sticky sessions makes $productName$ route requests to a specific pod providing your service in a given session. One pod serves all requests from a given session, eliminating the need for session data to be transferred between pods. $productName$ lets you configure session affinity based on the following parameters in an incoming request: - -- Cookie -- Header -- Source IP - -**NOTE:** $productName$ supports sticky sessions using two load balancing policies, `ring_hash` and `maglev`. - -### Cookie - -```yaml -load_balancer: - policy: ring_hash - cookie: - name: - ttl: - path: -``` - -If the cookie you wish to set affinity on is already present in incoming requests, then you only need the `cookie.name` field. However, if you want $productName$ to generate and set a cookie in response to the first request, then you need to specify a value for the `cookie.ttl` field which generates a cookie with the given expiration time. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - hostname: '*' - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - cookie: - name: sticky-cookie - ttl: 60s -``` - -### Header - -```yaml -load_balancer: - policy: ring_hash - header:
-``` - -$productName$ allows header based session affinity if the given header is present on incoming requests. - -Example: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - header: STICKY_HEADER -``` - -#### Source IP - -```yaml -load_balancer: - policy: ring_hash - source_ip: -``` - -$productName$ allows session affinity based on the source IP of incoming requests. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - source_ip: true -``` - -Load balancing can be configured both globally, and overridden on a per mapping basis. The following example configures the default load balancing policy to be round robin, while using header-based session affinity for requests to the `/backend/` endpoint of the quote application: - -Load balancing can be configured both globally, and overridden on a per mapping basis. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - resolver: my-resolver - load_balancer: - policy: round_robin -``` - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - header: STICKY_HEADER -``` diff --git a/content/en/docs/3.1/topics/running/resolvers.md b/content/en/docs/3.1/topics/running/resolvers.md deleted file mode 100644 index 1ace9a86..00000000 --- a/content/en/docs/3.1/topics/running/resolvers.md +++ /dev/null @@ -1,128 +0,0 @@ -# Service discovery and resolvers - -Service discovery is how cloud applications and their microservices are located on the network. In a cloud environment, services are ephemeral, existing only as long as they are needed and in use, so a real-time service discovery mechanism is required. $productName$ uses information from service discovery to determine where to route incoming requests. - -## $productName$ support for service discovery - -$productName$ supports different mechanisms for service discovery. These mechanisms are: - -* Kubernetes service-level discovery (default). -* Kubernetes endpoint-level discovery. -* Consul endpoint-level discovery. - -### Kubernetes service-level discovery - -By default, $productName$ uses Kubernetes DNS and service-level discovery. In a `Mapping` resource, specifying `service: foo` will prompt $productName$ to look up the DNS address of the `foo` Kubernetes service. Traffic will be routed to the `foo` service. Kubernetes will then load balance that traffic between multiple pods. For more details on Kubernetes networking and how this works, see our blog post on [Session affinity, load balancing controls, gRPC-Web, and $productName$](https://blog.getambassador.io/session-affinity-load-balancing-controls-grpc-web-and-ambassador-0-52-2b916b396d0c). - -### Kubernetes endpoint-level discovery - -$productName$ can also watch Kubernetes endpoints. This bypasses the Kubernetes service routing layer and enables the use of advanced load balancing controls such as session affinity and maglev. For more details, see the [load balancing reference](../load-balancer). - -### Consul endpoint-level discovery - -$productName$ natively integrates with [Consul](https://www.consul.io) for endpoint-level service discovery. In this mode, $productName$ obtains endpoint information from Consul. One of the primary use cases for this architecture is in hybrid cloud environments that run a mixture of Kubernetes services as well as VMs, as Consul can serve as the single global registry for all services. - -## The Resolver resource - -The `Resolver` resource is used to configure the discovery service strategy for $productName$. - -### The Kubernetes service resolver - -The Kubernetes Service Resolver configures $productName$ to use Kubernetes services. If no resolver is specified, this behavior is the default. When this resolver is used, the `service.namespace` value from a `Mapping` is handed to the Kubernetes cluster's DNS resolver to determine where requests are sent. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: KubernetesServiceResolver -metadata: - name: kubernetes-service -``` - -### The Kubernetes endpoint resolver - -The Kubernetes Endpoint Resolver configures $productName$ to resolve Kubernetes endpoints. This enables the use of more a [advanced load balancing configuration](../load-balancer). When this resolver is used, the endpoints for the `service` defined in a `Mapping` are resolved and used to determine where requests are sent. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: KubernetesEndpointResolver -metadata: - name: endpoint -``` - -### The Consul resolver - -The Consul Resolver configures $productName$ to use Consul for service discovery. When this resolver is used, the `service` defined in a `Mapping` is passed to Consul, along with the datacenter specified, to determine where requests are sent. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: ConsulResolver -metadata: - name: consul-dc1 -spec: - address: consul-server.default.svc.cluster.local:8500 - datacenter: dc1 -``` -- `address`: The fully-qualified domain name or IP address of your Consul server. This field also supports environment variable substitution. -- `datacenter`: The Consul data center where your services are registered - -You may want to use an environment variable if you're running a Consul agent on each node in your cluster. In this setup, you could do the following: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: ConsulResolver -metadata: - name: consul-dc1 -spec: - address: "${HOST_IP}" - datacenter: dc1 -``` - -and then add the `HOST_IP` environment variable to your Kubernetes deployment: - -```yaml -containers: - - name: example - image: docker.io/datawire/ambassador:$version$ - env: - - name: HOST_IP - valueFrom: - fieldRef: - fieldPath: status.hostIP -``` - -## Using resolvers - -Once a resolver is defined, you can use them in a given `Mapping`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: "*" - prefix: /backend/ - service: quote - resolver: endpoint - load_balancer: - policy: round_robin ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: bar -spec: - hostname: "*" - prefix: /bar/ - service: https://bar:9000 - tls: client-context - resolver: consul-dc1 - load_balancer: - policy: round_robin -``` - -The YAML configuration above will configure $productName$ to use Kubernetes Service Discovery to route to the Consul Service Discovery to route to the `bar` service on requests with `prefix: /bar/`. diff --git a/content/en/docs/3.1/topics/running/running.md b/content/en/docs/3.1/topics/running/running.md deleted file mode 100644 index a28b0cb5..00000000 --- a/content/en/docs/3.1/topics/running/running.md +++ /dev/null @@ -1,338 +0,0 @@ -# Running and deployment - -This section is intended for operators running $productName$, and covers various aspects of deploying and configuring the $productName$ in production. - -## $productName$ and Kubernetes - -$productName$ relies on Kubernetes for reliability, availability, and scalability. This means that features such as Kubernetes readiness and liveness probes, rolling updates, and the Horizontal Pod Autoscaling should be utilized to manage $productName$. - -## Default configuration - -The default configuration of $productName$ includes default [resource limits](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-requests-and-limits-of-pod-and-container), as well as [readiness and liveness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/). These values should be adjusted for your specific environment. - -## Running as non-root - -Starting with $productName$ 0.35, we support running $productName$ as non-root. This is the recommended configuration, and will be the default configuration in future releases. We recommend you configure $productName$ to run as non-root as follows: - -* Have Kubernetes run $productName$ as non-root. This may happen by default (e.g., OpenShift) or you can set a `securityContext` in your Deployment as shown below in this abbreviated example: - -```yaml ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: ambassador -spec: - replicas: 1 - selector: - matchLabels: - service: ambassador - template: - metadata: - labels: - service: ambassador - spec: - containers: - image: docker.io/datawire/aes:$version$ - name: ambassador - restartPolicy: Always - securityContext: - runAsUser: 8888 - serviceAccountName: ambassador -``` - -* Set the `service_port` element in the `ambassador Module` to 8080 (cleartext) or 8443 (TLS). This is the port that $productName$ will use to listen to incoming traffic. Note that any port number above 1024 will work; $productName$ will use 8080/8443 as its defaults in the future. - -* Make sure that incoming traffic to $productName$ is configured to route to the `service_port`. If you're using the default $productName$ configuration, this means configuring the `targetPort` to point to the `service_port` above. - -* If you are using `redirect_cleartext_from`, change the value of this field to point to your cleartext port (e.g., 8080) and set `service_port` to be your TLS port (e.g., 8443). - -## Changing the configuration directory - -While running, $productName$ needs to use a directory within its container for generated configuration data. Normally this is `/ambassador`, but in some situations - especially if running as non-root - it may be necessary to change to a different directory. To do so, set the environment variable `AMBASSADOR_CONFIG_BASE_DIR` to the full pathname of the directory to use, as shown below in this abbreviated example: - -```yaml -env: -- name: AMBASSADOR_CONFIG_BASE_DIR - value: /tmp/ambassador-config -``` - -With `AMBASSADOR_CONFIG_BASE_DIR` set as above, $productName$ will create and use the directory `/tmp/ambassador-config` for its generated data. (Note that, while the directory will be created if it does not exist, attempts to turn an existing file into a directory will fail.) - -## Running as DaemonSet - -$productName$ can be deployed as a DaemonSet to have one pod per node in a Kubernetes cluster. This setup is especially helpful when you have a Kubernetes cluster running on a private cloud. - -* In an ideal example scenario, you are running containers on Kubernetes alongside with your non-containerized applications running exposed via VIP using BIG-IP or similar products. In such cases, east-west traffic is routed based on iRules to certain a set of application pools consisting of application or web servers. In this setup, alongside traditional application servers, two or more $productName$ pods can also be part of the application pools. In case of failure there is at least one $productName$ pod available to BIG-IP that can take care of routing traffic to the Kubernetes cluster. - -* In manifest files `kind: Deployment` needs to be updated to `kind: DaemonSet` and `replicas` should be removed in `spec` section. - -## Namespaces - -$productName$ supports multiple namespaces within Kubernetes. To make this work correctly, you need to set the `AMBASSADOR_NAMESPACE` environment variable in $productName$'s container. By far the easiest way to do this is using Kubernetes' downward API (this is included in the YAML files from `getambassador.io`): - -```yaml -env: -- name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace -``` - -Given that `AMBASSADOR_NAMESPACE` is set, $productName$ [`Mappings`](../../using/mappings) can operate within the same namespace, or across namespaces. **Note well** that `Mappings` will have to explicitly include the namespace with the service to cross namespaces; see the [`Mapping`](../../using/mappings) documentation for more information. - -If you want $productName$ to only work within a single namespace, set `AMBASSADOR_SINGLE_NAMESPACE` as an environment variable. - -```yaml -env: -- name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace -- name: AMBASSADOR_SINGLE_NAMESPACE - value: "true" -``` - -With $productName$, if you set `AMBASSADOR_NAMESPACE` or `AMBASSADOR_SINGLE_NAMESPACE`, set it in the deployment container. - -If you want to set a certificate for your `TLScontext` from another namespace, you can use the following: - -```yaml -env: -- name: AMBASSADOR_SINGLE_NAMESPACE - value: "YES" -- name: AMBASSADOR_CERTS_SINGLE_NAMESPACE - value: "YES" -- name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - apiVersion: v1 - fieldPath: metadata.namespace -``` - -## `AMBASSADOR_ID` - -$productName$ supports running multiple $productNamePlural$ in the same cluster, without restricting a given $productName$ to a single namespace. This is done with the `AMBASSADOR_ID` setting. In the `ambassador Module`, set the `ambassador_id`, e.g., - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - ambassador_id: [ "ambassador-1" ] - config: - ... -``` - -Then, assign each $productName$ pod a unique `AMBASSADOR_ID` with the environment variable as part of your deployment: - -```yaml -env: -- name: AMBASSADOR_ID - value: ambassador-1 -``` - -With $productName$, if you set `AMBASSADOR_ID`, you will need to set it in the deployment container. - -$productName$ will then only use YAML objects that include an appropriate `ambassador_id` attribute. For example, if $productName$ is given the ID `ambassador-1` as above, only the first two YAML objects below will be used: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-used -spec: - ambassador_id: [ "ambassador-1" ] - prefix: /demo1/ - service: demo1 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-used-2 -spec: - ambassador_id: [ "ambassador-1", "ambassador-2" ] - prefix: /demo2/ - service: demo2 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-skipped -spec: - prefix: /demo3/ - service: demo3 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-skipped-2 -spec: - ambassador_id: [ "ambassador-2" ] - prefix: /demo4/ - service: demo4 -``` - -`ambassador_id` is always a list, and may (as shown in `mapping-used-2` above) include multiple IDs to allow a given object in the configuration for multiple $productName$ instances. In this case, `mapping-used-2` will be included in the configuration for `ambassador-1` and also for `ambassador-2`. - -**Note well that _any_ $productName$ configuration resource can have an `ambassador_id` included** so, for example, it is _fully supported_ to use `ambassador_id` to qualify the `ambassador Module`, `TLSContext`, and `AuthService` objects. You will need to set `ambassador_id` in all resources you want to use for $productName$. - -If no `AMBASSADOR_ID` is assigned to an $productName$, it will use the ID `default`. If no `ambassador_id` is present in a YAML object, it will also use the ID `default`. - -## `AMBASSADOR_ENVOY_BASE_ID` - -$productName$ supports running side-by-side with other envoy-based projects in a single pod. An example of this is running with an `istio` sidecar. This is done with the `AMBASSADOR_ENVOY_BASE_ID` environment variable as part of your deployment: - -```yaml -env: -- name: AMBASSADOR_ENVOY_BASE_ID - value: 1 -``` - -If no `AMBASSADOR_ENVOY_BASE_ID` is provided then it will use the ID `0`. For more information on the Envoy base-id option please see the [Envoy command line documentation](https://www.envoyproxy.io/docs/envoy/latest/operations/cli.html?highlight=base%20id#cmdoption-base-id). - -## `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. - -## `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. - -## `AMBASSADOR_LEGACY_MODE` - -Setting `AMBASSADOR_LEGACY_MODE` to `true` will result in $productName$ disabling certain features -and reverting to older codepaths which may be better preserve certain older behaviors. Legacy mode -currently has the following effects: - -- $productName$ will switch back to the $productName$ 1.6 input-resource validator (which can significantly -increase configuration latency for $productName$ installations with many resources). -- $productName$ will use the shell boot sequence that was the default up through 1.9.1, rather than the Golang boot sequence that became the default in 1.10.0. -- `AMBASSADOR_FAST_RECONFIGURE` (see below) is not supported in legacy mode. - -## `AMBASSADOR_FAST_RECONFIGURE` - -Setting `AMBASSADOR_FAST_RECONFIGURE` to "true" enables incremental reconfiguration. When enabled, $productName$ will track deltas from one configuration to the next and recalculate only what is necessary to follow the change. When disabled (the default), $productName$ will recompute the entire configuration at every change. - -**`AMBASSADOR_FAST_RECONFIGURE` is not supported when `AMBASSADOR_LEGACY_MODE` is active.** - -## Configuration from the filesystem - -If desired, $productName$ can be configured from YAML files in the directory `$AMBASSADOR_CONFIG_BASE_DIR/ambassador-config` (by default, `/ambassador/ambassador-config`, which is empty in the images built by Datawire). You could volume mount an external configuration directory here, for example, or use a custom Dockerfile to build configuration directly into a Docker image. - -Note well that while $productName$ will read its initial configuration from this directory, configuration loaded from Kubernetes annotations will _replace_ this initial configuration. If this is not what you want, you will need to set the environment variable `AMBASSADOR_NO_KUBEWATCH` so that $productName$ will not try to update its configuration from Kubernetes resources. - -Also note that the YAML files in the configuration directory must contain the $productName$ resources, not Kubernetes resources with annotations. - -## Log levels and debugging - -The $OSSproductName$ and $AESproductName$ support more verbose debugging levels. If using $OSSproductName$, the [diagnostics](../diagnostics) service has a button to enable debug logging. Be aware that if you're running $productName$ on multiple pods, the debug log levels are not enabled for all pods -- they are configured on a per-pod basis. - -If using $AESproductName$, you can 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 format - -By default, $productName$ writes its own logs in a plain text format. To produce logs as JSON instead, set the `AMBASSADOR_JSON_LOGGING` environment variable: - -```yaml -env: -- name: AMBASSADOR_JSON_LOGGING - value: "true" -``` - -## Port assignments - -$productName$ uses some TCP ports in the range 8000-8499 internally, as well as port 8877. Third-party software integrating with $productName$ should not use ports in this range on the $productName$ pod. - -## $productName$ update checks (Scout) - -$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 $productName$ will run regardless of the status of Scout (i.e., our uptime has zero impact on your uptime.) - -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. - -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. - -Unless disabled, $productName$ will also report the following anonymized information back to Datawire: - -| Attribute | Type | Description | -| :------------------------ | :---- | :------------------------ | -| `cluster_count` | int | total count of clusters in use | -| `cluster_grpc_count` | int | count of clusters using GRPC upstream | -| `cluster_http_count` | int | count of clusters using HTTP or HTTPS upstream | -| `cluster_routing_envoy_rh_count` | int | count of clusters routing using Envoy `ring_hash` | -| `cluster_routing_envoy_maglev_count` | int | count of clusters routing using Envoy `maglev` | -| `cluster_routing_envoy_lr_count` | int | count of clusters routing using Envoy `least_request` | -| `cluster_routing_envoy_rr_count` | int | count of clusters routing using Envoy `round_robin` | -| `cluster_routing_kube_count` | int | count of clusters routing using Kubernetes | -| `cluster_tls_count` | int | count of clusters originating TLS | -| `custom_ambassador_id` | bool | has the `ambassador_id` been changed from 'default'? | -| `custom_listener_port` | bool | has the listener port been changed from 80/443? | -| `diagnostics` | bool | is the diagnostics service enabled? | -| `endpoint_grpc_count` | int | count of endpoints to which $productName$ will originate GRPC | -| `endpoint_http_count` | int | count of endpoints to which $productName$ will originate HTTP or HTTPS | -| `endpoint_routing` | bool | is endpoint routing enabled? | -| `endpoint_routing_envoy_rh_count` | int | count of endpoints being routed using Envoy `ring_hash` | -| `endpoint_routing_envoy_maglev_count` | int | count of endpoints being routed using Envoy `maglev` | -| `endpoint_routing_envoy_lr_count` | int | count of endpoints being routed using Envoy `least_request` | -| `endpoint_routing_envoy_rr_count` | int | count of endpoints being routed using Envoy `round_robin` | -| `endpoint_routing_kube_count` | int | count of endpoints being routed using Kubernetes | -| `endpoint_tls_count` | int | count of endpoints to which $productName$ will originate TLS | -| `extauth` | bool | is extauth enabled? | -| `extauth_allow_body` | bool | will $productName$ send the body to extauth? | -| `extauth_host_count` | int | count of extauth hosts in use | -| `extauth_proto` | str | extauth protocol in use ('http', 'grpc', or `null` if not active) | -| `group_canary_count` | int | count of Mapping groups that include more than one Mapping | -| `group_count` | int | total count of Mapping groups in use (length of the route table) | -| `group_header_match_count` | int | count of groups using header matching (including `host` and `method`) | -| `group_host_redirect_count` | int | count of groups using host_redirect | -| `group_host_rewrite_count` | int | count of groups using host_rewrite | -| `group_http_count` | int | count of HTTP Mapping groups | -| `group_precedence_count` | int | count of groups that explicitly set the precedence of the group | -| `group_regex_header_count` | int | count of groups using regex header matching | -| `group_regex_prefix_count` | int | count of groups using regex prefix matching | -| `group_resolver_consul` | int | count of groups using the Consul resolver | -| `group_resolver_kube_endpoint` | int | count of groups using the Kubernetes endpoint resolver | -| `group_resolver_kube_service` | int | count of groups using the Kubernetes service resolver | -| `group_shadow_count` | int | count of groups using shadows | -| `group_shadow_weighted_count` | int | count of groups using shadows but not shadowing all traffic | -| `group_tcp_count` | int | count of TCP Mapping groups | -| `host_count` | int | count of Host resources in use | -| `k8s_ingress_class_count` | int | count of IngressClass resources in use | -| `k8s_ingress_count` | int | count of Ingress resources in use | -| `listener_count` | int | count of active listeners (1 unless `redirect_cleartext_from` or TCP Mappings are in use) | -| `liveness_probe` | bool | are liveness probes enabled? | -| `managed_by` | string | tool that manages the $productName$ deployment, if any (e.g. helm, edgectl, etc.) | -| `mapping_count` | int | count of Mapping resources in use | -| `ratelimit` | bool | is rate limiting in use? | -| `ratelimit_custom_domain` | bool | has the rate limiting domain been changed from 'ambassador'? | -| `ratelimit_data_plane_proto` | bool | is rate limiting using the data plane proto? | -| `readiness_probe` | bool | are readiness probes enabled? | -| `request_4xx_count` | int | lower bound for how many requests have gotten a 4xx response | -| `request_5xx_count` | int | lower bound for how many requests have gotten a 5xx response | -| `request_bad_count` | int | lower bound for how many requests have failed (either 4xx or 5xx) | -| `request_elapsed` | float | seconds over which the request_ counts are valid | -| `request_hr_elapsed` | string | human-readable version of `request_elapsed` (e.g. "3 hours 35 minutes 20 seconds" | -| `request_ok_count` | int | lower bound for how many requests have succeeded (not a 4xx or 5xx) | -| `request_total_count` | int | lower bound for how many requests were handled in total | -| `statsd` | bool | is StatsD enabled? | -| `server_name` | bool | is the `server_name` response header overridden? | -| `service_resource_total` | int | total count of service resources loaded from all discovery sources | -| `tls_origination_count` | int | count of TLS origination contexts | -| `tls_termination_count` | int | count of TLS termination contexts | -| `tls_using_contexts` | bool | are new TLSContext resources in use? ? | -| `tls_using_module` | bool |is the old TLS module in use | -| `tracing` | bool | is tracing in use? | -| `tracing_driver` | str | tracing driver in use ('zipkin', 'lightstep', 'datadog', or `null` if not active) | -| `use_proxy_proto` | bool | is the `PROXY` protocol in use? | -| `use_remote_address` | bool | is $productName$ honoring remote addresses? | -| `x_forwarded_proto_redirect` | bool | is $productName$ redirecting based on `X-Forwarded-Proto`? | -| `xff_num_trusted_hops` | int | what is the count of trusted hops for `X-Forwarded-For`? | - -The `request_*` counts are always incremental: they contain only information about the last `request_elapsed` seconds. Additionally, they only provide a lower bound -- notably, if an $productName$ pod crashes or exits, no effort is made to ship out a final update, so it's very easy for counts to never be reported. - -To completely disable feature reporting, set the environment variable `AMBASSADOR_DISABLE_FEATURES` to any non-empty value. diff --git a/content/en/docs/3.1/topics/running/scaling.md b/content/en/docs/3.1/topics/running/scaling.md deleted file mode 100644 index 22fa743e..00000000 --- a/content/en/docs/3.1/topics/running/scaling.md +++ /dev/null @@ -1,194 +0,0 @@ -# Performance and scaling $productName$ - -Scaling any cloud native application is inherently domain specific, however the content here -reflects common issues, tips, and tricks that come up frequently. - -## Performance dimensions - -The performance of $productName$'s control plane can be characterized along a number of -different dimensions: - - - The number of `TLSContext` resources. - - The number of `Host` resources. - - The number of `Mapping` resources per `Host` resource. - - The number of `Mapping` resources that will span all `Host` resources (either because they're using `host_regex`, or because they're using `hostname: "*"`). - -If your application involves a larger than average number of any of the above resources, you may -find yourself in need of some of the content in this section. - -## Mysterious pod restarts (aka pushing the edge of the envelope) - -Whether your application is growing organically or whether you are deliberately scale testing, it's -helpful to recognize how $productName$ behaves as it reaches the edge of its performance -envelope along any of these dimensions. - -As $productName$ approaches the edge of its performance envelope, it will often manifest as -mysterious pod restarts triggered by Kubernetes. This does not always mean there is a problem, it -could just mean you need to tune some of the resource limits set in your deployment. When it comes -to scaling, Kubernetes will generally kill an $productName$ pod for one of two reasons: exceeding -memory limits or failed liveness/readiness probes. See the [Memory Limits](#memory-limits), -[Liveness Probes](#liveness-probes), and [Readiness Probes](#readiness-probes) -sections for more on how to cope with these situations. - -## Memory limits - -$productName$ can grow in memory usage and be killed by Kubernetes if it exceeds the limits -defined in its pod spec. When this happens it is confusing and difficult to catch because the only -indication that this has occurred is the pod transitioning momentarily into the `OOMKilled` -state. The only way to actually observe this is if you are lucky enough to be running the following -command (or have similar monitoring configured) when $productName$ gets `OOMKilled`: - -``` - kubectl get pods -n ambassador -w -``` - -In order to take the luck out of the equation, $productName$ will periodically log its -memory usage so you can see in the logs if memory limits might be a problem and require adjustment: - -``` -2020/11/26 22:35:20 Memory Usage 0.56Gi (28%) - PID 1, 0.22Gi: busyambassador entrypoint - PID 14, 0.04Gi: /usr/bin/python /usr/bin/diagd /ambassador/snapshots /ambassador/bootstrap-ads.json /ambassador/envoy/envoy.json --notices /ambassador/notices.json --port 8004 --kick kill -HUP 1 - PID 16, 0.12Gi: /ambassador/sidecars/amb-sidecar - PID 37, 0.07Gi: /usr/bin/python /usr/bin/diagd /ambassador/snapshots /ambassador/bootstrap-ads.json /ambassador/envoy/envoy.json --notices /ambassador/notices.json --port 8004 --kick kill -HUP 1 - PID 48, 0.08Gi: envoy -c /ambassador/bootstrap-ads.json --base-id 0 --drain-time-s 600 -l error -``` - -In general you should try to keep $productName$'s memory usage below 50% of the pod's limit. This may -seem like a generous safety margin, but when reconfiguration occurs, $productName$ requires additional -memory to avoid disrupting active connections. At each reconfiguration, $productName$ keeps around the -old version for the duration of the configured drain time. See -[AMBASSADOR_DRAIN_TIME](#ambassador_drain_time) for more details on how to tune this -behavior. - -$productName$'s exact memory usage depends on (among other things) how many `Host` and -`Mapping` resources are defined in your cluster. If this number has grown over time, you may need to -increase the memory limit defined in your deployment. - -## Liveness probes - -$productName$ defines the `/ambassador/v0/check_alive` endpoint on port `8877` for use with Kubernetes -liveness probes. See the Kubernetes documentation for more details on [HTTP liveness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-a-liveness-http-request). - -Kubernetes will restart the $productName$ pod if it fails to get a 200 result from the endpoint. If -this happens it won't necessarily show up in an easily recognizable way in the pod logs. You can -look for Kubernetes events to see if this is happening. Use `kubectl describe pod -n ambassador` or -`kubectl get events -n ambassador` or equivalent. - -The purpose of liveness probes is to rescue an $productName$ instance that is wedged, however if -liveness probes are too sensitive they can take out $productName$ instances that are functioning -normally. This is more prone to happen as the number of $productName$ inputs increase. The -`timeoutSeconds` and `failureThreshold` fields of the $productName$ deployment's liveness Probe -determines how tolerant Kubernetes is with its probes. If you observe pod restarts along with -`Unhealthy` events, try tuning these fields upwards from their default values. See the Kubernetes documentation for more details on [tuning probes](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#probe-v1-core). - -Note that whatever changes you make to $productName$'s liveness probes should most likely be made to -its readiness probes also. - -## Readiness probes - -$productName$ defines the `/ambassador/v0/check_ready` endpoint on port `8877` for use with Kubernetes -readiness probes. See the Kubernetes documentation for more details on [readiness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-readiness-probes). - -Kubernetes uses readiness checks to prevent traffic from going to pods that are not ready to handle -requests. The only time $productName$ cannot usefully handle requests is during initial startup when it -has not yet loaded all the routing information from Kubernetes and/or consul. During this bootstrap -period there is no guarantee $productName$ would know where to send a given request. The `check_ready` -endpoint will only return 200 when all routing information has been loaded. After the initial -bootstrap period it behaves identically to the `check_alive` endpoint. - -Generally $productName$'s readiness probes should be configured with the same settings as its liveness -probes. - -## `AMBASSADOR_FAST_RECONFIGURE` and `AMBASSADOR_LEGACY_MODE` flags - -`AMBASSADOR_FAST_RECONFIGURE` is a feature flag that enables a higher performance implementation of -the code $productName$ uses to validate and generate envoy configuration. It will eventually be enabled -by default, but if you are experiencing performance problems you should try setting -`AMBASSADOR_FAST_RECONFIGURE` to `true` to see if this helps. - -`AMBASSADOR_LEGACY_MODE` is **not** recommended when performance is critical. - -## `AMBASSADOR_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. - -## Unconstrained Mappings with many hosts - -When working with a large number of `Host` resources, it's important to understand the impact of -unconstrained `Mapping`s. An unconstrained `Mapping` is one that is not restricted to a specific -`Host`. Such a `Mapping` will create a route for all of your `Host`s. If this is what you want then -it is the appropriate thing to do, however if you do not intend to do this, then you can end up with -many more routes than you had intended and this can adversely impact performance. - -## Inspecting $productName$ performance - -$productName$ internally tracks a number of key performance indicators. You can inspect these via the -debug endpoint at `localhost:8877/debug`. Note that the `AMBASSADOR_FAST_RECONFIGURE` flag needs to -be set to `"true"` for this endpoint to be present: - -``` -$ kubectl exec -n ambassador -it ${POD} curl localhost:8877/debug -{ - "timers": { - # These two timers track how long it takes to respond to liveness and readiness probes. - "check_alive": "7, 45.411495ms/61.85999ms/81.358927ms", - "check_ready": "7, 49.951304ms/61.976205ms/86.279038ms", - - # These two timers track how long we spend updating our in-memory snapshot when our Kubernetes - # watches tell us something has changed. - "consulUpdate": "0, 0s/0s/0s", - "katesUpdate": "3382, 28.662µs/102.784µs/95.220222ms", - - # These timers tell us how long we spend notifying the sidecars if changed input. This - # includes how long the sidecars take to process that input. - "notifyWebhook:diagd": "2, 1.206967947s/1.3298432s/1.452718454s", - "notifyWebhooks": "2, 1.207007216s/1.329901037s/1.452794859s", - - # This timer tells us how long we spend parsing annotations. - "parseAnnotations": "2, 21.944µs/22.541µs/23.138µs", - - # This timer tells us how long we spend reconciling changes to consul inputs. - "reconcileConsul": "2, 50.104µs/55.499µs/60.894µs", - - # This timer tells us how long we spend reconciling secrets related changes to $productName$ - # inputs. - "reconcileSecrets": "2, 18.704µs/20.786µs/22.868µs" - }, - "values": { - "envoyReconfigs": { - "times": [ - "2020-11-06T13:13:24.218707995-05:00", - "2020-11-06T13:13:27.185754494-05:00", - "2020-11-06T13:13:28.612279777-05:00" - ], - "staleCount": 2, - "staleMax": 0, - "synced": true - }, - "memory": "39.73Gi of Unlimited (0%)" - } -} -``` - -## Running profiles - -$productName$ exposes endpoints at `localhost:8877/debug/pprof` to run Golang profiles to aid in live debugging. The endpoints are equivalent to those found in the [http/pprof](https://pkg.go.dev/net/http/pprof) package. `/debug/pprof/` returns an HTML page listing the available profiles. - -The following are the different types of profiles you can run: - -| Profile | Function | -| :------- | :-------- | -| /debug/pprof/allocs | Returns a sampling of all past memory allocations. | -| /debug/pprof/block | Returns stack traces of goroutines that led to blocking on sychronization primitives. | -| /debug/pprof/cmdline | Returns the command line that was invoked by the current program. | -| /debug/pprof/goroutine | Returns stack traces of all current goroutines. | -| /debug/pprof/heap | Returns a sampling of memory allocations of live objects. | -| /debug/pprof/mutex | Returns stack traces of goroutines holding contended mutexes. | -| /debug/pprof/profile | Returns pprof-formatted cpu profile. You can specify the duration using the seconds `GET` parameter. The default duration is 30 seconds. | -| /debug/pprof/symbol | Returns the program counters listed in the request. | -| /debug/pprof/threadcreate | Returns stack traces that led to creation of new OS threads. | -| /debug/pprof/trace | Returns the execution trace in binary form. You can specify the duration using the seconds `GET` parameter. The default duration is 1 second. | diff --git a/content/en/docs/3.1/topics/running/services/auth-service.md b/content/en/docs/3.1/topics/running/services/auth-service.md deleted file mode 100644 index cb598161..00000000 --- a/content/en/docs/3.1/topics/running/services/auth-service.md +++ /dev/null @@ -1,150 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Authentication service - -$productName$ provides a highly flexible mechanism for authentication, -via the `AuthService` resource. An `AuthService` configures -$productName$ to use an external service to check authentication and -authorization for incoming requests. Each incoming request is -authenticated before routing to its destination. - -All requests are validated by the `AuthService` (unless the `Mapping` -applied to the request sets `bypass_auth`). It is not possible to -combine multiple `AuthServices`. While it is possible to create -multiple `AuthService` resources, $productName$ load-balances between -them in a round-robin fashion. This is useful for canarying an -`AuthService` change, but is not useful for deploying multiple -distinct `AuthServices`. In order to combine multiple external -services (either having multiple services apply to the same request, -or selecting between different services for the different requests), -instead of using an `AuthService`, use an [$AESproductName$ `External` -`Filter`](/docs/edge-stack/latest/topics/using/filters/). - - - -Because of the limitations described above, **$AESproductName$ does -not support `AuthService` resources, and you should instead use an -[`External` -`Filter`](/docs/edge-stack/latest/topics/using/filters/external),** -which is mostly a drop-in replacement for an `AuthService`. The -`External` `Filter` relies on the $AESproductName$ `AuthService`. -Make sure the $AESproductName$ `AuthService` is deployed before -configuring `External` `Filters`. - - - -The currently supported version of the `AuthService` resource is -`getambassador.io/v3alpha1`. Earlier versions are deprecated. - -## Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: AuthService -metadata: - name: authentication -spec: - ambassador_id: [ "ambassador-1" ] - auth_service: "example-auth.authentication:3000" - tls: true - proto: http - timeout_ms: 5000 - include_body: - max_bytes: 4096 - allow_partial: true - status_on_error: - code: 403 - failure_mode_allow: false - - # proto: grpc only, default is v2. If upgrading from 2.x then you must set this to v3. - protocol_version: v3 - - # proto: http only - path_prefix: "/path" - allowed_request_headers: - - "x-example-header" - allowed_authorization_headers: - - "x-qotm-session" - add_auth_headers: - x-added-auth: auth-added - add_linkerd_headers: false -``` - -## Fields - -`auth_service` is the only required field, all others are optional. - -| Attribute | Default value | Description | -| ---------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `ambassador_id` | `[ "default" ]` | Which [Ambassador ID](../../running/#ambassador_id) the `AuthService` should apply to. | -| `auth_service` | (none; a value is required) | Identifies the external auth service to talk to. The format of this field is `scheme://host:port` where `scheme://` and `:port` are optional. The scheme-part, if present, must be either `http://` or `https://`; if the scheme-part is not present, it behaves as if `http://` is given. The scheme-part controls whether TLS or plaintext is used and influences the default value of the port-part. The host-part must be the [namespace-qualified DNS name](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#namespaces-of-services) of the service you want to use for authentication. | -| `tls` | `""` | This field is populated with the name of the defined TLSContext, which determines the TLS certificate presented to external auth services. | -| `proto` | `http` | Specifies which variant of the [`ext_authz` protocol](../ext_authz/) to use when communicating with the external auth service. Valid options are `http` or `grpc`. | -| `timeout_ms` | `5000` | The total maximum duration in milliseconds for the request to the external auth service, before triggering `status_on_error` or `failure_mode_allow`. | -| `include_body` | `null` | Controls how much to buffer the request body to pass to the external auth service, for use cases such as computing an HMAC or request signature. If `include_body` is `null` or unset, then the request body is not buffered at all, and an empty body is passed to the external auth service. If `include_body` is not `null`, the `max_bytes` and `allow_partial` subfields are required. | -| `include_body.max_bytes` | (none; a value is required if `include_body` is not `null`) | Controls the amount of body data that is passed to the external auth service. | -| `include_body.allow_partial` | (none; a value is required if `include_body` is not `null`) | Controls what happens to requests with bodies larger than `max_bytes`. If `allow_partial` is `true`, the first `max_bytes` of the body are sent to the external auth service. If `false`, the message is rejected with HTTP 413 ("Payload Too Large"). | -| `status_on_error.code` | `403` | Controls the status code returned when unable to communicate with external auth service. This is ignored if `failure_mode_allow: true`. | -| `failure_mode_allow` | `false` | Controls whether to allow or reject requests when there is an error communicating with the external auth service; a value of `true` allows the request through to the upstream backend service, a value of `false` returns a `status_on_error.code` response to the client. | -| `stats_name` | the `auth_service` value with non-alphanumeric characters replaced with underscores | See [Overriding Statistics Names](../../statistics/#overriding-statistics-names). | -| `circuit_breakers` | the value set in the [`ambassador` `Module`](../../../using/defaults) | See [Circuit Breakers](../../../using/circuit-breakers/). | - -The following field is only used if `proto` is set to `grpc`. It is -ignored if `proto` is `http`. - -| Attribute | Default value | Description | -| ------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `protocol_version` | `v3` | Allowed values are `v3` and `v2`(defualt). `protocol_version` was used in previous versions of $productName$ to control the protocol used by the gRPC service. $productName$ 3.x is running an updated version of Envoy that has dropped support for the `v2` protocol, so starting in 3.x, if `protocol_version` is not specified, 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. | - -The following fields are only used if `proto` is set to `http`. They -are ignored if `proto` is `grpc`. - -| Attribute | Default value | Description | -| ------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `path_prefix` | `""` | Prepends a string to the request path of the request when sending it to the external auth service. By default this is empty, and nothing is prepended. For example, if the client makes a request to `/foo`, and `path_prefix: /bar`, then the path in the request made to the external auth service will be `/foo/bar`. | -| `allowed_request_headers` | `[]` | Lists the headers (case-insensitive) that are copied from the incoming request to the request made to the external auth service. In addition to the headers listed in this field, the following headers are always included: `Authorization`, `Cookie`, `From`, `Proxy-Authorization`, `User-Agent`, `X-Forwarded-For`, `X-Forwarded-Host`, and `X-Forwarded-Proto`. | -| `allowed_authorization_headers` | `[]` | Lists the headers (case-insensitive) that are copied from the response from the external auth service to the request sent to the upstream backend service (if the external auth service indicates that the request to the upstream backend service should be allowed). In addition to the headers listed in this field, the following headers are always included: `Authorization`, `Location`, `Proxy-Authenticate`, `Set-cookie`, `WWW-Authenticate` | -| `add_auth_headers` | `{}` | A dictionary of `header: value` pairs that are added to the request made to the external auth service. | -| `add_linkerd_headers` | Defaults to the value set in the [`ambassador` `Module`](../../ambassador) | When true, in the request to the external auth service, adds an `l5d-dst-override` HTTP header that is set to the hostname and port number of the external auth service. | - -## Canarying multiple `AuthServices` - -You may create multiple `AuthService` manifests to round-robin -authentication requests among multiple services. **All services must -use the same `path_prefix` and header definitions.** If you try to -have different values, you'll see an error in the [diagnostics -service](../../ambassador/#diagnostics), telling you which value is -being used. - -## Configuring public `Mappings` - -An `AuthService` can be disabled for a `Mapping` by setting -`bypass_auth` to `true`. This will tell $productName$ to allow all -requests for that `Mapping` through without interacting with the -external auth service. - - - -## Transport Protocol Migration - - -> **Note:** The following information is only applicable to `AuthServices` using `proto: grpc` -As of $productName$ version 2.3, the `v2` transport protocol is deprecated and any AuthServices making use -of it should migrate to `v3` before support for `v2` is removed in a future release. - -The following imports simply need to be updated to migrate an AuthService - -`v2` Imports: -``` - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" -``` - -`v3` Imports: -``` - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" -``` diff --git a/content/en/docs/3.1/topics/running/services/ext_authz.md b/content/en/docs/3.1/topics/running/services/ext_authz.md deleted file mode 100644 index 1a128208..00000000 --- a/content/en/docs/3.1/topics/running/services/ext_authz.md +++ /dev/null @@ -1,84 +0,0 @@ -# ExtAuth protocol - -By design, the ExtAuth protocol used by [the AuthService](../auth-service) and by [External Filters](/docs/edge-stack/latest/topics/using/filters/external) is highly flexible. The authentication service is the first external service invoked on an incoming request (e.g., it runs before the rate limit filter). Because the logic of authentication is encapsulated in an external service, you can use this to support a wide variety of use cases. For example: - -* Supporting traditional SSO authentication protocols, e.g., OAuth, OpenID Connect, etc. -* Supporting HTTP basic authentication ([see a sample implementation](https://github.com/datawire/ambassador-auth-httpbasic)). -* Only authenticating requests that are under a rate limit and rejecting authentication requests above the rate limit. -* Authenticating specific services (URLs), and not others. - -For each request, the ExtAuth service may either: - 1. return a direct HTTP *response*, intended to be sent back to the requesting HTTP client (normally *denying* the request from being forwarded to the upstream backend service) or - 2. return a modification to make to the HTTP *request* before sending it to the upstream backend service (normally *allowing* the request to be forwarded to the upstream backend service with modifications). - -The ExtAuth service receives information about every request through $productName$ and must indicate whether the request is to be allowed or not. If not, the ExtAuth service provides the HTTP response which is to be handed back to the client. A potential control flow for Authentication is shown in the image below. - -Giving the ExtAuth service the ability to control the response allows many different types of auth mechanisms, for example: - -- The ExtAuth service can simply return an error page with an HTTP 401 response. -- The ExtAuth service can choose to include a `WWW-Authenticate` header in the 401 response, to ask the client to perform HTTP Basic Auth. -- The ExtAuth service can issue a 301 `Redirect` to divert the client into an OAuth or OIDC authentication sequence. The control flow of this is shown below. -Authentication flow - -There are two variants of the ExtAuth: gRPC and plain HTTP. - -### The gRPC protocol - -When `proto: grpc` is set, the ExtAuth service must implement the `Authorization` gRPC interface, defined in [Envoy's `external_auth.proto`](https://github.com/emissary-ingress/emissary/blob/master/api/envoy/service/auth/v3/external_auth.proto). - -### The HTTP protocol - -External services for `proto: http` are often easier to implement, but have several limitations compared to `proto: grpc`. - - The list of headers that the ExtAuth service is interested in reading must be known ahead of time, in order to set `allow_request_headers`. Inspecting headers that are not known ahead of time requires instead using `proto: grpc`. - - The list of headers that the ExtAuth service would like to set or modify must be known ahead of time, in order to set `allow_authorization_headers`. Setting headers that are not known ahead of time requires instead using `proto: grpc`. - - When returning a direct HTTP response, the HTTP status code cannot be 200 or in the 5XX range. Intercepting with a 200 or 5XX response requires instead using `proto: grpc`. - -#### The request From $productName$ to the ExtAuth service - -For every incoming request, a similar request is made to the ExtAuth service that mimics the: - - HTTP request method - - HTTP request path, potentially modified by `path_prefix` - - HTTP request headers that are either named in `allowed_request_headers` or in the fixed list of headers that are always included - - first `include_body.max_bytes` of the HTTP request body. - -The `Content-Length` HTTP header is set to the number of bytes in the body of the request sent to the ExtAuth service (`0` if `include_body` is not set). - -**ALL** request methods will be proxied, which implies that the ExtAuth service must be able to handle any request that any client could make. - -Take this incoming request for example: - -``` -PUT /path/to/service HTTP/1.1 -Host: myservice.example.com:8080 -User-Agent: curl/7.54.0 -Accept: */* -Content-Type: application/json -Content-Length: 27 - -{ "greeting": "hello world!", "spiders": "OMG no" } -``` - -The request $productName$ will make of the auth service is: - -``` -PUT /path/to/service HTTP/1.1 -Host: extauth.example.com:8080 -User-Agent: curl/7.54.0 -Accept: */* -Content-Type: application/json -Content-Length: 0 -``` - -#### The response returned from the ExtAuth service to $productName$ - - - If the HTTP response returned from the ExtAuth service to $productName$ has an HTTP status code of 200, then the request is allowed through to the upstream backend service. **Only** 200 indicates this; other 2XX status codes will prevent the request from being allowed through. - - The 200 response should not contain anything in the body, but may contain arbitrary headers. Any header present in the ExtAuth service' response that is also either listed in the `allow_authorization_headers` attribute of the AuthService resource or in the fixed list of headers that are always included will be copied from the ExtAuth service's response into the request going to the upstream backend service. This allows the ExtAuth service to inject tokens or other information into the request, or to modify headers coming from the client. - - The big limitation here is that the list of headers to be set must be known ahead of time, in order to set `allow_request_headers`. Setting headers that are not known ahead of time requires instead using `proto: grpc`. - - - If $productName$ cannot reach the ExtAuth service at all, if the ExtAuth service does not return a valid HTTP response, or if the HTTP response has an HTTP status code in the 5XX range, then the communication with the ExtAuth service is considered to have failed, and the `status_on_error` or `failure_mode_allow` behavior is triggered. - - - Any HTTP status code other than 200 or 5XX from the ExtAuth service tells $productName$ to **not** allow the request to continue to the upstream backend service, but that the ExtAuth service is instead intercepting the request. The entire HTTP response from the ExtAuth service--including the status code, the headers, and the body--is handed back to the client verbatim. This gives the ExtAuth service **complete** control over the entire response presented to the client. - - The big limitation here is that you cannot directly return a 200 or 5XX response. Intercepting with a 200 or 5XX response requires instead using `proto: grpc`. diff --git a/content/en/docs/3.1/topics/running/services/index.md b/content/en/docs/3.1/topics/running/services/index.md deleted file mode 100644 index 1646aa5a..00000000 --- a/content/en/docs/3.1/topics/running/services/index.md +++ /dev/null @@ -1,11 +0,0 @@ -# Available plugins - -You may need an API Gateway to enforce policies specific to your organization. $productName$ supports custom policies through external service plugins. The policy logic specific to your organization is implemented in the external service, and $productName$ is configured to send RPC requests to your service. - -Currently, $productName$ supports plugins for authentication, -access logging, rate limiting, and tracing. - -* [AuthService](auth-service) Plugin -* [LogService](log-service) Plugin -* [RateLimitService](rate-limit-service) Plugin -* [TracingService](tracing-service) Plugin diff --git a/content/en/docs/3.1/topics/running/services/log-service.md b/content/en/docs/3.1/topics/running/services/log-service.md deleted file mode 100644 index b3e90c7c..00000000 --- a/content/en/docs/3.1/topics/running/services/log-service.md +++ /dev/null @@ -1,116 +0,0 @@ -# Log service - -By default, $productName$ puts the access logs on stdout; such -that the can be read using `kubectl logs`. The format of those logs, -and the local destination of them, can be configured using the -[`envoy_log_` settings in the `ambassador -Module`](../../ambassador). However, the -options there only allow for logging local to $productName$'s Pod. By -configuring a `LogService`, you can configure $productName$ to -report its access logs to a remote service, in addition to the usual -`ambassador Module` configured logging. - -The remote access log service (or ALS) must implement the -`AccessLogService` gRPC interface, defined in [Envoy's `als.proto`][als.proto]. - -[als.proto]: https://github.com/emissary-ingress/emissary/blob/master/api/envoy/service/accesslog/v3/als.proto - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: LogService -metadata: - name: example-log-service -spec: - # Common to all $productName$ resources - ambassador_id: []string # optional; default is ["default"] - - # LogService specific - service: "string" # required - driver: "enum-string:[tcp, http]" # required - driver_config: # required - additional_log_headers: # optional; default is [] (only for `driver: http`) - - header_name: string # required - during_request: boolean # optional; default is true - during_response: boolean # optional; default is true - during_trailer: boolean # optional; default is true - flush_interval_time: int-seconds # optional; default is 1 - flush_interval_byte_size: integer # optional; default is 16384 - grpc: boolean # optional; default is false - protocol_version: enum # optional; default is v2 -``` - - - `service` is where to route the access log gRPC requests to - - - `driver` identifies which type of accesses to log; HTTP requests (`"http"`) or - TLS connections (`"tcp"`). - - - `driver_config` stores the configuration that is specific to the `driver`: - - * `driver: tcp` has no additional configuration; the config must - be set as `driver_config: {}`. - - * `driver: http` - - - `additional_log_headers` identifies HTTP headers to include in - the access log, and when in the logged-request's lifecycle to - include them. - - - `flush_interval_time` is the maximum number of seconds to buffer - accesses for before sending them to the ALS. The logs will be - flushed to the ALS every time this duration is reached, or when the - buffered data reaches `flush_interval_byte_size`, whichever comes - first. See the [Envoy documentation on - `buffer_flush_interval`][buffer_flush_interval] for more - information. - - - `flush_interval_byte_size` is a soft size limit for the access log - buffer. The logs will be flushed to the ALS every time the - buffered data reaches this size, or whenever `flush_interval_time` - elapses, whichever comes first. See the [Envoy documentation on - `buffer_size_bytes`][buffer_size_bytes] for more information. - - - `grpc` must be `true`. - -[buffer_flush_interval]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/access_loggers/grpc/v3/als.proto.html#extensions-access-loggers-grpc-v3-commongrpcaccesslogconfig -[buffer_size_bytes]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/access_loggers/grpc/v3/als.proto.html#extensions-access-loggers-grpc-v3-commongrpcaccesslogconfig - - - `protocol_version` was used in previous versions of $productName$ to control the gRPC service name used to communicate with the `LogService`. $productName$ 3.x is running an updated version of Envoy that has dropped support for the `v2` protocol, so starting in 3.x, if `protocol_version` is not specified, 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. - -## Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: LogService -metadata: - name: als -spec: - service: "als.default:3000" - driver: http - driver_config: {} # NB: driver_config must be set, even if it's empty - grpc: true # NB: grpc must be true and it will use the V3 transport protocol -``` - -## Transport Protocol Migration - - -> **Note:** The following information is only applicable to `AuthServices` using `proto: grpc` -As of $productName$ version 2.3, the `v2` transport protocol is deprecated and any AuthServices making use -of it should migrate to `v3` before support for `v2` is removed in a future release. - -The following imports simply need to be updated to migrate an AuthService - -`v2` Imports: -``` - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" -``` - -`v3` Imports: -``` - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" -``` diff --git a/content/en/docs/3.1/topics/running/services/rate-limit-service.md b/content/en/docs/3.1/topics/running/services/rate-limit-service.md deleted file mode 100644 index 8301b862..00000000 --- a/content/en/docs/3.1/topics/running/services/rate-limit-service.md +++ /dev/null @@ -1,116 +0,0 @@ -# Rate limit service - -Rate limiting is a powerful technique to improve the [availability and -resilience of your -services](https://blog.getambassador.io/rate-limiting-a-useful-tool-with-distributed-systems-6be2b1a4f5f4). -In $productName$, each request can have one or more _labels_. These labels are -exposed to a third-party service via a gRPC API. The third-party service can -then rate limit requests based on the request labels. - -**Note that `RateLimitService` is only applicable to $OSSproductName$, -and not $AESproductName$, as $AESproductName$ includes a -built-in rate limit service.** - -## Request labels - -See [Attaching labels to -requests](../../../using/rate-limits#attaching-labels-to-requests) -for how to configure the labels that are attached to a request. - -## Domains - -In $productName$, each engineer (or team) can be assigned its own _domain_. A -domain is a separate namespace for labels. By creating individual domains, each -team can assign their own labels to a given request, and independently set the -rate limits based on their own labels. - -See [Attaching labels to -requests](../../../using/rate-limits/#attaching-labels-to-requests) -for how to labels under different domains. - -## External rate limit service - -In order for $productName$ to rate limit, you need to implement a -gRPC `RateLimitService`, as defined in [Envoy's `v3/rls.proto`] -interface. If you do not have the time or resources to implement your own rate -limit service, $AESproductName$ integrates a high-performance rate -limiting service. - -[envoy's `v3/rls.proto`]: https://github.com/emissary-ingress/emissary/tree/master/api/envoy/service/ratelimit/v3/rls.proto - -$productName$ generates a gRPC request to the external rate limit -service and provides a list of labels on which the rate limit service can base -its decision to accept or reject the request: - -``` -[ - {"source_cluster", ""}, - {"destination_cluster", ""}, - {"remote_address", ""}, - {"generic_key", ""}, - {"", ""} -] -``` - -If $productName$ cannot contact the rate limit service, it will -allow the request to be processed as if there were no rate limit service -configuration. - -It is the external rate limit service's responsibility to determine whether rate -limiting should take place, depending on custom business logic. The rate limit -service must simply respond to the request with an `OK` or `OVER_LIMIT` code: - -- If Envoy receives an `OK` response from the rate limit service, then $productName$ allows the client request to resume being processed by - the normal flow. -- If Envoy receives an `OVER_LIMIT` response, then $productName$ - will return an HTTP 429 response to the client and will end the transaction - flow, preventing the request from reaching the backing service. - -The headers injected by the [AuthService](../auth-service) can also be passed to -the rate limit service since the `AuthService` is invoked before the -`RateLimitService`. - -## Configuring the rate limit service - -A `RateLimitService` manifest configures $productName$ to use an -external service to check and enforce rate limits for incoming requests: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: RateLimitService -metadata: - name: ratelimit -spec: - service: 'example-rate-limit.default:5000' - protocol_version: # default is v2, if upgrading from 2.x then you must set this to v3. -``` - -- `service` gives the URL of the rate limit service. If using a Kubernetes service, this should be the [namespace-qualified DNS name](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#namespaces-of-services) of that service. -- `protocol_version` Allowed values are `v3` and `v2`(defualt). `protocol_version` was used in previous versions of $productName$ to control the protocol used by the gRPC service to communicate with the `RateLimitService`. $productName$ 3.x is running an updated version of Envoy that has dropped support for the `v2` protocol, so starting in 3.x, if `protocol_version` is not specified, 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. - -You may only use a single `RateLimitService` manifest. - -## Rate limit service and TLS - -You can tell $productName$ to use TLS to talk to your service by -using a `RateLimitService` with an `https://` prefix. However, you may also -provide a `tls` attribute: if `tls` is present and `true`, $productName$ will originate TLS even if the `service` does not have the `https://` -prefix. - -If `tls` is present with a value that is not `true`, the value is assumed to be the name of a defined TLS context, which will determine the certificate presented to the upstream service. - -## Example - -The [$OSSproductName$ Rate Limiting -Tutorial](../../../../howtos/rate-limiting-tutorial) has a simple rate limiting -example. For a more advanced example, read the [advanced rate limiting -tutorial](../../../../../2.0/howtos/advanced-rate-limiting), which uses the rate limit -service that is integrated with $AESproductName$. - -## Further reading - -- [Rate limiting: a useful tool with distributed systems](https://blog.getambassador.io/rate-limiting-a-useful-tool-with-distributed-systems-6be2b1a4f5f4) -- [Rate limiting for API Gateways](https://blog.getambassador.io/rate-limiting-for-api-gateways-892310a2da02) -- [Implementing a Java Rate Limiting Service for $productName$](https://blog.getambassador.io/implementing-a-java-rate-limiting-service-for-the-ambassador-api-gateway-e09d542455da) -- [Designing a Rate Limit Service for $productName$](https://blog.getambassador.io/designing-a-rate-limiting-service-for-ambassador-f460e9fabedb) diff --git a/content/en/docs/3.1/topics/running/services/tracing-service.md b/content/en/docs/3.1/topics/running/services/tracing-service.md deleted file mode 100644 index 044f4f4c..00000000 --- a/content/en/docs/3.1/topics/running/services/tracing-service.md +++ /dev/null @@ -1,69 +0,0 @@ -# Tracing service - -Applications that consist of multiple services can be difficult to debug, as a single request can span multiple services. Distributed tracing tells the story of your request as it is processed through your system. Distributed tracing is a powerful tool to debug and analyze your system in addition to request logging and metrics. - -When enabled, the `TracingService` will instruct $productName$ to initiate a trace on requests by generating and populating an `x-request-id` HTTP header. Services can make use of this `x-request-id` header in logging and forward it in downstream requests for tracing. $productName$ also integrates with external trace visualization services, including [LightStep](https://lightstep.com/) and Zipkin-compatible APIs such as [Zipkin](https://zipkin.io/) and [Jaeger](https://github.com/jaegertracing/) to allow you to store and visualize traces. You can read further on [Envoy's Tracing capabilities](https://www.envoyproxy.io/docs/envoy/v1.10.0/intro/arch_overview/tracing). - -A `TracingService` manifest configures $productName$ to use an external trace visualization service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TracingService -metadata: - name: tracing -spec: - service: "example-zipkin:9411" - driver: zipkin - config: {} - tag_headers: - - ":authority" - - ":path" - sampling: - overall: 100 -``` - -- `service` gives the URL of the external HTTP trace service. -- `driver` provides the driver information that handles communicating with the `service`. Supported values are `lightstep`, `zipkin`, and `datadog`. -- `config` provides additional configuration options for the selected `driver`. -- `tag_headers` (optional) if present, specifies a list of other HTTP request headers which will be used as tags in the trace's span. -- `propagation_modes` (optional) if present, specifies a list of the propogation modes to be used. Possible values: - - `ENVOY` - - `LIGHTSTEP` - - `B3` - - `TRACE_CONTEXT` -- `sampling` (optional) if present, specifies some target percentages of requests that will be traced. - - `client`: percentage of requests that will be force traced if the `x-client-trace-id` header is set. Defaults to 100. - - `random`: percentage of requests that will be randomly traced. Defaults to 100. - - `overall`: percentage of requests that will be traced after all other checks have been applied (force tracing, sampling, etc.). - This field functions as an upper limit on the total configured sampling rate. For instance, setting `client` - to `100%` but `overall` to `1%` will result in only `1%` of client requests with the appropriate headers to be force - traced. Defaults to 100. - - -Please note that you must use the HTTP/2 pseudo-header names. For example: - -- the `host` header should be specified as the `:authority` header; and -- the `method` header should be specified as the `:method` header. - -### Lightstep driver configurations - -- `access_token_file` provides the location of the file containing the access token to the LightStep API. - -### Zipkin driver configurations - -- `collector_endpoint` gives the API endpoint of the Zipkin service where the spans will be sent. The default value is `/api/v2/spans` -- `collector_endpoint_version` gives the transport version used when sending data to your Zipkin collector. The default value is `HTTP_JSON` and it must be one of `HTTP_JSON` or `HTTP_PROTO`. -- `collector_endpoint_hostname` sets the hostname Envoy will use when sending data to your Zipkin collector. The default value is the name of the underlying Envoy cluster. -- `trace_id_128bit` whether a 128-bit `trace id` will be used when creating a new trace instance. Defaults to `true`. Setting to `false` will result in a 64-bit trace id being used. -- `shared_span_context` whether client and server spans will share the same `span id`. The default value is `true`. - -### Datadog Driver Configurations - -- `service_name` the name of the service which is attached to the traces. The default value is `ambassador`. - -You may only use a single `TracingService` manifest per $productName$ deployment. Ensure [ambassador_id](../../running#ambassador_id) is set correctly in the `TracingService` manifest. - -## Example - -Check out the [DataDog](../../../../howtos/tracing-datadog) and [Zipkin](../../../../howtos/tracing-zipkin) HOWTOs. diff --git a/content/en/docs/3.1/topics/running/statistics/8877-metrics-grafana.json b/content/en/docs/3.1/topics/running/statistics/8877-metrics-grafana.json deleted file mode 100644 index b2b19b37..00000000 --- a/content/en/docs/3.1/topics/running/statistics/8877-metrics-grafana.json +++ /dev/null @@ -1,943 +0,0 @@ -{ - "annotations": { - "list": [ - { - "builtIn": 1, - "datasource": "Prometheus", - "enable": true, - "hide": true, - "iconColor": "rgba(0, 211, 255, 1)", - "name": "Annotations & Alerts", - "type": "dashboard" - } - ] - }, - "description": "Ambassador dashboard for Prometheus", - "editable": true, - "gnetId": 4698, - "graphTooltip": 0, - "id": 1, - "iteration": 1595611060519, - "links": [], - "panels": [ - { - "collapsed": false, - "datasource": null, - "gridPos": { - "h": 1, - "w": 24, - "x": 0, - "y": 0 - }, - "id": 34, - "panels": [], - "title": "Ambassador - Control Plane", - "type": "row" - }, - { - "cacheTimeout": null, - "colorBackground": false, - "colorValue": false, - "colors": [ - "#299c46", - "rgba(237, 129, 40, 0.89)", - "#d44a3a" - ], - "datasource": null, - "format": "none", - "gauge": { - "maxValue": 100, - "minValue": 0, - "show": false, - "thresholdLabels": false, - "thresholdMarkers": true - }, - "gridPos": { - "h": 5, - "w": 5, - "x": 0, - "y": 1 - }, - "id": 36, - "interval": "", - "links": [], - "mappingType": 1, - "mappingTypes": [ - { - "name": "value to text", - "value": 1 - }, - { - "name": "range to text", - "value": 2 - } - ], - "maxDataPoints": 100, - "maxPerRow": 3, - "nullPointMode": "connected", - "nullText": null, - "options": {}, - "postfix": "", - "postfixFontSize": "50%", - "prefix": "", - "prefixFontSize": "50%", - "rangeMaps": [ - { - "from": "null", - "text": "N/A", - "to": "null" - } - ], - "repeat": null, - "repeatDirection": "h", - "sparkline": { - "fillColor": "rgba(31, 118, 189, 0.18)", - "full": false, - "lineColor": "rgb(31, 120, 193)", - "show": false, - "ymax": null, - "ymin": null - }, - "tableColumn": "", - "targets": [ - { - "expr": "ambassador_diagnostics_info{namespace=~\"$namespace\"}", - "format": "time_series", - "hide": false, - "instant": true, - "intervalFactor": 1, - "legendFormat": "{{version}}", - "refId": "A" - } - ], - "thresholds": "", - "timeFrom": null, - "timeShift": null, - "title": "Version", - "type": "singlestat", - "valueFontSize": "80%", - "valueMaps": [], - "valueName": "name" - }, - { - "cacheTimeout": null, - "datasource": null, - "gridPos": { - "h": 5, - "w": 19, - "x": 5, - "y": 1 - }, - "id": 42, - "links": [], - "options": { - "displayMode": "lcd", - "fieldOptions": { - "calcs": [ - "lastNotNull" - ], - "defaults": { - "mappings": [], - "max": 2.5, - "min": 0, - "nullValueMode": "connected", - "thresholds": [ - { - "color": "green", - "value": null - }, - { - "color": "#EAB839", - "value": 1 - }, - { - "color": "red", - "value": 2 - } - ], - "title": "", - "unit": "s" - }, - "override": {}, - "values": false - }, - "orientation": "vertical" - }, - "pluginVersion": "6.4.3", - "repeat": "pod", - "repeatDirection": "v", - "scopedVars": { - "pod": { - "selected": false, - "text": "ambassador-x", - "value": "ambassador-x" - } - }, - "targets": [ - { - "expr": "ambassador_reconfiguration_time_seconds{namespace=~\"$namespace\", pod=~\"$pod\"}", - "instant": false, - "legendFormat": "Reconfiguration", - "refId": "C" - }, - { - "expr": "ambassador_fetcher_time_seconds{namespace=~\"$namespace\", pod=~\"$pod\"}", - "instant": false, - "legendFormat": "Fetcher", - "refId": "E" - }, - { - "expr": "ambassador_aconf_time_seconds{namespace=~\"$namespace\", pod=~\"$pod\"}", - "instant": false, - "legendFormat": "AConf", - "refId": "A" - }, - { - "expr": "ambassador_ir_time_seconds{namespace=~\"$namespace\", pod=~\"$pod\"}", - "instant": false, - "legendFormat": "IR", - "refId": "F" - }, - { - "expr": "ambassador_econf_time_seconds{namespace=~\"$namespace\", pod=~\"$pod\"}", - "instant": false, - "legendFormat": "EConf", - "refId": "B" - }, - { - "expr": "ambassador_diagnostics_time_seconds{namespace=~\"$namespace\", pod=~\"$pod\"}", - "instant": false, - "legendFormat": "Diagnostics", - "refId": "D" - } - ], - "timeFrom": null, - "timeShift": null, - "title": "Last control plane operation time ($pod)", - "type": "bargauge" - }, - { - "collapsed": true, - "datasource": null, - "gridPos": { - "h": 1, - "w": 24, - "x": 0, - "y": 6 - }, - "id": 38, - "panels": [ - { - "aliasColors": {}, - "bars": false, - "dashLength": 10, - "dashes": false, - "datasource": null, - "fill": 1, - "fillGradient": 0, - "gridPos": { - "h": 7, - "w": 24, - "x": 0, - "y": 2 - }, - "id": 40, - "legend": { - "avg": false, - "current": false, - "max": false, - "min": false, - "show": true, - "total": false, - "values": false - }, - "lines": true, - "linewidth": 1, - "nullPointMode": "null", - "options": { - "dataLinks": [] - }, - "percentage": false, - "pointradius": 2, - "points": false, - "renderer": "flot", - "seriesOverrides": [], - "spaceLength": 10, - "stack": false, - "steppedLine": false, - "targets": [ - { - "expr": " ambassador_edge_stack_go_memstats_alloc_bytes{namespace=~\"$namespace\", pod=~\"$pod\"}", - "legendFormat": "{{pod}}", - "refId": "A" - } - ], - "thresholds": [], - "timeFrom": null, - "timeRegions": [], - "timeShift": null, - "title": "amb-sidecar memory usage", - "tooltip": { - "shared": true, - "sort": 0, - "value_type": "individual" - }, - "type": "graph", - "xaxis": { - "buckets": null, - "mode": "time", - "name": null, - "show": true, - "values": [] - }, - "yaxes": [ - { - "format": "decbytes", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": true - }, - { - "format": "none", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": false - } - ], - "yaxis": { - "align": false, - "alignLevel": null - } - } - ], - "title": "Ambassador", - "type": "row" - }, - { - "collapsed": false, - "datasource": null, - "gridPos": { - "h": 1, - "w": 24, - "x": 0, - "y": 7 - }, - "id": 22, - "panels": [], - "repeat": null, - "title": "Ambassador - Envoy Data Plane", - "type": "row" - }, - { - "aliasColors": {}, - "bars": false, - "dashLength": 10, - "dashes": false, - "datasource": null, - "fill": 1, - "fillGradient": 0, - "gridPos": { - "h": 8, - "w": 24, - "x": 0, - "y": 8 - }, - "id": 30, - "legend": { - "avg": false, - "current": false, - "max": false, - "min": false, - "show": true, - "total": false, - "values": false - }, - "lines": true, - "linewidth": 1, - "links": [], - "nullPointMode": "null", - "options": { - "dataLinks": [] - }, - "percentage": false, - "pointradius": 2, - "points": false, - "renderer": "flot", - "seriesOverrides": [], - "spaceLength": 10, - "stack": false, - "steppedLine": false, - "targets": [ - { - "expr": "sum(increase(envoy_http_downstream_rq_xx{envoy_response_code_class=\"2\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "2xx", - "refId": "A" - }, - { - "expr": "sum(increase(envoy_http_downstream_rq_xx{envoy_response_code_class=\"3\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "3xx", - "refId": "B" - }, - { - "expr": "sum(increase(envoy_http_downstream_rq_xx{envoy_response_code_class=\"4\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "4xx", - "refId": "C" - }, - { - "expr": "sum(increase(envoy_http_downstream_rq_xx{envoy_response_code_class=\"5\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "5xx", - "refId": "D" - } - ], - "thresholds": [], - "timeFrom": null, - "timeRegions": [], - "timeShift": null, - "title": "Ambassador Response Codes", - "tooltip": { - "shared": true, - "sort": 0, - "value_type": "individual" - }, - "type": "graph", - "xaxis": { - "buckets": null, - "mode": "time", - "name": null, - "show": true, - "values": [] - }, - "yaxes": [ - { - "format": "short", - "label": "RPM", - "logBase": 1, - "max": null, - "min": null, - "show": true - }, - { - "format": "short", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": true - } - ], - "yaxis": { - "align": false, - "alignLevel": null - } - }, - { - "aliasColors": {}, - "bars": false, - "dashLength": 10, - "dashes": false, - "datasource": null, - "fill": 1, - "fillGradient": 0, - "gridPos": { - "h": 8, - "w": 24, - "x": 0, - "y": 16 - }, - "id": 20, - "legend": { - "avg": false, - "current": false, - "max": false, - "min": false, - "show": true, - "total": false, - "values": false - }, - "lines": true, - "linewidth": 1, - "links": [], - "nullPointMode": "null", - "options": { - "dataLinks": [] - }, - "percentage": false, - "pointradius": 2, - "points": false, - "renderer": "flot", - "seriesOverrides": [], - "spaceLength": 10, - "stack": false, - "steppedLine": false, - "targets": [ - { - "expr": "sum(increase(envoy_cluster_upstream_rq_xx{envoy_response_code_class=\"2\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "2xx", - "refId": "A" - }, - { - "expr": "sum(increase(envoy_cluster_upstream_rq_xx{envoy_response_code_class=\"3\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "3xx", - "refId": "B" - }, - { - "expr": "sum(increase(envoy_cluster_upstream_rq_xx{envoy_response_code_class=\"4\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "4xx", - "refId": "C" - }, - { - "expr": "sum(increase(envoy_cluster_upstream_rq_xx{envoy_response_code_class=\"5\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "5xx", - "refId": "D" - } - ], - "thresholds": [], - "timeFrom": null, - "timeRegions": [], - "timeShift": null, - "title": "API Response Codes", - "tooltip": { - "shared": true, - "sort": 0, - "value_type": "individual" - }, - "type": "graph", - "xaxis": { - "buckets": null, - "mode": "time", - "name": null, - "show": true, - "values": [] - }, - "yaxes": [ - { - "format": "short", - "label": "RPM", - "logBase": 1, - "max": null, - "min": null, - "show": true - }, - { - "format": "short", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": true - } - ], - "yaxis": { - "align": false, - "alignLevel": null - } - }, - { - "aliasColors": {}, - "bars": false, - "dashLength": 10, - "dashes": false, - "datasource": null, - "fill": 1, - "fillGradient": 0, - "gridPos": { - "h": 8, - "w": 24, - "x": 0, - "y": 24 - }, - "id": 26, - "legend": { - "avg": false, - "current": false, - "max": false, - "min": false, - "show": true, - "total": false, - "values": false - }, - "lines": true, - "linewidth": 1, - "links": [], - "nullPointMode": "null", - "options": { - "dataLinks": [] - }, - "percentage": false, - "pointradius": 2, - "points": false, - "renderer": "flot", - "seriesOverrides": [], - "spaceLength": 10, - "stack": false, - "steppedLine": false, - "targets": [ - { - "expr": "histogram_quantile(0.95, sum(rate(envoy_http_downstream_cx_length_ms_bucket[5m])) by (le))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "95 percentile", - "refId": "A" - }, - { - "expr": "histogram_quantile(0.9, sum(rate(envoy_http_downstream_cx_length_ms_bucket[5m])) by (le))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "90th percentile", - "refId": "B" - }, - { - "expr": "histogram_quantile(0.5, sum(rate(envoy_http_downstream_cx_length_ms_bucket[5m])) by (le))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "50th percentile", - "refId": "C" - } - ], - "thresholds": [], - "timeFrom": null, - "timeRegions": [], - "timeShift": null, - "title": "Downstream Connections Length", - "tooltip": { - "shared": true, - "sort": 0, - "value_type": "individual" - }, - "type": "graph", - "xaxis": { - "buckets": null, - "mode": "time", - "name": null, - "show": true, - "values": [] - }, - "yaxes": [ - { - "format": "short", - "label": "Milliseconds", - "logBase": 1, - "max": null, - "min": null, - "show": true - }, - { - "format": "short", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": true - } - ], - "yaxis": { - "align": false, - "alignLevel": null - } - }, - { - "aliasColors": {}, - "bars": false, - "dashLength": 10, - "dashes": false, - "datasource": null, - "fill": 1, - "fillGradient": 0, - "gridPos": { - "h": 8, - "w": 18, - "x": 0, - "y": 32 - }, - "id": 28, - "legend": { - "avg": false, - "current": false, - "max": false, - "min": false, - "show": true, - "total": false, - "values": false - }, - "lines": true, - "linewidth": 1, - "links": [], - "nullPointMode": "null", - "options": { - "dataLinks": [] - }, - "percentage": false, - "pointradius": 2, - "points": false, - "renderer": "flot", - "seriesOverrides": [], - "spaceLength": 10, - "stack": false, - "steppedLine": false, - "targets": [ - { - "expr": "sum(increase(envoy_http_downstream_cx_http1_active[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "HTTP/1", - "refId": "A" - }, - { - "expr": "sum(increase(envoy_http_downstream_cx_http2_active_active[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "HTTP/2", - "refId": "B" - }, - { - "expr": "sum(increase(envoy_http_downstream_cx_upgrades_active[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "Websocket", - "refId": "C" - } - ], - "thresholds": [], - "timeFrom": null, - "timeRegions": [], - "timeShift": null, - "title": "Active Connections", - "tooltip": { - "shared": true, - "sort": 0, - "value_type": "individual" - }, - "type": "graph", - "xaxis": { - "buckets": null, - "mode": "time", - "name": null, - "show": true, - "values": [] - }, - "yaxes": [ - { - "format": "short", - "label": "RPM", - "logBase": 1, - "max": null, - "min": null, - "show": true - }, - { - "format": "short", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": true - } - ], - "yaxis": { - "align": false, - "alignLevel": null - } - }, - { - "cacheTimeout": null, - "colorBackground": false, - "colorValue": false, - "colors": [ - "#299c46", - "rgba(237, 129, 40, 0.89)", - "#d44a3a" - ], - "datasource": null, - "format": "none", - "gauge": { - "maxValue": 100, - "minValue": 0, - "show": false, - "thresholdLabels": false, - "thresholdMarkers": true - }, - "gridPos": { - "h": 8, - "w": 6, - "x": 18, - "y": 32 - }, - "id": 32, - "interval": null, - "links": [], - "mappingType": 1, - "mappingTypes": [ - { - "name": "value to text", - "value": 1 - }, - { - "name": "range to text", - "value": 2 - } - ], - "maxDataPoints": 100, - "nullPointMode": "connected", - "nullText": null, - "options": {}, - "postfix": "", - "postfixFontSize": "50%", - "prefix": "", - "prefixFontSize": "50%", - "rangeMaps": [ - { - "from": "null", - "text": "N/A", - "to": "null" - } - ], - "sparkline": { - "fillColor": "rgba(31, 118, 189, 0.18)", - "full": false, - "lineColor": "rgb(31, 120, 193)", - "show": false - }, - "tableColumn": "", - "targets": [ - { - "expr": "avg(envoy_cluster_manager_active_clusters)", - "format": "time_series", - "intervalFactor": 1, - "refId": "A" - } - ], - "thresholds": "", - "timeFrom": null, - "timeShift": null, - "title": "Registered Services", - "type": "singlestat", - "valueFontSize": "80%", - "valueMaps": [ - { - "op": "=", - "text": "N/A", - "value": "null" - } - ], - "valueName": "avg" - } - ], - "refresh": "5s", - "schemaVersion": 20, - "style": "dark", - "tags": [ - "ambassador" - ], - "templating": { - "list": [ - { - "allValue": null, - "current": { - "text": "All", - "value": [ - "$__all" - ] - }, - "datasource": "Prometheus", - "definition": "label_values(ambassador_diagnostics_info, namespace)", - "hide": 0, - "includeAll": true, - "label": "Namespace", - "multi": true, - "name": "namespace", - "options": [], - "query": "label_values(ambassador_diagnostics_info, namespace)", - "refresh": 1, - "regex": "", - "skipUrlSync": false, - "sort": 5, - "tagValuesQuery": "", - "tags": [], - "tagsQuery": "", - "type": "query", - "useTags": false - }, - { - "allValue": null, - "current": { - "tags": [], - "text": "All", - "value": [ - "$__all" - ] - }, - "datasource": "Prometheus", - "definition": "label_values(ambassador_diagnostics_info{namespace=\"$namespace\"}, pod)", - "hide": 0, - "includeAll": true, - "label": "Pod", - "multi": true, - "name": "pod", - "options": [], - "query": "label_values(ambassador_diagnostics_info{namespace=\"$namespace\"}, pod)", - "refresh": 1, - "regex": "", - "skipUrlSync": false, - "sort": 5, - "tagValuesQuery": "", - "tags": [], - "tagsQuery": "", - "type": "query", - "useTags": false - } - ] - }, - "time": { - "from": "now-15m", - "to": "now" - }, - "timepicker": { - "refresh_intervals": [ - "5s", - "10s", - "30s", - "1m", - "5m", - "15m", - "30m", - "1h", - "2h", - "1d" - ], - "time_options": [ - "5m", - "15m", - "1h", - "6h", - "12h", - "24h", - "2d", - "7d", - "30d" - ] - }, - "timezone": "", - "title": "Ambassador", - "uid": "AJieHz4Mz", - "version": 16 -} diff --git a/content/en/docs/3.1/topics/running/statistics/8877-metrics.md b/content/en/docs/3.1/topics/running/statistics/8877-metrics.md deleted file mode 100644 index 770b07de..00000000 --- a/content/en/docs/3.1/topics/running/statistics/8877-metrics.md +++ /dev/null @@ -1,79 +0,0 @@ -# The metrics endpoint - -> For an overview of other options for gathering statistics on -> $productName$, see the [Statistics and Monitoring](../) overview. - -Each $productName$ pod exposes statistics and metrics for that pod at -`http://{POD}:8877/metrics`. The response is in the text-based -Prometheus [exposition format][]. - -[exposition format]: https://prometheus.io/docs/instrumenting/exposition_formats/ - -## Understanding the statistics - -The Prometheus exposition format includes special "HELP" lines that -make the file self-documenting as to what specific statistics mean. - - - -- `envoy_*`: See the [Envoy documentation][`GET /stats/prometheus`]. -- `ambassador_*` (new in 1.7.0): - - `ambassador_edge_stack_*` (not present in $OSSproductName$): - - `ambassador_edge_stack_go_*`: See [`promethus.NewGoCollector()`][]. - - `ambassador_edge_stack_promhttp_*` See [`promhttp.Handler()`][]. - - `ambassador_edge_stack_process_*`: See [`promethus.NewProcessCollector()`][].. - - `ambassador_*_time_seconds` (for `*` = one of `aconf`, `diagnostics`, `econf`, `fetcher`, `ir`, or `reconfiguration`): - Gauges of how long the various core operations take in the diagd - process. - - `ambassador_diagnostics_(errors|notices)`: The number of - diagnostics errors and notices that would be shown in the - diagnostics UI or the Edge Policy Console. - - `ambassador_diagnostics_info`: [Info][`prometheus_client.Info`] - about the $productName$ install; all information is presented in - labels; the value of the Gauge is always "1". - - `ambassador_process_*`: See [`prometheus_client.ProcessCollector`][]. - -[`GET /stats/prometheus`]: https://www.envoyproxy.io/docs/envoy/v1.15.0/operations/admin.html#get--stats-prometheus -[`prometheus.NewProcessCollector`]: https://godoc.org/github.com/prometheus/client_golang/prometheus#NewProcessCollector -[`prometheus.NewGoCollector`]: https://godoc.org/github.com/prometheus/client_golang/prometheus#NewGoCollector -[`promhttp.Handler()`]: https://godoc.org/github.com/prometheus/client_golang/prometheus/promhttp#Handler -[`prometheus_client.Info`]: https://github.com/prometheus/client_python#info -[`prometheus_client.ProcessCollector`]: https://github.com/prometheus/client_python#process-collector - -## Polling the `:8877/metrics` endpoint with Prometheus - -To scrape metrics directly, follow the instructions for [Monitoring -with Prometheus and Grafana](../../../../howtos/prometheus). - -### Using Grafana to visualize statistics gathered by Prometheus - -#### Sample dashboard - -We provide a [sample Grafana dashboard](https://grafana.com/dashboards/13758) -that displays information collected by Prometheus from the -`:8877/metrics` endpoint. - - -#### Just Envoy information -
-Screenshot of a Grafana dashboard that displays just information from Envoy - -[Alex Gervais][] has written a template [$productName$ dashboard for -Grafana][] that displays information collected by Prometheus either -from the `:8877/metrics` endpoint, or from [Envoy over -StatsD][envoy-statsd-prometheus]. Because it is designed to work with -the Envoy StatsD set up, it does not include any of the `ambassador_*` -statistics; because of this, we recommend using the other sample -dashboard above. - -[Alex Gervais]: https://twitter.com/alex_gervais -[$productName$ dashboard for Grafana]: https://grafana.com/dashboards/4698 -[envoy-statsd-prometheus]: ../envoy-statsd#using-prometheus-statsd-exporter-as-the-statsd-sink diff --git a/content/en/docs/3.1/topics/running/statistics/envoy-statsd.md b/content/en/docs/3.1/topics/running/statistics/envoy-statsd.md deleted file mode 100644 index 70795b50..00000000 --- a/content/en/docs/3.1/topics/running/statistics/envoy-statsd.md +++ /dev/null @@ -1,254 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Envoy statistics with StatsD - -> For an overview of other options for gathering statistics on -> $productName$, see the [Statistics and Monitoring](../) overview. - -At the core of $productName$ is [Envoy Proxy], which has built-in -support for exporting a multitude of statistics about its own -operations to StatsD (or to the modified DogStatsD used by Datadog). - -[Envoy Proxy]: https://www.envoyproxy.io - -If enabled, then $productName$ has Envoy expose this 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: - -```diff - spec: - containers: - - env: -+ - name: STATSD_ENABLED -+ value: "true" - - name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: -``` - -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. - -We have included a few example configurations in the -[`statsd-sink/`] directory to help you get started. Clone the -repository to get local, editable copies. - -[`statsd-sink/`]: https://github.com/emissary-ingress/emissary/tree/master/deployments/statsd-sink - -## Using Graphite as the StatsD sink - -[Graphite] is a web-based real-time graphing system. Spin up an -example Graphite setup: - -[Graphite]: http://graphite.readthedocs.org/ - -``` -kubectl apply -f statsd-sink/graphite/graphite-statsd-sink.yaml -``` - -This sets up the `statsd-sink` service and a deployment that contains -Graphite and its related infrastructure. Graphite's web interface is -available at `http://statsd-sink/` from within the cluster. Use port -forwarding to access the interface from your local machine: - -``` -SINKPOD=$(kubectl get pod -l service=statsd-sink -o jsonpath="{.items[0].metadata.name}") -kubectl port-forward $SINKPOD 8080:80 -``` - -This sets up Graphite access at `http://localhost:8080/`. - -## Using Prometheus StatsD Exporter as the StatsD sink - - - $productName$ $version$ has an endpoint that has exposes statistics in - a format that Prometheus understands natively. If you're using Prometheus, - we recommend configuring Prometheus to talk to  - the :8877/metrics endpoint  - directly, instead of instead of going through StatsD and a translator. - - -[Prometheus] is an open-source monitoring and alerting system. -Prometheus does not natively understand the StatsD protocol, but you -can deploy the [Prometheus StatsD Exporter] to act as the StatsD -sink, and it will translate from StatsD to the [exposition format] -that Prometheus requires. An example of how deploying Prometheus -StatsD Exporter is available in [`prom-statsd-sink.yaml`]. - -[Prometheus]: https://prometheus.io/ -[Prometheus StatsD Exporter]: https://github.com/prometheus/statsd_exporter -[exposition format]: https://prometheus.io/docs/instrumenting/exposition_formats/ -[`prom-statsd-sink.yaml`]: https://github.com/emissary-ingress/emissary/blob/master/deployments/statsd-sink/prometheus/prom-statsd-sink.yaml - -To finally get the statistics to Prometheus, you then configure a -Prometheus target to read from `statsd-sink` on port 9102. - -You could instead also add the `statsd-sink` service and Prometheus StatsD -Exporter as a sidecar on the $productName$ pod. If you do this, make -sure to set `STATSD_HOST=localhost` so that UDP packets are routed to -the sidecar. - -### Configuring how Prometheus StatsD Exporter translates from StatsD to the Prometheus format - -It may be desirable to change how metrics produced by the -`statsd-sink` are named, labeled and grouped when they finally make it -to Prometheus. - -For example, by default, each service that $productName$ serves will -create a new metric using its name. For the service called `usersvc` -you will see this metric -`envoy.cluster.usersvc_cluster.upstream_rq_total`. This may lead to -problems if you are trying to create a single aggregate that is the -sum of all similar metrics from different services. In this case, it -is common to differentiate the metrics for an individual service with -a `label`. This can be done by configuring a Prometheus StatsD -Exporter "mapping" (not to be confused with an [$productName$ -`Mapping`][Mappings]). See [Metric Mapping and Configuration] in -the Prometheus StatsD Exporter documentation to learn how to modify -its mappings. - -[Mappings]: ../../../using/mappings -[Metric Mapping and Configuration]: https://github.com/prometheus/statsd_exporter/#user-content-metric-mapping-and-configuration - -#### Configuring Prometheus StatsD Exporter with Helm - -If you deploy Prometheus using Helm the value that you should change -in order to add a mapping is `prometheusExporter.configuration`. Set -it to something like this: - -```yaml - configuration: | - --- - mappings: - - match: 'envoy.cluster.*.upstream_rq_total' - name: "envoy_cluster_upstream_rq_total" - timer_type: 'histogram' - labels: - cluster_name: "$1" -``` - -#### Configuring Prometheus StatsD Exporter in `prom-statsd-sink.yaml` - -If you are using the [`prom-statsd-sink.yaml`] example, edit its `ambassador-config` -ConfigMap with your Prometheus mappings, for example: - -```yaml ---- -apiVersion: v1 -kind: ConfigMap -metadata: - name: ambassador-config -data: - exporterConfiguration: | - --- - mappings: - - match: 'envoy.cluster.*.upstream_rq_total' - name: "envoy_cluster_upstream_rq_total" - timer_type: 'histogram' - labels: - cluster_name: "$1" -``` - -### Using the Prometheus Operator to configure Prometheus for use with the Prometheus StatsD Exporter - -If you don't already have a Prometheus setup, the [Prometheus -Operator] is a powerful way to create and deploy Prometheus -instances. Use the following YAML to quickly configure the Prometheus -Operator with $productName$: - -- [`statsd-sink.yaml`] Creates the Prometheus Stats Exporter - deployment and `statsd-sink` service that receives the statistics - from $productName$ and translates them to Prometheus metrics. It also - creates a `ServiceMonitor` resource that tells the Prometheus - Operator to configure Prometheus to fetch those metrics from the - StatsD Exporter. -- [`prometheus.yaml`] Deploys the Prometheus Operator and creates - `Prometheus` resource that tells the Prometheus Operator to create - the actual Prometheus deployment. - -[Prometheus operator]: https://github.com/coreos/prometheus-operator -[`statsd-sink.yaml`]: https://github.com/emissary-ingress/emissary/blob/master/deployments/statsd-sink/prometheus/statsd-sink.yaml -[`prometheus.yaml`]: https://github.com/emissary-ingress/emissary/blob/master/deployments/statsd-sink/prometheus/prometheus.yaml - -Make sure that the `ServiceMonitor` is in the same namespace as -$productName$. A walk-through of the basics of configuring the -Prometheus Operator with $productName$ is available -[here](http://www.datawire.io/faster/ambassador-prometheus/). - -Ensure `STATSD_ENABLED` is set to `"true"` and apply the YAML with -`kubectl`: - -``` -kubectl apply -f statsd-sink.yaml -kubectl apply -f prometheus.yaml -``` - -Wait for a minute after the pods spin up and then access the -Prometheus dashboard by port-forwarding the Prometheus pod and going -to `http://localhost:9090/` on a web-browser. - -``` -kubectl port-forward prometheus-prometheus-0 9090 -``` - -### Using Grafana to visualize statistics gathered by Prometheus -
-Screenshot of a Grafana dashboard that displays just information from Envoy - -If you're using Grafana, [Alex Gervais] has written a template -[$productName$ dashboard for Grafana] that works with either the -metrics exposed by the Prometheus StatsD Exporter, or by [the -`:8877/metrics` endpoint]. - -[Alex Gervais]: https://twitter.com/alex_gervais -[$productName$ dashboard for Grafana]: https://grafana.com/dashboards/4698 - -## Using Datadog DogStatsD as the StatsD sink - -If you are a user of the [Datadog] monitoring system, pulling in the -Envoy statistics from $productName$ is very easy. - -[Datadog]: https://www.datadoghq.com/ - -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: - -```diff - spec: - containers: - - env: -+ - name: STATSD_ENABLED -+ value: "true" -+ - name: DOGSTATSD -+ value: "true" - - name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: -``` - -Then, you will need to deploy the DogStatsD agent in to your cluster -to act as the StatsD sink. To do this, replace the sample API key in -our [sample YAML file][`dd-statsd-sink.yaml`] with your own, then -apply that YAML: - -[`dd-statsd-sink.yaml`]: https://github.com/emissary-ingress/emissary/blob/master/deployments/statsd-sink/datadog/dd-statsd-sink.yaml - -``` -kubectl apply -f statsd-sink/datadog/dd-statsd-sink.yaml -``` - -This sets up the `statsd-sink` service and a deployment of the -DogStatsD agent that forwards the $productName$ statistics to your -Datadog account. - -Additionally, $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). diff --git a/content/en/docs/3.1/topics/running/tls/cleartext-redirection.md b/content/en/docs/3.1/topics/running/tls/cleartext-redirection.md deleted file mode 100644 index 7144b1a3..00000000 --- a/content/en/docs/3.1/topics/running/tls/cleartext-redirection.md +++ /dev/null @@ -1,76 +0,0 @@ -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`. - - - The 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. - - -## Cleartext Routing - -To allow cleartext to be routed, set the `requestPolicy.insecure.action` of a `Host` to `Route`: - -```yaml -requestPolicy: - insecure: - action: Redirect -``` - -This allows routing for either HTTP and HTTPS, or _only_ HTTP, depending on `tlsSecret` configuration: - -- If the `Host` does not specify a `tlsSecret`, it will only route HTTP, not terminating TLS at all. -- If the `Host` does specify a `tlsSecret`, it will route both HTTP and HTTPS. - - - The 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. - - -## HTTP->HTTPS redirection - -Most websites that force HTTPS will also automatically redirect any -requests that come into it over HTTP: - -``` -Client $productName$ -| | -| http:///api | -| --------------------------> | -| | -| 301: https:///api | -| <-------------------------- | -| | -| https:///api | -| --------------------------> | -| | -``` - -In $productName$, this is configured by setting the `insecure.action` in a `Host` to `Redirect`. - -```yaml -requestPolicy: - insecure: - action: Redirect -``` - -$productName$ determines which requests are secure and which are insecure using the -`securityModel` of the [`Listener`] that accepts the request. - -[`Listener`]: ../../listener - - - The 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. - diff --git a/content/en/docs/3.1/topics/running/tls/index.md b/content/en/docs/3.1/topics/running/tls/index.md deleted file mode 100644 index 93427bc5..00000000 --- a/content/en/docs/3.1/topics/running/tls/index.md +++ /dev/null @@ -1,465 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Transport Layer Security (TLS) - -$productName$'s robust TLS support exposes configuration options -for many different TLS use cases, using the [`Host`](#host) and -[`TLSContext`](#host-and-tlscontext) resources in concert. - -## Certificates and Secrets - -Properly-functioning TLS requires the use of [TLS certificates] to prove that the -various systems communicating are who they say they are. At minimum, $productName$ -must have a server certificate that identifies it to clients; when [mTLS] or -[client certificate authentication] are in use, additional certificates are needed. - -You supply certificates to $productName$ in Kubernetes [TLS Secrets]. These Secrets -_must_ contain valid X.509 certificates with valid PKCS1, PKCS8, or Elliptic Curve private -keys. If a Secret does not contain a valid certificate, an error message will be logged, for -example: - -``` -tls-broken-cert.default.1 2 errors:; 1. K8sSecret secret tls-broken-cert.default tls.key cannot be parsed as PKCS1 or PKCS8: asn1: syntax error: data truncated; 2. K8sSecret secret tls-broken-cert.default tls.crt cannot be parsed as x.509: x509: malformed certificate -``` - -If you set the `AMBASSADOR_FORCE_SECRET_VALIDATION` environment variable, the invalid -Secret will be rejected, and a `Host` or `TLSContext` resource attempting to use an invalid -certificate will be disabled entirely. **Note** that in $productName$ $version$, this -includes disabling cleartext communication for such a `Host`. - -[TLS Certificates]: https://protonmail.com/blog/tls-ssl-certificate/ -[mTLS]: mtls -[client certificate authentication]: ../../../howtos/client-cert-validation/ -[TLS Secrets]: https://kubernetes.io/docs/concepts/configuration/secret/#tls-secrets - -## `Host` - -A `Host` represents a domain in $productName$ and defines how the domain manages TLS. For more information on the Host resource, see [The Host CRD reference documentation](../host-crd). - -**If no `Host`s are present**, $productName$ synthesizes a `Host` that -allows only cleartext routing. You will need to explictly define `Host`s to enable -TLS termination. - - - The examples below do not define a requestPolicy; however, most real-world - usage of $productName$ will require defining the requestPolicy.
-
- For more information, please refer to the Host documentation. - - -### Bring your own certificate - -The `Host` can read a certificate from a Kubernetes Secret and use that certificate -to terminate TLS on a domain. - -The following example shows the certificate contained in the Kubernetes Secret named -`host-secret` configured to have $productName$ terminate TLS on the `host.example.com` -domain: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: host-secret -``` - - - - The Kubernetes Secret named by 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. - - - -### Advanced TLS configuration with the `Host` - -You can specify TLS configuration directly in the `Host` via the `tls` field. This is the -recommended method to do more advanced TLS configuration for a single `Host`. - -For example, the configuration to enforce a minimum TLS version on the `Host` looks as follows: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: min-secret - tls: - min_tls_version: v1.2 -``` - - - - The Kubernetes Secret named by 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. - - - -The following fields are accepted in the `tls` field: -```yaml -tls: - cert_chain_file: # string - private_key_file: # string - ca_secret: # string - cacert_chain_file: # string - alpn_protocols: # string - cert_required: # bool - min_tls_version: # string - max_tls_version: # string - cipher_suites: # array of strings - ecdh_curves: # array of strings - sni: # string - crl_secret: # string -``` - -These fields have the same function as in the [`TLSContext`](#tlscontext) resource, -as described below. - -### `Host` and `TLSContext` - -You can link a `Host` to a [`TLSContext`](#tlscontext) instead of defining `tls` -settings in the `Host` itself. This is primarily useful for sharing settings between -multiple `Host`s. - -#### Link a `TLSContext` to the `Host` - - - It is invalid to use both the 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. - - -To link a [`TLSContext`](#tlscontext) with a `Host`, create a [`TLSContext`](#tlscontext) -with the desired configuration and link it to the `Host` by setting the `tlsContext.name` -field in the `Host`. For example, to enforce a minimum TLS version on the `Host` above, -create a `TLSContext` with any name with the following configuration: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: min-tls-context -spec: - hosts: - - host.example.com - secret: min-secret - min_tls_version: v1.2 -``` - -Next, link it to the `Host` via the `tlsContext` field as shown: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: min-secret - tlsContext: - name: min-tls-context -``` - - - - The `Host` and the `TLSContext` must name the same Kubernetes Secret; if not, - $productName$ will disable TLS for the `Host`. - - - - - - The Kubernetes Secret named by 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. - - - - - - The `Host`'s `hostname` and the `TLSContext`'s `hosts` must have compatible settings. If - they do not, requests may not be accepted. - - - -See [`TLSContext`](#tlscontext) below to read more on the description of these fields. - -#### Create a `TLSContext` with the name `{{AMBASSADORHOST}}-context` (DEPRECATED) - - - This implicit 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. - - -The `Host` will implicitly link to the `TLSContext` when a `TLSContext` exists with the following: - -- the name `{{NAME_OF_AMBASSADORHOST}}-context` -- `hosts` in the `TLSContext` set to the same value as `hostname` in the `Host`, and -- `secret` in the `TLSContext` set to the same value as `tlsSecret` in the `Host` - -**As noted above, this implicit linking is deprecated.** - -For example, another way to enforce a minimum TLS version on the `Host` above would -be to simply create the `TLSContext` with the name `example-host-context` and then not modify the `Host`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-host-context -spec: - hosts: - - host.example.com - secret: host-secret - min_tls_version: v1.2 -``` - - - - The `Host` and the `TLSContext` must name the same Kubernetes Secret; if not, - $productName$ will disable TLS for the `Host`. - - - - - - The Kubernetes Secret named by 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. - - - - - - The `Host`'s `hostname` and the `TLSContext`'s `hosts` must have compatible settings. If - they do not, requests may not be accepted. - - - -Full reference for all options available to the `TLSContext` can be found [below](#tlscontext). - -## TLSContext - -The `TLSContext` is used to configure advanced TLS options in $productName$. -Remember, a `TLSContext` must always be paired with a `Host`. - -A full schema of the `TLSContext` can be found below with descriptions of the -different configuration options. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-host-context -spec: - # 'hosts' defines the hosts for which this TLSContext is relevant. - # It ties into SNI. A TLSContext without "hosts" is useful only for - # originating TLS. - # type: array of strings - # - # hosts: [] - - # 'sni' defines the SNI string to use on originated connections. - # type: string - # - # sni: None - - # 'secret' defines a Kubernetes Secret that contains the TLS certificate we - # use for origination or termination. If not specified, $productName$ will look - # at the value of cert_chain_file and private_key_file. - # type: string - # - # secret: None - - # 'ca_secret' defines a Kubernetes Secret that contains the TLS certificate we - # use for verifying incoming TLS client certificates. - # type: string - # - # ca_secret: None - - # Tells $productName$ whether to interpret a "." in the secret name as a "." or - # a namespace identifier. - # type: boolean - # - # secret_namespacing: true - - # 'cert_required' can be set to true to _require_ TLS client certificate - # authentication. - # type: boolean - # - # cert_required: false - - # 'alpn_protocols' is used to enable the TLS ALPN protocol. It is required - # if you want to do GRPC over TLS; typically it will be set to "h2" for that - # case. - # type: string (comma-separated list) - # - # alpn_protocols: None - - # 'min_tls_version' sets the minimum acceptable TLS version: v1.0, v1.1, - # v1.2, or v1.3. It defaults to v1.0. - # min_tls_version: v1.0 - - # 'max_tls_version' sets the maximum acceptable TLS version: v1.0, v1.1, - # v1.2, or v1.3. It defaults to v1.3. - # max_tls_version: v1.3 - - # Tells $productName$ to load TLS certificates from a file in its container. - # type: string - # - # cert_chain_file: None - # private_key_file: None - # cacert_chain_file: None -``` - - - - `secret` and (if used) `ca_secret` must specify Kubernetes Secrets containing valid TLS - certificates. If `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and either Secret contains - an invalid certificate, $productName$ will reject the Secret, which will also completely - disable any `Host` using the `TLSContext`; see [**Certificates and Secrets**](#certificates-and-secrets) - above. - - - -### ALPN protocols - -The `alpn_protocols` setting configures the TLS ALPN protocol. To use gRPC over -TLS, set `alpn_protocols: h2`. If you need to support HTTP/2 upgrade from -HTTP/1, set `alpn_protocols: h2,http/1.1` in the configuration. - -#### HTTP/2 support - -The `alpn_protocols` setting is also required for HTTP/2 support. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls -spec: - secret: ambassador-certs - hosts: ["*"] - alpn_protocols: h2[, http/1.1] -``` -Without setting alpn_protocols as shown above, HTTP2 will not be available via -negotiation and will have to be explicitly requested by the client. - -If you leave off http/1.1, only HTTP2 connections will be supported. - -### TLS parameters - -The `min_tls_version` setting configures the minimum TLS protocol version that -$productName$ will use to establish a secure connection. When a client -using a lower version attempts to connect to the server, the handshake will -result in the following error: `tls: protocol version not supported`. - -The `max_tls_version` setting configures the maximum TLS protocol version that -$productName$ will use to establish a secure connection. When a client -using a higher version attempts to connect to the server, the handshake will -result in the following error: -`tls: server selected unsupported protocol version`. - -The `cipher_suites` setting configures the supported ciphers found below using the -[configuration parameters for BoringSSL](https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#Cipher-suite-configuration) when negotiating a TLS 1.0-1.2 connection. -This setting has no effect when negotiating a TLS 1.3 connection. When a client does not -support a matching cipher a handshake error will result. - -The `ecdh_curves` setting configures the supported ECDH curves when negotiating -a TLS connection. When a client does not support a matching ECDH a handshake -error will result. - -``` - - AES128-SHA - - AES256-SHA - - AES128-GCM-SHA256 - - AES256-GCM-SHA384 - - ECDHE-RSA-AES128-SHA - - ECDHE-RSA-AES256-SHA - - ECDHE-RSA-AES128-GCM-SHA256 - - ECDHE-RSA-AES256-GCM-SHA384 - - ECDHE-RSA-CHACHA20-POLY1305 - - ECDHE-ECDSA-AES128-SHA - - ECDHE-ECDSA-AES256-SHA - - ECDHE-ECDSA-AES128-GCM-SHA256 - - ECDHE-ECDSA-AES256-GCM-SHA384 - - ECDHE-ECDSA-CHACHA20-POLY1305 - - ECDHE-PSK-AES128-CBC-SHA - - ECDHE-PSK-AES256-CBC-SHA - - ECDHE-PSK-CHACHA20-POLY1305 - - PSK-AES128-CBC-SHA - - PSK-AES256-CBC-SHA - - DES-CBC3-SHA -``` - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls -spec: - hosts: ["*"] - secret: ambassador-certs - min_tls_version: v1.0 - max_tls_version: v1.3 - cipher_suites: - - "[ECDHE-ECDSA-AES128-GCM-SHA256|ECDHE-ECDSA-CHACHA20-POLY1305]" - - "[ECDHE-RSA-AES128-GCM-SHA256|ECDHE-RSA-CHACHA20-POLY1305]" - ecdh_curves: - - X25519 - - P-256 -``` - - -The `crl_secret` field allows you to reference a Kubernetes Secret that contains a certificate revocation list. -If specified, $productName$ will verify that the presented peer certificate has not been revoked by this CRL even if they are otherwise valid. This provides a way to reject certificates before they expire or if they become compromised. -The `crl_secret` field takes a PEM-formatted [Certificate Revocation List](https://en.wikipedia.org/wiki/Certificate_revocation_list) in a `crl.pem` entry. - -Note that if a CRL is provided for any certificate authority in a trust chain, a CRL must be provided for all certificate authorities in that chain. Failure to do so will result in verification failure for both revoked and unrevoked certificates from that chain. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls-crl -spec: - hosts: ["*"] - secret: ambassador-certs - min_tls_version: v1.0 - max_tls_version: v1.3 - crl_secret: 'ambassador-crl' ---- -apiVersion: v1 -kind: Secret -metadata: - name: ambassador-crl - namespace: ambassador -type: Opaque -data: - crl.pem: | - {BASE64 CRL CONTENTS} ---- -``` diff --git a/content/en/docs/3.1/topics/running/tls/mtls.md b/content/en/docs/3.1/topics/running/tls/mtls.md deleted file mode 100644 index 1b039cf8..00000000 --- a/content/en/docs/3.1/topics/running/tls/mtls.md +++ /dev/null @@ -1,88 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Mutual TLS (mTLS) - -Many organizations have security concerns that require all network traffic -throughout their cluster be encrypted. With traditional architectures, -this was not that complicated of a requirement since internal network traffic -was fairly minimal. With microservices, we are making many more requests over -the network that must all be authenticated and secured. - -In order for services to authenticate with each other, they will each need to -provide a certificate and key that the other trusts before establishing a -connection. This action of both the client and server providing and validating -certificates is referred to as mutual TLS. - -## mTLS with $productName$ - -Since $productName$ is a reverse proxy acting as the entry point to your cluster, -$productName$ is acting as the client as it proxies requests to services upstream. - -It is trivial to configure $productName$ to simply originate TLS connections as -the client to upstream services by setting -`service: https://{{UPSTREAM_SERVICE}}` in the `Mapping` configuration. -However, in order to do mTLS with services upstream, $productName$ must also -have certificates to authenticate itself with the service. - -To do this, we can use the `TLSContext` object to get certificates from a -Kubernetes `Secret` and use those to authenticate with the upstream service. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: upstream-context -spec: - hosts: [] - secret: upstream-certs -``` - -We use `hosts: []` for this `TLSContext` since we do not want to use it to terminate -TLS connections from the client. We are just using this to load certificates for -requests upstream. - - - - The Kubernetes Secret must contain a valid TLS certificate. If the environment - variable `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) in the TLS overview. - - - -After loading the certificates, we can tell $productName$ when to use them by -setting the `tls` parameter in a `Mapping`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: upstream-mapping -spec: - hostname: "*" - prefix: /upstream/ - service: upstream-service - tls: upstream-context -``` - -Now, when $productName$ proxies a request to `upstream-service`, it will provide -the certificates in the `upstream-certs` secret for authentication when -encrypting traffic. - -## Service mesh - -As you can imagine, when you have many services in your cluster all -authenticating with each other, managing all of those certificates can become a -very big challenge. - -For this reason, many organizations rely on a service mesh for their -service-to-service authentication and encryption. - -$productName$ integrates with multiple service meshes and makes it easy to -configure mTLS to upstream services for all of them. Click the links below to -see how to configure $productName$ to do mTLS with any of these service meshes: - -- [Consul Connect](../../../../howtos/consul/) - -- [Istio](../../../../howtos/istio/) diff --git a/content/en/docs/3.1/topics/running/tls/origination.md b/content/en/docs/3.1/topics/running/tls/origination.md deleted file mode 100644 index b15dd5f8..00000000 --- a/content/en/docs/3.1/topics/running/tls/origination.md +++ /dev/null @@ -1,82 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# TLS origination - -Sometimes you may want traffic from $productName$ to your services to be encrypted. For the cases where terminating TLS at the ingress is not enough, $productName$ can be configured to originate TLS connections to your upstream services. - -## Basic configuration - -Telling $productName$ to talk to your services over HTTPS is easily configured in the `Mapping` definition by setting `https://` in the `service` field. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: basic-tls -spec: - hostname: "*" - prefix: / - service: https://example-service -``` - -## Advanced configuration using a `TLSContext` - -If your upstream services require more than basic HTTPS support (for example, providing a client certificate or -setting the minimum TLS version support) you must create a `TLSContext` for $productName$ to use when -originating TLS. For example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls-context -spec: - secret: self-signed-cert - min_tls_version: v1.3 - sni: some-sni-hostname -``` - - - - The Kubernetes Secret named by `secret` must contain a valid TLS certificate. If the - environment variable `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and the Secret contains - an invalid certificate, $productName$ will reject the `TLSContext` and prevent its use; - see [**Certificates and Secrets**](../#certificates-and-secrets) in the TLS overview. - - - -Configure $productName$ to use this `TLSContext` for connections to upstream services by setting the `tls` attribute of a `Mapping`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-with-tls-context -spec: - hostname: "*" - prefix: / - service: https://example-service - tls: tls-context -``` - -The `example-service` service must now support TLS v1.3 for $productName$ to connect. - - - - The Kubernetes Secret named by `secret` must contain a valid TLS certificate. If the - environment variable `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and the Secret contains - an invalid certificate, $productName$ will reject the `TLSContext` and prevent its use; - see [**Certificates and Secrets**](../#certificates-and-secrets) in the TLS overview. - - - - - - A `TLSContext` requires a certificate be provided, even in cases where the upstream - service does not require it (for origination) and the `TLSContext` is not being used - to terminate TLS. In this case, simply generate and provide a self-signed certificate. - - diff --git a/content/en/docs/3.1/topics/running/tls/sni.md b/content/en/docs/3.1/topics/running/tls/sni.md deleted file mode 100644 index 92e4992f..00000000 --- a/content/en/docs/3.1/topics/running/tls/sni.md +++ /dev/null @@ -1,103 +0,0 @@ -# Server Name Indication (SNI) - -$productName$ supports serving multiple `Host`s behind a single IP address, each -with their own certificate. - -This is as easy to do as creating a `Host` for each domain or subdomain you -want $productName$ to serve, getting a certificate for each, and telling -$productName$ which `Host` the route should be created for. - -The example below configures two `Host`s and assigns routes to them. - -## Configuring a `Host` - -The `Host` resources lets you separate configuration for each distinct domain -and subdomain you plan on serving behind $productName$. - -Let's start by creating a simple `Host` and providing our own certificate in -the `host-cert` secret. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: host-cert -``` - -Now let's create a second `Host` for a different domain we want to serve behind -$productName$. This second `Host` uses $AESproductName$'s automatic TLS -to get a certificate from Let's Encrypt. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: host.foo.com - acmeProvider: - email: julian@example.com -``` - -We now have two `Host`s with two different certificates. - - - A minimum version of TLS 1.1 is required to properly use SNI. When setting up your TLS configuration, be sure you are not using TLS 1.0 or older. - - -## Configuring routes - -Now that we have two domains behind $productName$, we can create routes for either -or both of them. - -We do this by setting the `hostname` attribute of a `Mapping` to the domain the -`Mapping` should be created for. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin -spec: - prefix: /httpbin/ - service: httpbin.org:80 - host_rewrite: httpbin.org - hostname: host.example.com -``` - -The above creates a `/httpbin/` endpoint for `host.example.com`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mockbin -spec: - prefix: /foo/ - service: foo-service - hostname: host.foo.com -``` - -The above creates a `/foo/` endpoint for `host.foo.com`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: frontend -spec: - hostname: "*" - prefix: /bar/ - service: bar-endpoint -``` - -The above creates a `/bar/` endpoint for all `Host`s. diff --git a/content/en/docs/3.1/topics/using/authservice.md b/content/en/docs/3.1/topics/using/authservice.md deleted file mode 100644 index 9bc2630f..00000000 --- a/content/en/docs/3.1/topics/using/authservice.md +++ /dev/null @@ -1,24 +0,0 @@ -# AuthService settings - -A Mapping can pass these settings along to an [AuthService](../../running/services/auth-service). This is helpful to allow these specific configurations to apply only to certain Mappings and not globally. - -## Bypass authentication - -An AuthService can be disabled for a specific Mapping with the `bypass_auth` attribute. This will tell $productName$ to allow all requests for that Mapping through without interacting with the external auth service. This could be helpful, for example, for a public API. - -```yaml -bypass_auth: true -``` - -## Context extensions (gRPC only) - -The `auth_context_extensions` attribute will pass the given values along to the AuthService when authentication happens. This is only supported when the `proto` of the AuthService is `grpc`, which is a restriction of the underlying Envoy implementation. -The values are arbitrary key value pairs formatted as strings. - -```yaml -auth_context_extensions: - foo: bar - baz: zing -``` - -More information is available on [the Envoy documentation on external authentication](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto.html#extensions-filters-http-ext-authz-v3-checksettings). diff --git a/content/en/docs/3.1/topics/using/canary.md b/content/en/docs/3.1/topics/using/canary.md deleted file mode 100644 index f99de1a3..00000000 --- a/content/en/docs/3.1/topics/using/canary.md +++ /dev/null @@ -1,41 +0,0 @@ -# Canary releases - -Canary releasing is a deployment pattern where a small percentage of traffic is diverted to an early ("canary") release of a particular service. This technique lets you test a release on a small subset of users, mitigating the impact of any given bug. Canary releasing also allows you to quickly roll back to a known good version in the event of an unexpected error. Detailed monitoring of core service metrics is an essential part of canary releasing, as monitoring enables the rapid detection of problems in the canary release. - -## Canary releases in Kubernetes - -Kubernetes supports a basic canary release workflow using its core objects. In this workflow, a service owner can create a Kubernetes [service](https://kubernetes.io/docs/concepts/services-networking/service/). This service can then be pointed to multiple [deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/). Each deployment can be a different version. By specifying the number of `replicas` in a given deployment, you can control how much traffic goes between different versions. For example, you could set `replicas: 3` for `v1`, and `replicas: 1` for `v2`, to ensure that 25% of traffic goes to `v2`. This approach works but is fairly coarse-grained unless you have lots of replicas. Moreover, auto-scaling doesn't work well with this strategy. - -## Canary releases in $productName$ - -$productName$ supports fine-grained canary releases. $productName$ uses a weighted round-robin scheme to route traffic between multiple services. Full metrics are collected for all services, making it easy to compare the relative performance of the canary and production. - -### The weight attribute - -The `weight` attribute specifies how much traffic for a given resource will be routed using a given mapping. Its value is an integer percentage between 0 and 100. $productName$ will balance weights to make sure that, for every resource, the mappings for that resource will have weights adding to 100%. (In the simplest case, a single mapping is guaranteed to receive 100% of the traffic no matter whether it's assigned a `weight` or not.) - -Specifying a weight only makes sense if you have multiple mappings for the same resource, and typically you would _not_ assign a weight to the "default" mapping (the mapping expected to handle most traffic): letting $productName$ assign that mapping all the traffic not otherwise spoken for tends to make life easier when updating weights. - -Here's an example, which might appear during a canary deployment: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - prefix: /backend/ - service: quotev2 - weight: 10 -``` - -In this case, the quote-backend2 will receive 10% of the requests for `/backend/`, and $productName$ will assign the remaining 90% to the quote-backend. diff --git a/content/en/docs/3.1/topics/using/circuit-breakers.md b/content/en/docs/3.1/topics/using/circuit-breakers.md deleted file mode 100644 index 97b40f57..00000000 --- a/content/en/docs/3.1/topics/using/circuit-breakers.md +++ /dev/null @@ -1,116 +0,0 @@ -# Circuit breakers - -Circuit breakers are a powerful technique to improve resilience. By preventing additional connections or requests to an overloaded service, circuit breakers limit the ["blast radius"](https://www.ibm.com/garage/method/practices/manage/practice_limited_blast_radius/) of an overloaded service. By design, $productName$ circuit breakers are distributed, i.e., different $productName$ instances do not coordinate circuit breaker information. - -## Circuit breaker configuration - -A default circuit breaking configuration can be set for all -$productName$ resources in the [`ambassador -Module`](../../running/ambassador), or set to a different value on a -per-resource basis for [`Mappings`](../mappings), -[`TCPMappings`](../tcpmappings/), and -[`AuthServices`](../../running/services/auth-service/). - -The `circuit_breakers` attribute configures circuit breaking. The following fields are supported: - -```yaml -circuit_breakers: -- priority: - max_connections: - max_pending_requests: - max_requests: - max_retries: -``` - -|Key|Default value|Description| -|---|---|---| -|`priority`|`default`|Specifies the priority to which the circuit breaker settings apply to; it can be set to either `default` or `high`.| -|`max_connections`|`1024`|Specifies the maximum number of connections that $productName$ will make to the services. In practice, this is more applicable to HTTP/1.1 than HTTP/2.| -|`max_pending_requests`|`1024`|Specifies the maximum number of requests that will be queued while waiting for a connection. In practice, this is more applicable to HTTP/1.1 than HTTP/2.| -|`max_requests`|`1024`|Specifies the maximum number of parallel outstanding requests to an upstream service. In practice, this is more applicable to HTTP/2 than HTTP/1.1.| -|`max_retries`|`3`|Specifies the maximum number of parallel retries allowed to an upstream service.| - -The `max_*` fields can be reduced to shrink the "blast radius," or -increased to enable $productName$ to handle a larger number of -concurrent requests. - -## Examples - -Circuit breakers defined on a single `Mapping`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - circuit_breakers: - - max_connections: 2048 - max_pending_requests: 2048 -``` - -Circuit breakers defined on a single `AuthService`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: AuthService -metadata: - name: dancing-walrus -spec: - auth_service: http://dancing-walrus:8500 - proto: grpc - circuit_breakers: - - max_requests: 4096 -``` - -A global circuit breaker: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - circuit_breakers: - - max_connections: 2048 - max_pending_requests: 2048 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote -``` - -## Circuit breakers and automatic retries - -Circuit breakers are best used in conjunction with [automatic retries](../retries). Here are some examples: - -* You've configured automatic retries for failed requests to a service. Your service is under heavy load, and starting to time out on servicing requests. In this case, automatic retries can exacerbate your problem, increasing the total request volume by 2x or more. By aggressively circuit breaking, you can mitigate failure in this scenario. -* To circuit break when services are slow, you can combine circuit breakers with retries. Reduce the time out for retries, and then set a circuit breaker that detects many retries. In this setup, if your service doesn't respond quickly, a flood of retries will occur, which can then trip the circuit breaker. - -Note that setting circuit breaker thresholds requires careful monitoring and experimentation. We recommend you start with conservative values for circuit breakers and adjust them over time. - -## More about circuit breakers - -Responses from a broken circuit contain the `x-envoy-overloaded` header. - -The following are the default values for circuit breaking if nothing is specified: - -```yaml -circuit_breakers: -- priority: default - max_connections: 1024 - max_pending_requests: 1024 - max_requests: 1024 - max_retries: 3 -``` - -Circuit breaker metrics are exposed in StatsD. For more information about the specific statistics, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/circuit_breaking.html). diff --git a/content/en/docs/3.1/topics/using/cors.md b/content/en/docs/3.1/topics/using/cors.md deleted file mode 100644 index 315e4694..00000000 --- a/content/en/docs/3.1/topics/using/cors.md +++ /dev/null @@ -1,155 +0,0 @@ -# Cross-Origin Resource Sharing (CORS) - -Cross-Origin resource sharing lets users request resources (e.g., images, fonts, videos) from domains outside the original domain. - -CORS configuration can be set for all $productName$ mappings in the [`ambassador Module`](../../running/ambassador), or set per [`Mapping`](../mappings). - -When the CORS attribute is set at either the `Mapping` or `Module` level, $productName$ will intercept the pre-flight `OPTIONS` request and respond with the appropriate CORS headers. This means you will not need to implement any logic in your upstreams to handle these CORS `OPTIONS` requests. - -The flow of the request will look similar to the following: -``` -Client $productName$ Upstream - | OPTIONS | | - | —————————————————> | | - | CORS_RESP | | - | <————————————————— | | - | GET /foo/ | | - | —————————————————> | ————————————> | - | | RESP | - | <————————————————————————————————— | -``` -## The `cors` attribute - -The `cors` attribute enables the CORS filter. The following settings are supported: - -- `origins`: Specifies a list of allowed domains for the `Access-Control-Allow-Origin` header. To allow all origins, use the wildcard `"*"` value. Format can be either of: - - comma-separated list, e.g. - ```yaml - origins: http://foo.example,http://bar.example - ``` - - YAML array, e.g. - ```yaml - origins: - - http://foo.example - - http://bar.example - ``` - -- `methods`: if present, specifies a list of allowed methods for the `Access-Control-Allow-Methods` header. Format can be either of: - - comma-separated list, e.g. - ```yaml - methods: POST, GET, OPTIONS - ``` - - YAML array, e.g. - ```yaml - methods: - - GET - - POST - - OPTIONS - ``` - -- `headers`: if present, specifies a list of allowed headers for the `Access-Control-Allow-Headers` header. Format can be either of: - - comma-separated list, e.g. - ```yaml - headers: Content-Type - ``` - - YAML array, e.g. - ```yaml - headers: - - Content-Type - ``` - -- `credentials`: if present with a true value (boolean), will send a `true` value for the `Access-Control-Allow-Credentials` header. - -- `exposed_headers`: if present, specifies a list of allowed headers for the `Access-Control-Expose-Headers` header. Format can be either of: - - comma-separated list, e.g. - ```yaml - exposed_headers: X-Custom-Header - ``` - - YAML array, e.g. - ```yaml - exposed_headers: - - X-Custom-Header - ``` - -- `max_age`: if present, indicated how long the results of the preflight request can be cached, in seconds. This value must be a string. - -## Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cors -spec: - prefix: /cors/ - service: cors-example - cors: - origins: http://foo.example,http://bar.example - methods: POST, GET, OPTIONS - headers: Content-Type - credentials: true - exposed_headers: X-Custom-Header - max_age: "86400" -``` - -## AuthService and Cross-Origin Resource Sharing - -When you use external authorization, each incoming request is authenticated before routing to its destination, including pre-flight `OPTIONS` requests. - -By default, many [`AuthService`](../../running/services/auth-service) implementations will deny these requests. If this is the case, you will need to add some logic to your `AuthService` to accept all CORS headers. - -For example, a possible configuration for Spring Boot 2.0.1: - -```java -@EnableWebSecurity -class SecurityConfig extends WebSecurityConfigurerAdapter { - - public void configure(final HttpSecurity http) throws Exception { - http - .cors().configurationSource(new PermissiveCorsConfigurationSource()).and() - .csrf().disable() - .authorizeRequests() - .antMatchers("**").permitAll(); - } - - private static class PermissiveCorsConfigurationSource implements CorsConfigurationSource { - /** - * Return a {@link CorsConfiguration} based on the incoming request. - * - * @param request - * @return the associated {@link CorsConfiguration}, or {@code null} if none - */ - @Override - public CorsConfiguration getCorsConfiguration(final HttpServletRequest request) { - final CorsConfiguration configuration = new CorsConfiguration(); - configuration.setAllowCredentials(true); - configuration.setAllowedHeaders(Collections.singletonList("*")); - configuration.setAllowedMethods(Collections.singletonList("*")); - configuration.setAllowedOrigins(Collections.singletonList("*")); - return configuration; - } - } -} -``` - -This is okay since CORS is being handled by $productName$ after authentication. - -The flow of this request will look similar to the following: - -``` -Client $productName$ Auth Upstream - | OPTIONS | | | - | —————————————————> | ————————————> | | - | | CORS_ACCEPT_* | | - | CORS_RESP |<——————————————| | - | <——————————————————| | | - | GET /foo/ | | | - | —————————————————> | ————————————> | | - | | AUTH_RESP | | - | | <———————————— | | - | | AUTH_ALLOW | | - | | ————————————————————————————> | - | | | RESP | - | <————————————————————————————————————————————————— | - ``` diff --git a/content/en/docs/3.1/topics/using/defaults.md b/content/en/docs/3.1/topics/using/defaults.md deleted file mode 100644 index 673a08be..00000000 --- a/content/en/docs/3.1/topics/using/defaults.md +++ /dev/null @@ -1,32 +0,0 @@ -# Using `ambassador` `Module` defaults - -## The defaults element - -If present, the `ambassador Module` can define a set of defaults that will automatically be applied to certain resources: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - class1: # This is a class. Different resource types will look in different classes. - key1: value1 # Within a class, you can set different keys. - key2: value2 - ... - class2: - ... - top_key1: value1 # If a key isn't found in a resource's class, the system will look in the - top_key2: value2 # toplevel defaults dictionary for it. -``` - -### Mapping - -Currently, only the `Mapping` resource uses the `defaults` mechanism. `Mapping` looks first for defaultable resources in the `httpmapping` class, including: - -- [`add_request_headers`](../../using/headers/add_request_headers) -- [`add_response_headers`](../../using/headers/add_response_headers) -- [`remove_request_headers`](../../using/headers/remove_request_headers) -- [`remove_response_headers`](../../using/headers/remove_response_headers) diff --git a/content/en/docs/3.1/topics/using/gateway-api.md b/content/en/docs/3.1/topics/using/gateway-api.md deleted file mode 100644 index 5e92cd0d..00000000 --- a/content/en/docs/3.1/topics/using/gateway-api.md +++ /dev/null @@ -1,19 +0,0 @@ -# Gateway API - -## Using the Gateway API - -$productName$ now supports a limited subset of the new `v1alpha1` [Gateway API](https://gateway-api.sigs.k8s.io/). -Note that the Gateway API is not supported when `AMBASSADOR_LEGACY_MODE` is set. - -Support is currently limited to the following fields, however this will expand in future releases: - - - `Gateway.spec.listeners.port` - - `HTTPRoute.spec.rules.matches.path.type` (`Exact`, `Prefix`, and `RegularExpression`) - - `HTTPRoute.spec.rules.matches.path.value` - - `HTTPRoute.spec.rules.matches.header.type` (`Exact` and `RegularExpression`) - - `HTTPRoute.spec.rules.matches.header.values` - - `HTTPRoute.spec.rules.forwardTo.serviceName` - - `HTTPRoute.spec.rules.forwardTo.port` - - `HTTPRoute.spec.rules.forwardTo.weight` - -Please see the [specification](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/) for more details. diff --git a/content/en/docs/3.1/topics/using/headers/add_request_headers.md b/content/en/docs/3.1/topics/using/headers/add_request_headers.md deleted file mode 100644 index c6ad4956..00000000 --- a/content/en/docs/3.1/topics/using/headers/add_request_headers.md +++ /dev/null @@ -1,77 +0,0 @@ -# Add request headers - -$productName$ can add a dictionary of HTTP headers that can be added to each request that is passed to a service. - -## The `add_request_headers` attribute - -The `add_request_headers` attribute is a dictionary of `header`: `value` pairs. The `value` can be a `string`, `bool` or `object`. When it is an `object`, the object should have a `value` property, which is the actual header value, and the remaining attributes are additional envoy properties. - -Envoy dynamic values `%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%` and `%PROTOCOL%` are supported, in addition to static values. - -`add_request_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -### Mapping example - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: "*" - prefix: /backend/ - add_request_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-static-2: - value: This the test header #same as above "x-test-static header" - x-test-object: - value: This the value - append: False #True by default - service: quote - ``` - -will add the protocol, client IP, and a static header to `/backend/`. - -### Defaults example - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - add_request_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-static-2: - value: This the test header #same as above "x-test-static header" - x-test-object: - value: This the value - append: False #True by default ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - hostname: "*" - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - hostname: "*" - prefix: /backend2/ - service: quote -``` - -This example will add the same headers for both mappings. diff --git a/content/en/docs/3.1/topics/using/headers/add_response_headers.md b/content/en/docs/3.1/topics/using/headers/add_response_headers.md deleted file mode 100644 index 236ace61..00000000 --- a/content/en/docs/3.1/topics/using/headers/add_response_headers.md +++ /dev/null @@ -1,73 +0,0 @@ -# Add response headers - -$productName$ can add a dictionary of HTTP headers that can be added to each response that is returned to the client. - -## The `add_response_headers` attribute - -The `add_response_headers` attribute is a dictionary of `header`: `value` pairs. The `value` can be a `string`, `bool` or `object`. When it is an `object`, the object should have a `value` property, which is the actual header value, and the remaining attributes are additional envoy properties. - -Envoy dynamic values `%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%` and `%PROTOCOL%` are supported, in addition to static values. - -`add_response_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -### Mapping example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - add_response_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-object: - append: False - value: this is from object header config - service: quote -``` - -will add the protocol, client IP, and a static header to the response returned to the client. - -### Defaults example - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - add_response_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-object: - append: False - value: this is from object header config ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - hostname: "*" - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - hostname: "*" - prefix: /backend2/ - service: quote -``` - -This example will add the same headers for both mappings. diff --git a/content/en/docs/3.1/topics/using/headers/headers.md b/content/en/docs/3.1/topics/using/headers/headers.md deleted file mode 100644 index 126653b0..00000000 --- a/content/en/docs/3.1/topics/using/headers/headers.md +++ /dev/null @@ -1,76 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Header-based routing - -$productName$ can route to target services based on HTTP headers with the `headers` and `regex_headers` specifications. Multiple mappings with different annotations can be applied to construct more complex routing rules. - -## The `headers` annotation - -The `headers` attribute is a dictionary of `header`: `value` pairs. $productName$ will only allow requests that match the specified `header`: `value` pairs to reach the target service. - -### Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - headers: - x-quote-mode: backend - x-random-header: datawire -``` - -will allow requests to /backend/ to succeed only if the x-quote-mode header has the value backend and the x-random-header has the value `datawire`. - - - 1.x versions of the Ambassador Edge Stack could test for the existence of a header using x-sample-header:true. Since 2.0, the same functionality is achieved by using regex_headers. - - -## Regex headers - -You can also set the `value` of a regex header to `".*"` to test for the existence of a header. - -### Conditional example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-mode -spec: - prefix: /backend/ - service: quote-mode - regex_headers: - x-quote-mode: ".*" - ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-regular -spec: - prefix: /backend/ - service: quote-regular -``` - -will send requests that contain the x-quote-mode header to the quote-mode target, while routing all other requests to the quote-regular target. - -The following mapping will route mobile requests from Android and iPhones to a mobile service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - regex_headers: - user-agent: ".*(iPhone|(a|A)ndroid).*" - prefix: /backend/ - service: quote -``` diff --git a/content/en/docs/3.1/topics/using/headers/host.md b/content/en/docs/3.1/topics/using/headers/host.md deleted file mode 100644 index 5a8dd02c..00000000 --- a/content/en/docs/3.1/topics/using/headers/host.md +++ /dev/null @@ -1,76 +0,0 @@ -# Host headers - -$productName$ supports several different methods for managing the HTTP `Host` header. - -## Using `host` and `host_regex` - -A mapping that specifies the `host` attribute will take effect _only_ if the HTTP `Host` header matches the value in the `host` attribute. If `host_regex` is `true`, the `host` value is taken to be a regular expression. Otherwise, an exact string match is required. - -You may have multiple mappings listing the same resource but different `host` attributes to effect `Host`-based routing. An example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote1 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend-2 -spec: - prefix: /backend/ - host: quote.datawire.io - service: quote2 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend-3 -spec: - prefix: /backend/ - host: "^quote[2-9]\\.datawire\\.io$" - host_regex: true - service: quote3 -``` - -will map requests for `/` to - -- the `quote2` service if the `Host` header is `quote.datawire.io`; -- the `quote3` service if the `Host` header matches `^quote[2-9]\\.datawire\\.io$`; and to -- the `quote1` service otherwise. - -Note that enclosing regular expressions in quotes can be important to prevent backslashes from being doubled. - -## Using `host_rewrite` - -By default, the `Host` header is not altered when talking to the service -- whatever `Host` header the client gave to $productName$ will be presented to the service. For many microservices, this will be fine, but if you use $productName$ to route to services that use the `Host` header for routing, it's likely to fail (legacy monoliths are particularly susceptible to this, as well as external services). You can use `host_rewrite` to force the `Host` header to whatever value that such target services need. - -An example: the default $productName$ configuration includes the following mapping for `httpbin.org`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin -spec: - prefix: /httpbin/ - service: httpbin.org:80 - host_rewrite: httpbin.org -``` - -As it happens, `httpbin.org` is virtually hosted, and it simply _will not_ function without a `Host` header of `httpbin.org`, which means that the `host_rewrite` attribute is necessary here. - -## `host` and `method` - -Internally: - -- the `host` attribute becomes a `header` match on the `:authority` header; and -- the `method` attribute becomes a `header` match on the `:method` header. - -You will see these headers in the diagnostic service if you use the `method` or `host` attributes. diff --git a/content/en/docs/3.1/topics/using/headers/remove_request_headers.md b/content/en/docs/3.1/topics/using/headers/remove_request_headers.md deleted file mode 100644 index 62603756..00000000 --- a/content/en/docs/3.1/topics/using/headers/remove_request_headers.md +++ /dev/null @@ -1,57 +0,0 @@ -# Remove request headers - -$productName$ can remove a list of HTTP headers that would be sent to the upstream from the request. - -## The `remove_request_headers` attribute - -The `remove_request_headers` attribute takes a list of keys used to match to the header. - -`remove_request_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -## Mapping example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - remove_request_headers: - - authorization - service: quote -``` - -will drop the header with key `authorization`. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - remove_request_headers: - - authorization ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - prefix: /backend2/ - service: quote -``` - -This is the same as the mapping example, but the headers will be removed for both mappings. diff --git a/content/en/docs/3.1/topics/using/headers/remove_response_headers.md b/content/en/docs/3.1/topics/using/headers/remove_response_headers.md deleted file mode 100644 index 16b18569..00000000 --- a/content/en/docs/3.1/topics/using/headers/remove_response_headers.md +++ /dev/null @@ -1,57 +0,0 @@ -# Remove response headers - -$productName$ can remove a list of HTTP headers that would be sent to the client in the response (e.g. default `x-envoy-upstream-service-time`). - -## The `remove_response_headers` attribute - -The `remove_response_headers` attribute takes a list of keys used to match to the header. - -`remove_request_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -## Mapping example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - remove_response_headers: - - x-envoy-upstream-service-time - service: quote -``` - -will drop the header with key `x-envoy-upstream-service-time`. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - remove_response_headers: - - x-envoy-upstream-service-time ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - prefix: /backend2/ - service: quote -``` - -This is the same as the mapping example, but the headers will be removed for both mappings. diff --git a/content/en/docs/3.1/topics/using/index.md b/content/en/docs/3.1/topics/using/index.md deleted file mode 100644 index a996249e..00000000 --- a/content/en/docs/3.1/topics/using/index.md +++ /dev/null @@ -1,32 +0,0 @@ -# Using $productName$ - -Application development teams use $productName$ to manage edge policies associated with a specific service. This section of the documentation covers core $productName$ elements that are typically used by the application development team. - -* [Introduction to Mappings](intro-mappings) The `Mapping` resource is the core resource used by every application development team. -* Mapping Configuration: - * [Automatic Retries](retries) - * [Canary Releases](canary) - * [Circuit Breakers](circuit-breakers) - * [Cross Origin Resource Sharing](cors) - * HTTP Headers - * [Header-based Routing](headers/headers) - * [Host Header](headers/host) - * [Adding Request Headers](headers/add_request_headers) - * [Adding Response Headers](headers/add_response_headers) - * [Removing Request Headers](headers/remove_request_headers) - * [Remove Response Headers](headers/remove_response_headers) - * [Query Parameter Based Routing](query_parameters) - * [Keepalive](keepalive) - * Protocols - * [TCP](tcpmappings) - * gRPC, HTTP/1.0, gRPC-Web, WebSockets - * [RegEx-based Routing](prefix_regex) - * [Redirects](redirects) - * [Rewrites](rewrites) - * [Timeouts](timeouts) - * [Traffic Shadowing](shadowing) -* [Advanced Mapping Configuration](mappings) -* Rate Limiting - * [Introduction to Rate Limits](rate-limits/) -* [Developer Portal](../../tutorials/dev-portal-tutorial) -* [Gateway API](gateway-api) diff --git a/content/en/docs/3.1/topics/using/intro-mappings.md b/content/en/docs/3.1/topics/using/intro-mappings.md deleted file mode 100644 index 51656052..00000000 --- a/content/en/docs/3.1/topics/using/intro-mappings.md +++ /dev/null @@ -1,148 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Introduction to the Mapping resource - -$productName$ is designed around a [declarative, self-service management model](../../concepts/gitops-continuous-delivery). The core resource used to support application development teams who need to manage the edge with $productName$ is the `Mapping` resource. - - - Remember that Listener and Host resources are -  required for a functioning $productName$ installation that can route traffic!
- Learn more about Listener.
- Learn more about Host. - - -## Quick example - -At its core a `Mapping` resource maps a `resource` to a `service`: - -| Required attribute | Description | -| :------------------------ | :------------------------ | -| `name` | is a string identifying the `Mapping` (e.g. in diagnostics) | -| [`prefix`](#resources) | is the URL prefix identifying your [resource](#resources) | -| [`service`](#services) | is the name of the [service](#services) handling the resource; must include the namespace (e.g. `myservice.othernamespace`) if the service is in a different namespace than $productName$ | - -These resources are defined as Kubernetes Custom Resource Definitions. Here's a simple example that maps all requests to `/httpbin/` to the `httpbin.org` web service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin-mapping -spec: - prefix: /httpbin/ - service: http://httpbin.org -``` - -## Applying a Mapping resource - -A `Mapping` resource can be managed using the same workflow as any other Kubernetes resources (e.g., `service`, `deployment`). For example, if the above `Mapping` is saved into a file called `httpbin-mapping.yaml`, the following command will apply the configuration directly to $productName$: - -``` -kubectl apply -f httpbin-mapping.yaml -``` - -For production use, the general recommended best practice is to store the file in a version control system and apply the changes with a continuous deployment pipeline. For more detail, see [the Ambassador Operating Model](../../concepts/gitops-continuous-delivery). - -## Extending Mappings - -`Mapping` resources support a rich set of annotations to customize the specific routing behavior. Here's an example service for implementing the CQRS pattern (using HTTP): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-get -spec: - prefix: /cqrs/ - method: GET - service: getcqrs ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-put -spec: - prefix: /cqrs/ - method: PUT - service: putcqrs -``` - -More detail on each of the available annotations are discussed in subsequent sections. - -## Resources - -To $productName$, a `resource` is a group of one or more URLs that all share a common prefix in the URL path. For example: - -``` -https://ambassador.example.com/resource1/foo -https://ambassador.example.com/resource1/bar -https://ambassador.example.com/resource1/baz/zing -https://ambassador.example.com/resource1/baz/zung -``` - -all share the `/resource1/` path prefix, so it can be considered a single resource. On the other hand: - -``` -https://ambassador.example.com/resource1/foo -https://ambassador.example.com/resource2/bar -https://ambassador.example.com/resource3/baz/zing -https://ambassador.example.com/resource4/baz/zung -``` - -share only the prefix `/` -- you _could_ tell $productName$ to treat them as a single resource, but it's probably not terribly useful. - -Note that the length of the prefix doesn't matter: if you want to use prefixes like `/v1/this/is/my/very/long/resource/name/`, go right ahead, $productName$ can handle it. - -Also note that $productName$ does not actually require the prefix to start and end with `/` -- however, in practice, it's a good idea. Specifying a prefix of - -``` -/man -``` - -would match all of the following: - -``` -https://ambassador.example.com/man/foo -https://ambassador.example.com/mankind -https://ambassador.example.com/man-it-is/really-hot-today -https://ambassador.example.com/manohmanohman -``` - -which is probably not what was intended. - -## Services - -$productName$ routes traffic to a `service`. A `service` is defined as: - -``` -[scheme://]service[.namespace][:port] -``` - -Where everything except for the `service` is optional. - -- `scheme` can be either `http` or `https`; if not present, the default is `http`. -- `service` is the name of a service (typically the service name in Kubernetes or Consul); it is not allowed to contain the `.` character. -- `namespace` is the namespace in which the service is running. Starting with $productName$ 1.0.0, if not supplied, it defaults to the namespace in which the Mapping resource is defined. The default behavior can be configured using the [`ambassador` Module](../../running/ambassador). When using a Consul resolver, `namespace` is not allowed. -- `port` is the port to which a request should be sent. If not specified, it defaults to `80` when the scheme is `http` or `443` when the scheme is `https`. Note that the [resolver](../../running/resolvers) may return a port in which case the `port` setting is ignored. - -Note that while using `service.namespace.svc.cluster.local` may work for Kubernetes resolvers, the preferred syntax is `service.namespace`. - -## Best practices for configuration - -$productName$'s configuration is assembled from multiple YAML blocks which are managed by independent application teams. This implies: - -- $productName$'s configuration should be under version control. - - While you can always read back the $productName$'s configuration from Kubernetes or its diagnostic service, the $productName$ will not do versioning for you. - -- Be aware that the $productName$ tries to not start with a broken configuration, but it's not perfect. - - Gross errors will result in $productName$ refusing to start, in which case `kubectl logs` will be helpful. However, it's always possible to e.g. map a resource to the wrong service, or use the wrong `rewrite` rules. $productName$ can't detect that on its own, although its diagnostic pages can help you figure it out. - -- Be careful of mapping collisions. - - If two different developers try to map `/user/` to something, this can lead to unexpected behavior. $productName$'s canary-deployment logic means that it's more likely that traffic will be split between them than that it will throw an error -- again, the diagnostic service can help you here. - -**Note:** Unless specified, mapping attributes cannot be applied to any other resource type. diff --git a/content/en/docs/3.1/topics/using/keepalive.md b/content/en/docs/3.1/topics/using/keepalive.md deleted file mode 100644 index d75e96ba..00000000 --- a/content/en/docs/3.1/topics/using/keepalive.md +++ /dev/null @@ -1,70 +0,0 @@ -# Keepalive - -Keepalive option indicates whether `SO_KEEPALIVE` on the socket should be enabled. - -## Keepalive configuration - -Keepalive configuration can be set for all $productName$ mappings in the [`ambassador Module`](../../running/ambassador) or set per [`Mapping`](../mappings). - -The `keepalive` attribute configures keepalive. The following fields are supported: - -```yaml -keepalive: - idle_time: - interval: - probes: -``` - -### `idle_time` - -(Default: `7200`) The number of seconds a connection needs to be idle before keep-alive probes start being sent. - -### `interval` - -(Default: `75`) The number of seconds between keep-alive probes. - -### `probes` - -(Default: `9`) is the maximum number of keepalive probes to send without response before deciding the connection is dead. - -## Examples - -Keepalive probes defined on a single mapping: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - keepalive: - idle_time: 100 - interval: 10 - probes: 9 -``` - -A global keepalive configuration: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - keepalive: - idle_time: 100 - interval: 10 - probes: 9 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote -``` diff --git a/content/en/docs/3.1/topics/using/mappings.md b/content/en/docs/3.1/topics/using/mappings.md deleted file mode 100644 index f930fc62..00000000 --- a/content/en/docs/3.1/topics/using/mappings.md +++ /dev/null @@ -1,189 +0,0 @@ -# Advanced Mapping configuration - -$productName$ is designed so that the author of a given Kubernetes service can easily and flexibly configure how traffic gets routed to the service. The core abstraction used to support service authors is a mapping, which maps a target backend service to a given host or prefix. For Layer 7 protocols such as HTTP, gRPC, or WebSockets, the `Mapping` resource is used. For TCP, the `TCPMapping` resource is used. - -$productName$ _must_ have one or more mappings defined to provide access to any services at all. The name of the mapping must be unique. - -## System-wide defaults for Mappings - -Certain aspects of mappings can be set system-wide using the `defaults` element of the `ambassador Module`: -see [using defaults](../../using/defaults) for more information. The `Mapping` element will look first in -the `httpmapping` default class. - -## Mapping evaluation order - -$productName$ sorts mappings such that those that are more highly constrained are evaluated before those less highly constrained. The prefix length, the request method, constraint headers, and query parameters are all taken into account. - -If absolutely necessary, you can manually set a `precedence` on the mapping (see below). In general, you should not need to use this feature unless you're using the `regex_headers` or `host_regex` matching features. If there's any question about how $productName$ is ordering rules, the diagnostic service is a good first place to look: the order in which mappings appear in the diagnostic service is the order in which they are evaluated. - -## Optional fallback Mapping - -$productName$ will respond with a `404 Not Found` to any request for which no mapping exists. If desired, you can define a fallback "catch-all" mapping so all unmatched requests will be sent to an upstream service. - -For example, defining a mapping with only a `/` prefix will catch all requests previously unhandled and forward them to an external service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: catch-all -spec: - prefix: / - service: https://www.getambassador.io -``` - -### Using `precedence` - -$productName$ sorts mappings such that those that are more highly constrained are evaluated before those less highly constrained. The prefix length, the request method, and the constraint headers are all taken into account. These mechanisms, however, may not be sufficient to guarantee the correct ordering when regular expressions or highly complex constraints are in play. - -For those situations, a `Mapping` can explicitly specify the `precedence`. A `Mapping` with no `precedence` is assumed to have a `precedence` of 0; the higher the `precedence` value, the earlier the `Mapping` is attempted. - -If multiple `Mapping`s have the same `precedence`, $productName$'s normal sorting determines the ordering within the `precedence`; however, there is no way that $productName$ can ever sort a `Mapping` with a lower `precedence` ahead of one at a higher `precedence`. - -### Using `tls` - -To originate TLS, use a `service` with an `https://` prefix. By itself, this will cause $productName$ to originate TLS without presenting a client certificate to the upstream service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-no-cert -spec: - prefix: /prefix/ - service: https://upstream/ -``` - -If you do need to supply a client certificate, you will also need to set `tls` to the name of a defined TLS context. The client certificate given in that context will be presented to the upstream service. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-with-cert -spec: - prefix: /prefix/ - service: https://upstream/ - tls: upstream-cert-context -``` - -(If `tls` is present, $productName$ will originate TLS even if the `service` does not have an `https://` prefix.) - -### Using `cluster_tag` - -If the `cluster_tag` attribute is present, its value will be prepended to cluster names generated from -the `Mapping`. This provides a simple mechanism for customizing the `cluster` name when working with metrics. - -## Using `dns_type` - -If the `dns_type` attribute is present, its value will determine how the DNS is used when locating the upstream service. Valid values are: - -- `strict_dns` (the default): The DNS result is assumed to define the exact membership of the cluster. For example, if DNS returns three IP addresses, the cluster is assumed to have three distinct upstream hosts. If a successful DNS query returns no hosts, the cluster is assumed to be empty. `strict_dns` makes sense for situations like a Kubernetes service, where DNS resolution is fast and returns a relatively small number of IP addresses. - -- `logical_dns`: Instead of assuming that the DNS result defines the full membership of the cluster, every new connection simply uses the first IP address returned by DNS. `logical_dns` makes sense for a service with a large number of IP addresses using round-robin DNS for upstream load balancing: typically each DNS query returns a different first result, and it is not necessarily possible to know the full membership of the cluster. With `logical_dns`, no attempt is made to garbage-collect connections: they will stay open until the upstream closes them. - -If `dns_type` is not given, `strict_dns` is the default, as this is the most conservative choice. When interacting with large web services with many IP addresses, switching to `logical_dns` may be a better choice. For more on the different types of DNS, see the [`strict_dns` Envoy documentation] or the [`logical_dns` Envoy documentation]. - -[`strict_dns` Envoy documentation]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/service_discovery#strict-dns -[`logical_dns` Envoy documentation]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/service_discovery#logical-dns - - -## Namespaces and Mappings - -If `AMBASSADOR_NAMESPACE` is correctly set, $productName$ can map to services in other namespaces by taking advantage of Kubernetes DNS: - -- `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. - -### Linkerd interoperability (`add_linkerd_headers`) - -When using Linkerd, requests going to an upstream service need to include the `l5d-dst-override` header to ensure that Linkerd will route them correctly. Setting `add_linkerd_headers` does this automatically, based on the `service` attribute in the `Mapping`. - -If `add_linkerd_headers` is not specified for a given `Mapping`, the default is taken from the `ambassador`[Module](../../running/ambassador). The overall default is `false`: you must explicitly enable `add_linkerd_headers` for $productName$ to add the header for you (although you can always add it yourself with `add_request_headers`, of course). - -### "Upgrading" to non-HTTP protocols (`allow_upgrade`) - -HTTP has [a mechanism][upgrade-mechanism] where the client can say -`Connection: upgrade` / `Upgrade: PROTOCOL` to switch ("upgrade") from -the current HTTP version to a different one, or even a different -protocol entirely. $productName$ itself understands and can handle the -different HTTP versions, but for other protocols you need to tell -$productName$ to get out of the way, and let the client speak that -protocol directly with your upstream service. You can do this by -setting the `allow_upgrade` field to a case-insensitive list of -protocol names $productName$ will allow switching to from HTTP. After -the upgrade, $productName$ does not interpret the traffic, and behaves -similarly to how it does for `TCPMapping`s. - -[upgrade-mechanism]: https://tools.ietf.org/html/rfc7230#section-6.7 - -This "upgrade" mechanism is a useful way of adding HTTP-based -authentication and access control to another protocol that might not -support authentication; for this reason the designers of the WebSocket -protocol made this "upgrade" mechanism the *only* way of initiating a -WebSocket connection. In a Mapping for an upstream service that -supports WebSockets, you would write - -```yaml -allow_upgrade: -- websocket -``` - -The Kubernetes apiserver itself uses this "upgrade" mechanism to -perform HTTP authentication before switching to SPDY for endpoint used -by `kubectl exec`; if you wanted to use $productName$ to expose the -Kubernetes apiserver such that `kubectl exec` functions, you would -write - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: apiserver -spec: - hostname: "*" - service: https://kubernetes.default - prefix: / - allow_upgrade: - - spdy/3.1 -``` - -There is a deprecated setting `use_websocket`; setting `use_websocket: -true` is equivalent to setting `allow_upgrade: ["websocket"]`. - -## DNS configuration for Mappings - -`respect_dns_ttl` can be set to `true` to force the DNS refresh rate for this `Mapping` to be set to the record’s TTL obtained from DNS resolution. -- Allowed values: `true` or `false` -- Default: `false` - - -`dns_type` can be used to configure the service discovery type between Strict DNS and Logical DNS. You can -- Allowed values: - - `strict_dns`: Ambassador will continuously and asynchronously resolve the specified DNS targets. - - `logical_dns`: Similar to `strict_dns`, but only uses the first IP address returned when a new connection needs to be initiated and Connections are never drained. More optimal for large scale web services that must be accessed via DNS. -- Default: `strict_dns` - - -For more information on the differences between dns types, see [the Envoy documentation for service discovery](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/service_discovery.html). - -> **Note:** When the [endpoint resolver](../../running/resolvers/#the-kubernetes-endpoint-resolver) is used in a `Mapping`, `dns_type` will be ignored in favor of the endpoint resolver's service discovery. - - - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: dnsoverwrite -spec: - service: quote - prefix: /backend/ - dns_type: logical_dns - respect_dns_ttl: true -``` diff --git a/content/en/docs/3.1/topics/using/method.md b/content/en/docs/3.1/topics/using/method.md deleted file mode 100644 index 94185dcd..00000000 --- a/content/en/docs/3.1/topics/using/method.md +++ /dev/null @@ -1,26 +0,0 @@ -# Method-based routing - -$productName$ supports routing based on the HTTP method and regular expression. - -## Using `method` - -The `method` annotation specifies the specific HTTP method for a mapping. The value of the `method` annotation must be in all upper case. - -For example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: get -spec: - hostname: "*" - prefix: /backend/get_only/ - method: GET - service: quote -``` - -## Using `method_regex` - -When `method_regex` is set to `true`, the value of the `method` annotation will be interpreted as a regular expression. diff --git a/content/en/docs/3.1/topics/using/prefix_regex.md b/content/en/docs/3.1/topics/using/prefix_regex.md deleted file mode 100644 index 04a6e4b8..00000000 --- a/content/en/docs/3.1/topics/using/prefix_regex.md +++ /dev/null @@ -1,25 +0,0 @@ -# Prefix regex - -## Using `prefix` and `prefix_regex` - -When the `prefix_regex` attribute is set to `true`, $productName$ configures a [regex route](https://www.envoyproxy.io/docs/envoy/v1.5.0/api-v1/route_config/route#route) instead of a prefix route in Envoy. **This means the entire path must match the regex specified, not only the prefix.** - -## Example with a version in the URL - -If the version is a path parameter and the resources are served by different services, then - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: qotm -spec: - prefix: "/(v1|v2)/qotm/.*" - prefix_regex: true - service: qotm -``` - -will map requests to both `/v1` and `/v2` to the `qotm` service. - -Note that enclosing regular expressions in quotes can be important to prevent backslashes from being doubled. diff --git a/content/en/docs/3.1/topics/using/query-parameters.md b/content/en/docs/3.1/topics/using/query-parameters.md deleted file mode 100644 index 6b880fd4..00000000 --- a/content/en/docs/3.1/topics/using/query-parameters.md +++ /dev/null @@ -1,69 +0,0 @@ -# Query parameter-based routing - -$productName$ can route to target services based on HTTP query parameters with the `query_parameters` and `regex_query_parameters` specifications. Multiple mappings with different annotations can be applied to construct more complex routing rules. - -## The `query_parameters` annotation - -The `query_parameters` attribute is a dictionary of `query_parameter`: `value` pairs. $productName$ will only allow requests that match the specified `query_parameter`: `value` pairs to reach the target service. - -You can also set the `value` of a query parameter to `true` to test for the existence of a query parameter. - -### A basic example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - query_parameters: - quote-mode: backend - random-query-parameter: datawire -``` - -This will allow requests to /backend/ to succeed only if the `quote-mode` query parameter has the value `backend` and the `random-query-parameter` has the value `datawire`. - -## `regex_query_parameters` - -The following mapping will route requests with the `quote-mode` header that contain values that match the regex. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - regex_query_parameters: - quote-mode: "^[a-z].*" - prefix: /backend/ - service: quote -``` - -### A conditional example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-mode -spec: - prefix: /backend/ - service: quote-mode - regex_query_parameters: - quote-mode: .* ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-regular -spec: - prefix: /backend/ - service: quote-regular -``` - -This will send requests that contain the `quote-mode` query parameter (with any value) to the `quote-mode` target, while routing all other requests to the `quote-regular` target. diff --git a/content/en/docs/3.1/topics/using/rate-limits/index.md b/content/en/docs/3.1/topics/using/rate-limits/index.md deleted file mode 100644 index b65f8c5d..00000000 --- a/content/en/docs/3.1/topics/using/rate-limits/index.md +++ /dev/null @@ -1,199 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Basic rate limiting - -Rate limiting in $productName$ is composed of two parts: - -* The [`RateLimitService`](../../running/services/rate-limit-service) resource tells $productName$ what external service - to use for rate limiting. - - If $productName$ cannot contact the rate limit service, it will allow the request to be processed as if there were no rate limit service configuration. - -* _Labels_ that get attached to requests. A label is basic metadata that - is used by the `RateLimitService` to decide which limits to apply to - the request. - - - These labels require Mapping resources with apiVersion - getambassador.io/v2 or newer — if you're updating an old installation, check the - apiVersion! - - -Labels are grouped according to _domain_ and _group_: - -```yaml -labels: - "domain1": - - "group1": - - "my_label_specifier_1" - - "my_label_specifier_2" - - "group2": - - "my_label_specifier_3" - - "my_label_specifier_4" - "domain2": - - ... -``` - -The names of domains and groups are not interpreted by $productName$ in any way: -they are solely there to help configuration authors remember the different groupings. -Note that **at present, rate limiting supports just one domain**: the name of the -domain must be configured in the [`RateLimitService`](../../running/services/rate-limit-service). - - - -## Attaching labels to requests - -There are two ways of setting labels on a request: - -1. You can set labels on an individual [`Mapping`](../mappings). These labels - will only apply to requests that use that `Mapping`. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Mapping - metadata: - name: foo-mapping - spec: - hostname: "*" - prefix: /foo/ - service: foo - labels: - "domain1": - - "group1": - - "my_label_specifier_1" - - "my_label_specifier_2" - - "group2": - - "my_label_specifier_3" - - "my_label_specifier_4" - "domain2": - - ... - ``` - -2. You can set global labels in the [`ambassador` `Module`](../../running/ambassador). - These labels will apply to _every_ request that goes through $productName$. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - spec: - config: - default_labels: - "domain1": - defaults: - - "my_label_specifier_a" - - "my_label_specifier_b" - "domain2": - defaults: - - "my_label_specifier_c" - - "my_label_specifier_d" - ``` - - If a `Mapping` and the defaults both give label groups for the same domain, the - default labels are prepended to each label group from the `Mapping`. If the `Mapping` - does not give any labels for that domain, the global labels are placed into a new - label group named "default" for that domain. - -Each label group is a list of labels; each label is a key/value pair. Since the label -group is a list rather than a map: -- it is possible to have multiple labels with the same key, and -- the order of labels matters. - -> Note: The terminology used by the Envoy documentation differs from -> the terminology used by $productName$: -> -> | $productName$ | Envoy | -> |-----------------|-------------------| -> | label group | descriptor | -> | label | descriptor entry | -> | label specifier | rate limit action | - -The `Mapping`s' listing of the groups of specifiers have names for the -groups; the group names are useful for humans dealing with the YAML, -but are ignored by $productName$, all $productName$ cares about are the -*contents* of the groupings of label specifiers. - -There are 5 types of label specifiers in $productName$: - - - -1. `source_cluster` - - ```yaml - source_cluster: - key: source_cluster - ``` - - Sets the label `source_cluster=«Envoy source cluster name»"`. The Envoy - source cluster name is the name of the Envoy cluster that the request came - in on. - - The syntax of this label currently _requires_ `source_cluster: {}`. - -2. `destination_cluster` - - ```yaml - destination_cluster: - key: destination_cluster - ``` - - Sets the label `destination_cluster=«Envoy destination cluster name»"`. The Envoy - destination cluster name is the name of the Envoy cluster to which the `Mapping` - routes the request. You can get the name for a cluster from the - [diagnostics service](../../running/diagnostics). - - The syntax of this label currently _requires_ `destination_cluster: {}`. - -3. `remote_address` - - ```yaml - remote_address: - key: remote_address - ``` - - Sets the label `remote_address=«IP address of the client»"`. The IP address of - the client will be taken from the `X-Forwarded-For` header, to correctly manage - situations with L7 proxies. This requires that $productName$ be correctly - [configured to communicate](../../../howtos/configure-communications). - - The syntax of this label currently _requires_ `remote_address: {}`. - -4. `request_headers` - - ```yaml - request_headers: - header_name: "header-name" - key: mykey - ``` - - If a header named `header-name` is present, set the label `mykey=«value of the header»`. - If no header named `header-name` is present, **the entire label group is dropped**. - -5. `generic_key` - - ```yaml - generic_key: - key: mykey - value: myvalue - ``` - - Sets the label `«mykey»=«myval»`. Note that supplying a `key` is supported only - with the Envoy V3 API. - -## Rate limiting requests based on their labels - -This is determined by your `RateLimitService` implementation. See the -[Basic Rate Limiting tutorial](../../../howtos/rate-limiting-tutorial) for an -example `RateLimitService` implementation for $productName$. - -If you'd rather not write your own `RateLimitService` implementation, -$AESproductName$ provides a `RateLimitService` implementation that is -configured by a `RateLimit` custom resource. See the -[$AESproductName$ RateLimit Reference](/docs/edge-stack/latest/topics/using/rate-limits/rate-limits/) -for more information. diff --git a/content/en/docs/3.1/topics/using/redirects.md b/content/en/docs/3.1/topics/using/redirects.md deleted file mode 100644 index f55c467d..00000000 --- a/content/en/docs/3.1/topics/using/redirects.md +++ /dev/null @@ -1,142 +0,0 @@ -# Redirects - -$productName$ can perform 3xx redirects on `Mapping`s to a different host, with various options to redirect the path and to return a different 3xx response code instead of the default 301. - -## Schema - -| Name | Type | Description | -| --- | --- | --- | -| `spec.host_redirect` | Boolean | This is *required* to be set to `true` to use any type of redirect, otherwise the request will be proxied instead of redirected. | -| `spec.path_redirect` | String | Optional, changes the path for the redirect. | -| `spec.prefix_redirect` | String | Optional, matches the `prefix` value and replaces it with the `prefix_redirect` value. | -| `spec.regex_redirect` | String | Optional, uses regex to match and replace the `prefix` value. | -| `spec.redirect_response_code` | Integer | Optional, changes the response code from the default 301, valid values are 301, 302, 303, 307, and 308. | -| `spec.config. x_forwarded_proto_redirect` | Boolean | Redirect only the originating HTTP requests to HTTPS, allowing the originating HTTPS requests to pass through. | -| `spec.config. use_remote_address` | Boolean | Required to be set to `false` to use the `x_forwarded_proto_redirect` feature. | - -## Examples - -### Basic redirect - -To effect any type of HTTP `Redirect`, the `Mapping` *must* set `host_redirect` to `true`, with `service` set to the host to which the client should be redirected: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - prefix: /redirect/ - service: httpbin.org - host_redirect: true - hostname: '*' -``` - -Using this `Mapping`, a request to `http://$AMBASSADOR_URL/redirect/` will be redirected to `http://httpbin.org/redirect/`. - -> As always with $productName$, the trailing `/` on any URL with a -`Mapping` is required! - -### Path redirect - -The `Mapping` may optionally also set additional properties to customize the behavior of the HTTP redirect response. - -To also change the path portion of the URL during the redirect, set `path_redirect`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - hostname: '*' - prefix: /redirect/ - service: httpbin.org - host_redirect: true - path_redirect: /ip -``` - -Here, a request to `http://$AMBASSADOR_URL/redirect/` will be redirected to `http://httpbin.org/ip/`. - -### Prefix redirect - -To change only a prefix of the path portion of the URL, set `prefix_redirect`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - hostname: '*' - prefix: /redirect/path/ - service: httpbin.org - host_redirect: true - prefix_redirect: /ip -``` - -Now, a request to `http://$AMBASSADOR_URL/redirect/path/` will be redirected to `http://httpbin.org/ip/`. The prefix `/redirect/path/` was matched and replaced with `/ip/`. - -### Regex redirect - -`regex_redirect` matches a regular expression to replace instead of a fixed prefix. -[See more information about using regex with $productName$](../rewrites/#regex_rewrite). - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - prefix: /foo/ - service: httpbin.org - host_redirect: true - regex_redirect: - pattern: '/foo/([0-9]*)/list' - substitution: '/bar/\1' -``` -A request to `http://$AMBASSADOR_URL/foo/12345/list` will be redirected to -`http://$AMBASSADOR_URL/bar/12345`. - -### Redirect response code - -To change the HTTP response code return by $productName$, set `redirect_reponse_code`. If this is not set, 301 is returned by default. Valid values include 301, 302, 303, 307, and 308. This -can be used with any type of redirect. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - prefix: /ip/ - service: httpbin.org - host_redirect: true - redirect_response_code: 302 -``` - -A request to `http://$AMBASSADOR_URL/ip/` will result in an HTTP 302 redirect to `http://httpbin.org/ip`. - -### X-FORWARDED-PROTO redirect - -In cases when TLS is being terminated at an external layer 7 load balancer, then you would want to redirect only the originating HTTP requests to HTTPS, and let the originating HTTPS requests pass through. - -This distinction between an originating HTTP request and an originating HTTPS request is done based on the `X-FORWARDED-PROTO` header that the external layer 7 load balancer adds to every request it forwards after TLS termination. - -To enable this `X-FORWARDED-PROTO` based HTTP to HTTPS redirection, add a `x_forwarded_proto_redirect: true` field to `ambassador Module`'s configuration. Note that when this feature is enabled `use_remote_address` MUST be set to false. - -An example configuration is as follows - - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - x_forwarded_proto_redirect: true - use_remote_address: false -``` - -Note: Setting `x_forwarded_proto_redirect: true` will impact all your $productName$ mappings. Every HTTP request to $productName$ will only be allowed to pass if it has an `X-FORWARDED-PROTO: https` header. diff --git a/content/en/docs/3.1/topics/using/retries.md b/content/en/docs/3.1/topics/using/retries.md deleted file mode 100644 index d018ab59..00000000 --- a/content/en/docs/3.1/topics/using/retries.md +++ /dev/null @@ -1,84 +0,0 @@ -# Automatic retries - -Sometimes requests fail. When these requests fail for transient issues, $productName$ can automatically retry the request. - -Retry policy can be set for all $productName$ mappings in the [`ambassador Module`](../../running/ambassador), or set per [`Mapping`](../mappings). Generally speaking, you should set `retry_policy` on a per mapping basis. Global retries can easily result in unexpected cascade failures. - -> Note that when setting `retry_policy`, adjusting `max_retries` in the [circuit breaker](https://www.getambassador.io/docs/edge-stack/pre-release/topics/using/circuit-breakers/) configuration should also be considered in order to account for all desired retries. - -## Configuring retries - -The `retry_policy` attribute configures automatic retries. The following fields are supported: - -```yaml -retry_policy: - retry_on: - num_retries: - per_try_timeout: -``` - -### `retry_on` - -(Required) Specifies the condition under which $productName$ retries a failed request. - -| Value | Description | -| --- | --- | -|`5xx`| Retries if the upstream service responds with any 5xx code or does not respond at all -|`gateway-error`| Similar to a `5xx` but only applies to a 502, 503, or 504 response -|`connect-failure`| Retries on a connection failure to the upstream service (included in `5xx`) -|`retriable-4xx`| Retries on a retriable 4xx response (currently only 409) -|`refused-stream`| Retires if the upstream service sends a REFUSED_STREAM error (included in `5xx`) -|`retriable-status-codes`| Retries based on status codes set in the `x-envoy-retriable-status-codes` header. If that header isn't set, $productName$ will not retry the request. - - For more details on each of these values, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/v1.9.0/configuration/http_filters/router_filter#x-envoy-retry-on). - -### `num_retries` - -(Default: 1) Specifies the number of retries to execute for a failed request. - -### `per_try_timeout` - -(Default: global request timeout) Specify the timeout for each retry. Must be in seconds or nanoseconds, e.g., `1s`, `1500ns`. - -## Examples - -A per mapping retry policy: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - retry_policy: - retry_on: "5xx" - num_retries: 10 -``` - -A global retry policy (not recommended): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - retry_policy: - retry_on: "retriable-4xx" - num_retries: 4 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - hostname: '*' -``` diff --git a/content/en/docs/3.1/topics/using/rewrites.md b/content/en/docs/3.1/topics/using/rewrites.md deleted file mode 100644 index 44d0a961..00000000 --- a/content/en/docs/3.1/topics/using/rewrites.md +++ /dev/null @@ -1,100 +0,0 @@ -# Rewrites - -Once $productName$ uses a prefix to identify the service to which a given request should be passed, it can rewrite the URL before handing it off to the service. - -There are two approaches for rewriting: `rewrite` for simpler scenarios and `regex_rewrite` for more advanced rewriting. - -**Please note that** only one of these two can be configured for a mapping **at the same time**. As a result $productName$ ignores `rewrite` when `regex_rewrite` is provided. - -## `rewrite` - -By default, the `prefix` is rewritten to `/`, so e.g., if we map `/backend-api/` to the service `service1`, then - - -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/content/en/docs/3.1/topics/using/shadowing.md b/content/en/docs/3.1/topics/using/shadowing.md deleted file mode 100644 index 4a0201a6..00000000 --- a/content/en/docs/3.1/topics/using/shadowing.md +++ /dev/null @@ -1,78 +0,0 @@ -# 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. - -Shadowing - -## 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/content/en/docs/3.1/topics/using/tcpmappings.md b/content/en/docs/3.1/topics/using/tcpmappings.md deleted file mode 100644 index 37a6eb7a..00000000 --- a/content/en/docs/3.1/topics/using/tcpmappings.md +++ /dev/null @@ -1,225 +0,0 @@ -# TCP connections - -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`. - -## TCPMapping - -An $productName$ `TCPMapping` associates TCP connections with Kubernetes _services_. Cleartext TCP connections are defined by destination IP address and/or destination TCP port; TLS TCP connections can also be defined by the hostname presented using SNI. A service is exactly the same as in Kubernetes. - -## TCPMapping configuration - -$productName$ supports a number of attributes to configure and customize mappings. - -| Attribute | Description | -| :------------------------ | :------------------------ | -| `address` | (optional) the IP address on which $productName$ should listen for connections for this Mapping -- if not present, $productName$ will listen on all addresses ) -| `port` | (required) the TCP port on which $productName$ should listen for connections for this Mapping | -| `idle_timeout_ms` | (optional) the timeout, in milliseconds, after which the connection will be terminated if no traffic is seen -- if not present, no timeout is applied | -| `enable_ipv4` | (optional) if true, enables IPv4 DNS lookups for this mapping's service (the default is set by the [`ambassador Module`](../../running/ambassador)) | -| `enable_ipv6` | (optional) if true, enables IPv6 DNS lookups for this mapping's service (the default is set by the [`ambassador Module`](../../running/ambassador)) | -| `circuit_breakers` | (optional) circuit breakers, as for [`HTTP mapping`](../circuit-breakers) (the default is set by the [`ambassador Module`](../../running/ambassador)) | - -If both `enable_ipv4` and `enable_ipv6` are set, $productName$ will prefer IPv6 to IPv4. See the [`ambassador Module`](../../running/ambassador) documentation for more information. - -$productName$ can manage TCP connections using TLS: - -| Attribute | Description | -| :------------------------ | :------------------------ | -| [`host`](../headers/host) | (optional) enables TLS _termination_ and specifies the hostname that must be presented using SNI for this `TCPMapping` to match -- **FORCES TLS TERMINATION**, see below | -| [`service`](#tcpmapping-and-tls) | An `https://` prefix will enable TLS _origination_ | -| [`tls`](#tcpmapping-and-tls) | (optional) configures TLS _origination_ by specifying the name of a `TLSContext` that will determine the certificate to offer to the upstream service | - -$productName$ supports multiple deployment patterns for your services. These patterns are designed to let you safely release new versions of your service while minimizing its impact on production users. - -| Attribute | Description | -| :------------------------ | :------------------------ | -| [`weight`](../canary) | (optional) specifies the (integer) percentage of traffic for this resource that will be routed using this mapping | - -The name of the mapping must be unique. - -### `TCPMapping` and TLS - -The `host` attribute of a `TCPMapping` determines whether $productName$ will terminate TLS when a client connects. The `service` prefix (if any) and the `tls` attribute work together to determine whether $productName$ will _originate_ TLS. The two are independent. - -This leaves four cases: - -#### `host` is not set, and the `service` does not state `https://` - -In this case, $productName$ simply proxies bytes between the client and the upstream. TLS may or may not be involved, and $productName$ doesn't care. You should specify the port to use for the upstream connection; if you don't, $productName$ will guess port 80. - -Examples: - -```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. - -#### `host` is set, but the `service` has no `https://` prefix - -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 the port to use for the upstream connection; if you don't, $productName$ will guess port **80**. - -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`, and that the termination `TLSContext` has a `host` that matches the `host` in the `TCPMapping`. (This is the same rule as TLS termination with SNI in an HTTP `Mapping`.) - -Example: - -```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 example 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. - -#### `host` is set, and `service` has an `https://` prefix - -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 also set, $productName$ will use to determine the certificate offered to the upstream service. You should specify the port to use for the upstream connection; if you don't, $productName$ will guess port **443**. - -This is useful for doing host routing while maintaining end-to-end encryption. - -Note that this case **requires** that you have created a termination `TLSContext`, and that the termination `TLSContext` has a `host` that matches the `host` in the `TCPMapping`. (This is the same rule as TLS termination with SNI in an HTTP `Mapping`.) - -Example: - -```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 example 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. - -#### `host` is not set, but `service` has an `https://` prefix - -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. - -#### Summary - -- To get a `TCPMapping` to terminate TLS, configure $productName$ with a termination `TLSContext` and list a `host` in the `TCPMapping`. - -- To get a `TCPMapping` to originate TLS, use an `http://` prefix for the `TCPMapping`'s `service`. Use the `tls` attribute as well if you want to offer a certificate to the upstream service. - -- You can mix and match as long as you think about how the protocols interact. - -#### Required attributes for `TCPMapping`s - -- `name` is a string identifying the `Mapping` (e.g. in diagnostics) -- `port` is an integer specifying which port to listen on for connections -- `service` is the name of the service handling the resource; must include the namespace (e.g. `myservice.othernamespace`) if the service is in a different namespace than $productName$ - -Note that the `service` in a `TCPMapping` should include a port number, and may include a scheme of `https`. - -## Namespaces and Mappings - -Given that `AMBASSADOR_NAMESPACE` is correctly set, $productName$ can map to services in other namespaces by taking advantage of Kubernetes DNS: - -- `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. diff --git a/content/en/docs/3.1/topics/using/timeouts.md b/content/en/docs/3.1/topics/using/timeouts.md deleted file mode 100644 index ae004102..00000000 --- a/content/en/docs/3.1/topics/using/timeouts.md +++ /dev/null @@ -1,66 +0,0 @@ -# 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/content/en/docs/3.1/tutorials/dev-portal-tutorial.md b/content/en/docs/3.1/tutorials/dev-portal-tutorial.md deleted file mode 100644 index d3c0d0a8..00000000 --- a/content/en/docs/3.1/tutorials/dev-portal-tutorial.md +++ /dev/null @@ -1,29 +0,0 @@ -# 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:///docs/` to see the -publicly visible Developer Portal. Make sure you include the trailing `/`. -This is a fully customizable portal that you can share with third parties who -need information about your APIs. diff --git a/content/en/docs/3.1/tutorials/getting-started.md b/content/en/docs/3.1/tutorials/getting-started.md deleted file mode 100644 index 014e1f7b..00000000 --- a/content/en/docs/3.1/tutorials/getting-started.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -description: "A simple three step guide to installing $productName$ and quickly get started routing traffic from the edge of your Kubernetes cluster to your services." ---- - -import Alert from '@material-ui/lab/Alert'; -import GettingStartedEmissary21Tabs from './gs-tabs' - -# $productName$ quick start - -
-

Contents

- -- [1. Installation](#1-installation) - - [Connecting your installation to Ambassador Cloud](#connecting-your-installation-to-ambassador-cloud) -- [2. Routing traffic from the edge](#2-routing-traffic-from-the-edge) -- [What's next?](#img-classos-logo-srcimageslogopng-whats-next) - -
- -## 1. Installation - -We'll start by installing $productName$ into your cluster. - -**We recommend using Helm** but there are other options below to choose from. - - - -### Connecting your installation to Ambassador Cloud - -Now is a great moment to connect your new installation to Ambassador Cloud in order to fully leverage the power of $productName$ and the Developer Control Plane (DCP). - -1. Log in to [Ambassador Cloud](https://app.getambassador.io/cloud/services/) with GitHub, GitLab or Google and select your team account. - -2. At the top, click **Add Services** then click **Connection Instructions** in the "Connect your installation" section. - -3. Follow the prompts to name the cluster and click **Generate a Cloud Token**. - -4. Follow the prompts to install the cloud token into your cluster. - -5. When the token installation completes, your services will be listed in the DCP. - -Success! At this point, you have installed $productName$. Now let's get some traffic flowing to your services. - -## 2. Routing traffic from the edge - -$productName$ uses Kubernetes Custom Resource Definitions (CRDs) to declaratively define its desired state. The workflow you are going to build uses a simple demo app, a **`Listener` CRD**, and a **`Mapping` CRD**. The `Listener` CRD tells $productName$ what port to listen on, and the `Mapping` CRD tells $productName$ how to route incoming requests by host and URL path from the edge of your cluster to Kubernetes services. - -1. Start by creating a `Listener` resource for HTTP on port 8080: - - ``` - kubectl apply -f - < - This 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.
-
- Learn more about Listener.
- Learn more about Host. - - -2. Apply the YAML for the "Quote" service. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/quickstart/qotm.yaml - ``` - - The Service and Deployment are created in your default namespace. You can use 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](#connecting-your-installation-to-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` - - ## Mapping editor - - 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 - <Victory! You have created your first $productName$ 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/content/en/docs/3.1/tutorials/gs-tabs.js b/content/en/docs/3.1/tutorials/gs-tabs.js deleted file mode 100644 index eb392504..00000000 --- a/content/en/docs/3.1/tutorials/gs-tabs.js +++ /dev/null @@ -1,131 +0,0 @@ -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 ( - - ); -} - -TabPanel.propTypes = { - children: PropTypes.node, - index: PropTypes.any.isRequired, - value: PropTypes.any.isRequired, -}; - -function a11yProps(index) { - return { - id: `simple-tab-${index}`, - 'aria-controls': `simple-tabpanel-${index}`, - }; -} - -const useStyles = makeStyles((theme) => ({ - root: { - flexGrow: 1, - backgroundColor: 'transparent', - }, -})); - -export default function GettingStartedEmissary21Tabs(props) { - const version = props.version; - const classes = useStyles(); - const [value, setValue] = React.useState(0); - - const handleChange = (event, newValue) => { - setValue(newValue); - }; - - return ( -
- - - } - label="Helm 3" - {...a11yProps(0)} - style={{ minWidth: '10%', textTransform: 'none' }} - /> - } - label="Kubernetes YAML" - {...a11yProps(1)} - style={{ minWidth: '10%', textTransform: 'none' }} - /> - - - - {/*Helm 3 install instructions*/} - - - {'# Add the Repo:' + - '\n' + - 'helm repo add datawire https://app.getambassador.io' + - '\n' + - 'helm repo update' + - '\n \n' + - '# Create Namespace and Install:' + - '\n' + - 'kubectl create namespace emissary && \\' + - '\n' + - `kubectl apply -f https://app.getambassador.io/yaml/emissary/${version}/emissary-crds.yaml` + - '\n' + - 'kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system' + - '\n' + - 'helm install emissary-ingress --namespace emissary datawire/emissary-ingress && \\' + - '\n' + - 'kubectl -n emissary wait --for condition=available --timeout=90s deploy -lapp.kubernetes.io/instance=emissary-ingress' + - '\n'} - - - - - {/*YAML install instructions*/} - - - {'kubectl create namespace emissary && \\' + - '\n' + - `kubectl apply -f https://app.getambassador.io/yaml/emissary/${version}/emissary-crds.yaml && \\` + - '\n' + - 'kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system' + - '\n' + - `kubectl apply -f https://app.getambassador.io/yaml/emissary/${version}/emissary-emissaryns.yaml && \\` + - '\n' + - 'kubectl -n emissary wait --for condition=available --timeout=90s deploy -lproduct=aes' + - '\n'} - - -
- ); -} diff --git a/content/en/docs/3.1/tutorials/gs-tabs2.js b/content/en/docs/3.1/tutorials/gs-tabs2.js deleted file mode 100644 index bfd95047..00000000 --- a/content/en/docs/3.1/tutorials/gs-tabs2.js +++ /dev/null @@ -1,174 +0,0 @@ -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'; - -function TabPanel(props) { - const { children, value, index, ...other } = props; - - return ( - - ); -} - -TabPanel.propTypes = { - children: PropTypes.node, - index: PropTypes.any.isRequired, - value: PropTypes.any.isRequired, -}; - -function a11yProps(index) { - return { - id: `simple-tab-${index}`, - 'aria-controls': `simple-tabpanel-${index}`, - }; -} - -const useStyles = makeStyles((theme) => ({ - root: { - flexGrow: 1, - backgroundColor: 'transparent', - }, -})); - -export default function SimpleTabs() { - const classes = useStyles(); - const [value, setValue] = React.useState(0); - - const handleChange = (event, newValue) => { - setValue(newValue); - }; - - return ( -
- - - - - - - - - - {/*Helm 3 token install instructions*/} - Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Helm. The slideout contains instructions with a - unique cloud-connect-token that is used to connect your - cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'helm upgrade ambassador --namespace ambassador datawire/ambassador \\' + - '\n' + - ' --set agent.cloudConnectToken=$TOKEN && \\' + - '\n' + - 'kubectl -n ambassador wait --for condition=available --timeout=90s deploy -lproduct=aes'} - - - - - {/*Helm 2 token install instructions*/} - Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Helm. The slideout contains instructions with a - unique cloud-connect-token that is used to connect your - cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'helm upgrade --namespace ambassador ambassador datawire/ambassador \\' + - '\n' + - ' --set crds.create=false --set agent.cloudConnectToken=$TOKEN && \\' + - '\n' + - 'kubectl -n ambassador wait --for condition=available --timeout=90s deploy -lproduct=aes'} - - - - - {/*YAML token install instructions*/} - Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Kubernetes YAML. The slideout contains instructions - with a unique cloud-connect-token that is used to connect - your cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'kubectl create configmap -n ambassador ambassador-agent-cloud-token \\' + - '\n' + - ' --from-literal=CLOUD_CONNECT_TOKEN=$TOKEN'} - - - - - {/*edgectl token install instructions*/} - Connecting $productName$ that was installed via edgectl is - identical to the Kubernetes YAML procedure. -
- Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Kubernetes YAML. The slideout contains instructions - with a unique cloud-connect-token that is used to connect - your cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'kubectl create configmap -n ambassador ambassador-agent-cloud-token \\' + - '\n' + - ' --from-literal=CLOUD_CONNECT_TOKEN=$TOKEN'} - - -
- ); -} diff --git a/content/en/docs/3.1/tutorials/quickstart-demo.md b/content/en/docs/3.1/tutorials/quickstart-demo.md deleted file mode 100644 index 70cbce8b..00000000 --- a/content/en/docs/3.1/tutorials/quickstart-demo.md +++ /dev/null @@ -1,176 +0,0 @@ -# $productName$ Tutorial - -In this article, you will explore some of the key features of $productName$ by walking through an example workflow and exploring the -Edge Policy Console. - -## Prerequisites - -You must have [$productName$ installed](../getting-started/) in your -Kubernetes cluster. - -## Routing Traffic from the Edge - -Like any other Kubernetes object, Custom Resource Definitions (CRDs) are used to -declaratively define $productName$’s desired state. The workflow you are going to -build uses a sample deployment and the `Mapping` CRD, which is the core resource -that you will use with $productName$ to manage your edge. It enables you to route -requests by host and URL path from the edge of your cluster to Kubernetes services. - -1. Copy the configuration below and save it to a file named `quote.yaml` so that -you can deploy these resources to your cluster. This basic configuration creates -the `quote` deployment and a service to expose that deployment on port 80. - - ```yaml - --- - apiVersion: apps/v1 - kind: Deployment - metadata: - name: quote - namespace: ambassador - spec: - replicas: 1 - selector: - matchLabels: - app: quote - strategy: - type: RollingUpdate - template: - metadata: - labels: - app: quote - spec: - containers: - - name: backend - image: docker.io/datawire/quote:$quoteVersion$ - ports: - - name: http - containerPort: 8080 - --- - apiVersion: v1 - kind: Service - metadata: - name: quote - namespace: ambassador - spec: - ports: - - name: http - port: 80 - targetPort: 8080 - selector: - app: quote - ``` - -1. Apply the configuration to the cluster with the command `kubectl apply -f quote.yaml`. - -1. Copy the configuration below and save it to a file called `quote-backend.yaml` -so that you can create a `Mapping` on your cluster. This `Mapping` tells $productName$ to route all traffic inbound to the `/backend/` path, on any host that can be used to reach $productName$, to the `quote` service. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Mapping - metadata: - name: quote-backend - namespace: ambassador - spec: - hostname: "*" - prefix: /backend/ - service: quote - ``` - -1. Apply the configuration to the cluster with the command -`kubectl apply -f quote-backend.yaml` - -1. Store the $productName$ `LoadBalancer` address to a local environment variable. -You will use this variable to test accessing your pod. - - ``` - export AMBASSADOR_LB_ENDPOINT=$(kubectl -n ambassador get svc ambassador -o "go-template={{range .status.loadBalancer.ingress}}{{or .ip .hostname}}{{end}}") - ``` - -1. Test the configuration by accessing the service through the $productName$ load -balancer. - - ``` - $ curl -Lk "https://$AMBASSADOR_LB_ENDPOINT/backend/" - { - "server": "idle-cranberry-8tbb6iks", - "quote": "Non-locality is the driver of truth. By summoning, we vibrate.", - "time": "2019-12-11T20:10:16.525471212Z" - } - ``` - -Success, you have created your first $productName$ `Mapping`, routing a -request from your cluster's edge to a service! - -Since the `Mapping` you just created controls how requests are routed, -changing the `Mapping` will immediately change the routing. To see this -in action, use `kubectl` to edit the `Mapping`: - -1. Run `kubectl edit Mapping quote-backend`. - -1. Change `prefix: /backend/` to `prefix: /quoteme/`. - -1. Save the file and let `kubectl` update your `Mapping`. - -1. Run `kubectl get Mappings --namespace ambassador`. You will see the -`quote-backend` `Mapping` has the updated prefix listed. Try to access the -endpoint again via `curl` with the updated prefix. - - ``` - $ kubectl get Mappings --namespace ambassador - NAME PREFIX SERVICE STATE REASON - quote-backend /quoteme/ quote - - $ curl -Lk "https://${AMBASSADOR_LB_ENDPOINT}/quoteme/" - { - "server": "snippy-apple-ci10n7qe", - "quote": "A principal idea is omnipresent, much like candy.", - "time": "2020-11-18T17:15:42.095153306Z" - } - ``` - -1. Change the prefix back to `/backend/` so that you can later use the `Mapping` -with other tutorials. - -## 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. In the Edge Policy Console, navigate to the **APIs** tab. You'll see the -OpenAPI documentation there for the "Quote Service API." Click **GET** to -expand out the documentation. - -1. Navigate to `https:///docs/` to see the -publicly visible Developer Portal. Make sure you include the trailing `/`. -This is a fully customizable portal that you can share with third parties who -need information about your APIs. - -## Next Steps - -Further explore some of the concepts you learned about in this article: -* [`Mapping` resource](../../topics/using/intro-mappings/): routes traffic from -the edge of your cluster to a Kubernetes service -* [`Host` resource](../../topics/running/host-crd/): sets the hostname by which -$productName$ will be accessed and secured with TLS certificates -* [Developer Portal](../../tutorials/dev-portal-tutorial/): -publishes an API catalog and OpenAPI documentation - -$productName$ has a comprehensive range of [features](/features/) to -support the requirements of any edge microservice. - -Learn more about [how developers use $productName$](../../topics/using/) to manage -edge policies. - -Learn more about [how site reliability engineers and operators run $productName$](../../topics/running/) -in production environments. - -To learn how $productName$ works, use cases, best practices, and more, check out -the [Quick Start](../getting-started) or read the [$productName$ Story](../../about/why-ambassador). - -For a custom configuration, you can install $productName$ -[manually](../../topics/install/yaml-install). diff --git a/content/en/docs/3.1/versions.yml b/content/en/docs/3.1/versions.yml deleted file mode 100644 index 39482caf..00000000 --- a/content/en/docs/3.1/versions.yml +++ /dev/null @@ -1,35 +0,0 @@ -# branch info -branch: release/v2.2 - -# self -version: 3.1.0 -productName: "Emissary-ingress" -productNamePlural: "Emissary-ingresses" -productNamespace: emissary -productDeploymentName: emissary-ingress -productHelmName: emissary-ingress - -# OSS (self) -ossVersion: 3.1.0 -ossDocsVersion: "3.1" -ossChartVersion: 8.1.0 -OSSproductName: "Emissary-ingress" -OSSproductNamePlural: "Emissary-ingresses" - -# AES (not self) -aesVersion: 3.1.0 -aesDocsVersion: "3.1" -aesChartVersion: 8.1.0 -AESproductName: "Ambassador Edge Stack" -AESproductNamePlural: "Ambassador Edge Stacks" - -# other products -qotmVersion: 1.7 -quoteVersion: 0.5.0 - -# Most recent version from previous major versions -# This is mostly to ensure that the migration matrix stays up-to-date -versionTwoX: 2.3.2 -chartVersionTwoX: 7.4.2 -versionOneX: 1.14.4 -chartVersionOneX: 6.9.5 diff --git a/content/en/docs/3.2/_index.md b/content/en/docs/3.2/_index.md deleted file mode 100644 index 1a897f7e..00000000 --- a/content/en/docs/3.2/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: v3.2 docs -cascade: - version: v3.2 - versName: &name v3.2 - git_version_tag: v3.2.0 - exclude_search: true -linkTitle: *name -simple_list: true -weight: -320 # Weight for doc version vX.Y should be -XY0 ---- - -These docs cover everything from setting up and running Emissary-ingress to its operation and usage. diff --git a/content/en/docs/3.2/about/aes-emissary-eol.md b/content/en/docs/3.2/about/aes-emissary-eol.md deleted file mode 100644 index 6afc3142..00000000 --- a/content/en/docs/3.2/about/aes-emissary-eol.md +++ /dev/null @@ -1,56 +0,0 @@ -# $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/content/en/docs/3.2/about/alternatives.md b/content/en/docs/3.2/about/alternatives.md deleted file mode 100644 index bafec087..00000000 --- a/content/en/docs/3.2/about/alternatives.md +++ /dev/null @@ -1,19 +0,0 @@ -# $productName$ vs. other software - -Alternatives to $productName$ fall into three basic categories: - -* Hosted API gateways, such as the [Amazon API gateway](https://aws.amazon.com/api-gateway/). -* Traditional API gateways, such as [Kong](https://konghq.org/). -* L7 proxies, such as [Traefik](https://traefik.io/), [NGINX](http://nginx.org/), [HAProxy](http://www.haproxy.org/), or [Envoy](https://www.envoyproxy.io), or Ingress controllers built on these proxies. - -Both hosted API gateways and traditional API gateways are: - -* Not self-service. The management interfaces on traditional API gateways are not designed for developer self-service, and provide limited safety and usability for developers. -* Not Kubernetes-native. They're typically configured using REST APIs, making it challenging to adopt cloud-native patterns such as GitOps and declarative configuration. -* [Designed for API management, rather than designed for microservices](../../topics/concepts/microservices-api-gateways). - -A Layer 7 proxy can be used as an API gateway, but typically requires additional bespoke development to support microservices use cases. In fact, many API gateways package the additional features needed for an API gateway on top of an L7 proxy. $productName$ uses Envoy, while Kong uses NGINX. If you're interested in deploying Envoy directly, we've written an [introductory tutorial](https://www.datawire.io/guide/traffic/getting-started-lyft-envoy-microservices-resilience/). - -## Istio - -[Istio](https://istio.io) is an open-source service mesh, built on Envoy. A service mesh is designed to manage East/West traffic (traffic between servers and your data center), while an API gateway manages North/South traffic (in and out of your data center). Documentation on how to deploy $productName$ with Istio is [here](../../howtos/istio). In general, we've found that North/South traffic is quite different from East/West traffic (i.e., you don't control the client in the North/South use case). diff --git a/content/en/docs/3.2/about/changes-2.x.md b/content/en/docs/3.2/about/changes-2.x.md deleted file mode 100644 index 389cc89b..00000000 --- a/content/en/docs/3.2/about/changes-2.x.md +++ /dev/null @@ -1,238 +0,0 @@ -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. - - - $productName$ 2.X supports only API versions getambassador.io/v2 - and getambassador.io/v3alpha1. If you are using any resources with - older API versions, you will need to upgrade them. - - -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 [structural CRDs](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. - - - Learn more about Listener.
- Learn more about Host. - - -### 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. - - - Learn more about Host. - - -### `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. - - - Learn more about Host.
- Learn more about Mapping. - - -### 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. - - - Learn more about Host. - - -### `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). - - - Learn more about Host.
- Learn more about TLSContext. - - -### `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). - - - Learn more about Mapping. - - -### `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. - - - Learn more about Mapping. - - -## 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). In $productName$ -2.X, you may switch back to Envoy V2 by setting the `AMBASSADOR_ENVOY_API_VERSION` -environment variable to "V2"; in $productName$ 3.X, support for the Envoy V2 API (and -the `AMBASSADOR_ENVOY_API_VERSION` environment variable) will be removed. - -### 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. - - - Learn more about Listener. - - -### `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/content/en/docs/3.2/about/changes-3.y.md b/content/en/docs/3.2/about/changes-3.y.md deleted file mode 100644 index 91105d28..00000000 --- a/content/en/docs/3.2/about/changes-3.y.md +++ /dev/null @@ -1,52 +0,0 @@ -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 AuthServices 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, -``` - - - Learn more about Envoy Proxy changes. - - -## 2. Envoy V2 Protocol Support Removed - -With the upgrade to Envoy **1.22**, the V2 Envoy Transport Protocol is no longer supported. -$productName$ 3.X **only** supports [V3 Envoy API](https://www.envoyproxy.io/docs/envoy/latest/api-v3/api). - - -The environment variable AMBASSADOR_ENVOY_API_VERSION has been removed and will no longer have the affect -of changing the transport protocol. - - - -The setting of 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. - diff --git a/content/en/docs/3.2/about/faq.md b/content/en/docs/3.2/about/faq.md deleted file mode 100644 index 513c75c5..00000000 --- a/content/en/docs/3.2/about/faq.md +++ /dev/null @@ -1,79 +0,0 @@ -# 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. -* 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! The core functionality of the $AESproductName$ is free and has no limits whatsoever. If you wish to use one of our additional, proprietary features such as Single Sign-On, you can get a free community license for up to 5 requests per second by registering your connected $AESproductName$ installation in [Ambassador Cloud](https://app.getambassador.io/cloud/). Please contact [sales](/contact-us/) if you need more than 5 RPS. - -For more details on core unlimited features and premium features, see the [editions page](/editions). - -### 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? - -[//]: # (+FIX+ Check for OSS) - -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$? - -[//]: # (+FIX+ Check for OSS) - -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 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/content/en/docs/3.2/about/features-and-benefits.md b/content/en/docs/3.2/about/features-and-benefits.md deleted file mode 100644 index a25d7752..00000000 --- a/content/en/docs/3.2/about/features-and-benefits.md +++ /dev/null @@ -1,43 +0,0 @@ -# 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 - -[//]: # (+FIX+ Forge is no more) - -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 - -[//]: # (+FIX+ we've come to realize that it's better to scale vertically) - -$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 using a custom authentication service. When configured, the $productName$ will check with your external authentication service prior to routing an incoming request. For more information, see the [authentication guide](../../topics/running/services/auth-service). - -## 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/content/en/docs/3.2/about/known-issues.md b/content/en/docs/3.2/about/known-issues.md deleted file mode 100644 index 6b89c65a..00000000 --- a/content/en/docs/3.2/about/known-issues.md +++ /dev/null @@ -1,9 +0,0 @@ -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. diff --git a/content/en/docs/3.2/about/support.md b/content/en/docs/3.2/about/support.md deleted file mode 100644 index 11927f95..00000000 --- a/content/en/docs/3.2/about/support.md +++ /dev/null @@ -1,27 +0,0 @@ -# Need help? - -If you need help deploying $productName$ at your organization, there are several different options available to you. - -## Support tiers - -### $productName$ community support - -When running $OSSproductName$, or $AESproductName$ with free community licenses, [join our Slack channel](http://a8r.io/slack) to talk with other users in the community and get your questions answered. - -If you can’t find an answer there, [contact us](/contact-us) to learn more about the support options available with $AESproductName$ Enterprise. - -### $AESproductName$ Enterprise - -With $AESproductName$ Enterprise, you have access to deployment and production support. To learn more, [contact sales](/contact-us). - -**Deployment and Update Support**: $AESproductName$ can accelerate your migration to Kubernetes, or your upgrade between versions of $AESproductName$. Deployment support helps you with the $AESproductName$ and Kubernetes migration, before you move to production. - -**Production Support**: We offer two types of production support contracts for users deploying the $AESproductName$ in production. We offer both business hour (8am - 5pm EST, M-F) and 24x7 Sev 1 support for the $AESproductName$. 24x7 Sev 1 support includes custom hotfix support for production outages if necessary. - -## File a Github Issue - -If you see a bug you want to fix, see room for documentation improvements, or have something else you want to change, you can [file an issue on github](https://github.com/datawire/ambassador/issues/new). - -## Pricing - -[Contact us](/contact-us) to learn how we can help, and for detailed pricing information. diff --git a/content/en/docs/3.2/about/why-ambassador.md b/content/en/docs/3.2/about/why-ambassador.md deleted file mode 100644 index 0d343983..00000000 --- a/content/en/docs/3.2/about/why-ambassador.md +++ /dev/null @@ -1,54 +0,0 @@ -# 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 an open-source, Kubernetes-native [microservices API gateway](../../topics/concepts/microservices-api-gateways) built on 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/content/en/docs/3.2/community.md b/content/en/docs/3.2/community.md deleted file mode 100644 index 759e4f0e..00000000 --- a/content/en/docs/3.2/community.md +++ /dev/null @@ -1,12 +0,0 @@ -# Community - -## Contributor's guide -Please review our [contributor's guide](https://github.com/emissary-ingress/emissary/blob/master/DEVELOPING.md) -on GitHub to learn how you can help make Emissary-ingress better. - -## Changelog -Our [changelog](https://github.com/emissary-ingress/emissary/blob/master/CHANGELOG.md) -describes new features, bug fixes, and updates to each version of Emissary-ingress. - -## Meetings -Check out our community [meeting schedule](https://github.com/emissary-ingress/emissary/blob/master/MEETING_SCHEDULE.md) for opportunities to interact with Emissary-ingress developers. diff --git a/content/en/docs/3.2/doc-links.yml b/content/en/docs/3.2/doc-links.yml deleted file mode 100644 index 90c7b5dd..00000000 --- a/content/en/docs/3.2/doc-links.yml +++ /dev/null @@ -1,225 +0,0 @@ -- 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: $productName$ 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: 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: 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/basic-auth - - title: Rate limiting - items: - - title: Rate limiting service - link: /topics/running/services/rate-limit-service/ - - title: Basic rate limiting - link: /topics/using/rate-limits/ - - 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: 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: 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: 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: Diagnostics - link: /topics/running/diagnostics -- 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: Licenses - link: licenses diff --git a/content/en/docs/3.2/features-icons/basic-authentication.svg b/content/en/docs/3.2/features-icons/basic-authentication.svg deleted file mode 100644 index 2bd19edf..00000000 --- a/content/en/docs/3.2/features-icons/basic-authentication.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_897228_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.2/features-icons/canary-release.svg b/content/en/docs/3.2/features-icons/canary-release.svg deleted file mode 100644 index f8de57d9..00000000 --- a/content/en/docs/3.2/features-icons/canary-release.svg +++ /dev/null @@ -1,27 +0,0 @@ - - - - Group 25 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.2/features-icons/cors.svg b/content/en/docs/3.2/features-icons/cors.svg deleted file mode 100644 index e559d924..00000000 --- a/content/en/docs/3.2/features-icons/cors.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_111967_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.2/features-icons/datadog.png b/content/en/docs/3.2/features-icons/datadog.png deleted file mode 100644 index eea05f8c..00000000 Binary files a/content/en/docs/3.2/features-icons/datadog.png and /dev/null differ diff --git a/content/en/docs/3.2/features-icons/datadog.svg b/content/en/docs/3.2/features-icons/datadog.svg deleted file mode 100644 index e46e8118..00000000 --- a/content/en/docs/3.2/features-icons/datadog.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Screen Shot 2018-04-05 at 8.22.25 AM - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.2/features-icons/diagnostics.svg b/content/en/docs/3.2/features-icons/diagnostics.svg deleted file mode 100644 index 940e1bc2..00000000 --- a/content/en/docs/3.2/features-icons/diagnostics.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_196445_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.2/features-icons/distributed-tracing.png b/content/en/docs/3.2/features-icons/distributed-tracing.png deleted file mode 100644 index 6b69e28c..00000000 Binary files a/content/en/docs/3.2/features-icons/distributed-tracing.png and /dev/null differ diff --git a/content/en/docs/3.2/features-icons/grpc.png b/content/en/docs/3.2/features-icons/grpc.png deleted file mode 100644 index b2f5a0d9..00000000 Binary files a/content/en/docs/3.2/features-icons/grpc.png and /dev/null differ diff --git a/content/en/docs/3.2/features-icons/prometheus.svg b/content/en/docs/3.2/features-icons/prometheus.svg deleted file mode 100644 index d5252a66..00000000 --- a/content/en/docs/3.2/features-icons/prometheus.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - prometheus_logo_grey - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.2/features-icons/rate-limiting.svg b/content/en/docs/3.2/features-icons/rate-limiting.svg deleted file mode 100644 index f1b6eacb..00000000 --- a/content/en/docs/3.2/features-icons/rate-limiting.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - Group 10 - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.2/features-icons/regex-routing.svg b/content/en/docs/3.2/features-icons/regex-routing.svg deleted file mode 100644 index 113b53b5..00000000 --- a/content/en/docs/3.2/features-icons/regex-routing.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_699774_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.2/features-icons/request-transformers.svg b/content/en/docs/3.2/features-icons/request-transformers.svg deleted file mode 100644 index 0b13e2dc..00000000 --- a/content/en/docs/3.2/features-icons/request-transformers.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_96239_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.2/features-icons/shadowing.svg b/content/en/docs/3.2/features-icons/shadowing.svg deleted file mode 100644 index 9e85eee1..00000000 --- a/content/en/docs/3.2/features-icons/shadowing.svg +++ /dev/null @@ -1,15 +0,0 @@ - - - - shadow - Created with Sketch. - - - - - - - - - - diff --git a/content/en/docs/3.2/features-icons/statsd.png b/content/en/docs/3.2/features-icons/statsd.png deleted file mode 100644 index 28374438..00000000 Binary files a/content/en/docs/3.2/features-icons/statsd.png and /dev/null differ diff --git a/content/en/docs/3.2/features-icons/statsd.svg b/content/en/docs/3.2/features-icons/statsd.svg deleted file mode 100644 index cabc90db..00000000 --- a/content/en/docs/3.2/features-icons/statsd.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - 88eb31f74479e422e4e9abfc6c2b00ee - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.2/features-icons/third-party-auth.svg b/content/en/docs/3.2/features-icons/third-party-auth.svg deleted file mode 100644 index 5359a24a..00000000 --- a/content/en/docs/3.2/features-icons/third-party-auth.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_511233_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.2/features-icons/timeouts.svg b/content/en/docs/3.2/features-icons/timeouts.svg deleted file mode 100644 index 47f63056..00000000 --- a/content/en/docs/3.2/features-icons/timeouts.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_587034_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.2/features-icons/tls-termination.svg b/content/en/docs/3.2/features-icons/tls-termination.svg deleted file mode 100644 index 6a631a96..00000000 --- a/content/en/docs/3.2/features-icons/tls-termination.svg +++ /dev/null @@ -1,17 +0,0 @@ - - - - noun_63544_cc - Created with Sketch. - - - - - - - - - - - - diff --git a/content/en/docs/3.2/features-icons/url-rewrite.svg b/content/en/docs/3.2/features-icons/url-rewrite.svg deleted file mode 100644 index 023e2e05..00000000 --- a/content/en/docs/3.2/features-icons/url-rewrite.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1295942_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.2/features-icons/websockets.svg b/content/en/docs/3.2/features-icons/websockets.svg deleted file mode 100644 index af17b9c0..00000000 --- a/content/en/docs/3.2/features-icons/websockets.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - noun_50814_cc - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.2/howtos/basic-auth.md b/content/en/docs/3.2/howtos/basic-auth.md deleted file mode 100644 index 70ce27ce..00000000 --- a/content/en/docs/3.2/howtos/basic-auth.md +++ /dev/null @@ -1,191 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Basic authentication (for $productName$) - -[//]: # (+FIX+ link to "authentication and authorization" concept) - - - This guide applies to $OSSproductName$, use of this guide with $AESproductName$ is not supported. $AESproductName$ does authentication using the Filter resource instead of the AuthService resource as described below. - - -$productName$ can authenticate incoming requests before routing them to a backing -service. In this tutorial, we'll configure $productName$ to use an external third -party authentication service. We're assuming also that you are running the -quote application in your cluster as described in the -[$productName$ tutorial](../../tutorials/quickstart-demo/). - -## Before you get started - -This tutorial assumes you have already followed the $productName$ [Installation](../../topics/install/) guide. If you haven't done that already, you should do so now. - -Once complete, you'll have a Kubernetes cluster running $productName$. Let's walk through adding authentication to this setup. - -## 1. Deploy the authentication service - -$productName$ delegates the actual authentication logic to a third party authentication service. We've written a [simple authentication service](https://github.com/datawire/ambassador-auth-service) that: - -- listens for requests on port 3000; -- expects all URLs to begin with `/extauth/`; -- performs HTTP Basic Auth for all URLs starting with `/backend/get-quote/` (other URLs are always permitted); -- accepts only user `username`, password `password`; and -- makes sure that the `x-qotm-session` header is present, generating a new one if needed. - -$productName$ routes _all_ requests through the authentication service: it relies on the auth service to distinguish between requests that need authentication and those that do not. If $productName$ cannot contact the auth service, it will return a 503 for the request; as such, **it is very important to have the auth service running before configuring $productName$ to use it.** - -Here's the YAML we'll start with: - -```yaml ---- -apiVersion: v1 -kind: Service -metadata: - name: example-auth -spec: - type: ClusterIP - selector: - app: example-auth - ports: - - port: 3000 - name: http-example-auth - targetPort: http-api ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: example-auth -spec: - replicas: 1 - strategy: - type: RollingUpdate - selector: - matchLabels: - app: example-auth - template: - metadata: - labels: - app: example-auth - spec: - containers: - - name: example-auth - image: docker.io/datawire/ambassador-auth-service:2.0.0 - imagePullPolicy: Always - ports: - - name: http-api - containerPort: 3000 - resources: - limits: - cpu: "0.1" - memory: 100Mi -``` - -Note that the cluster does not yet contain any $productName$ AuthService definition. This is intentional: we want the service running before we tell $productName$ about it. - -The YAML above is published at getambassador.io, so if you like, you can just do - -``` -kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/demo/demo-auth.yaml -``` - -to spin everything up. (Of course, you can also use a local file, if you prefer.) - -Wait for the pod to be running before continuing. The output of `kubectl get pods` should look something like - -``` -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -example-auth-6c5855b98d-24clp 1/1 Running 0 4m -``` -Note that the `READY` field says `1/1` which means the pod is up and running. - -## 2. Configure $productName$ authentication - -Once the auth service is running, we need to tell $productName$ about it. The easiest way to do that is point it to the `example-auth` service with the following: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: AuthService -metadata: - name: authentication -spec: - auth_service: "example-auth:3000" - path_prefix: "/extauth" - allowed_request_headers: - - "x-qotm-session" - allowed_authorization_headers: - - "x-qotm-session" -``` - -This configuration tells $productName$ about the auth service, notably that it needs the `/extauth` prefix, and that it's OK for it to pass back the `x-qotm-session` header. Note that `path_prefix` and `allowed_*_headers` are optional. - -If the auth service uses a framework like [Gorilla Toolkit](http://www.gorillatoolkit.org) which enforces strict slashes as HTTP path separators, it is possible to end up with an infinite redirect where the auth service's framework redirects any request with non-conformant slashing. This would arise if the above example had `path_prefix: "/extauth/"`, the auth service would see a request for `/extauth//backend/get-quote/` which would then be redirected to `/extauth/backend/get-quote/` rather than actually be handled by the authentication handler. For this reason, remember that the full path of the incoming request including the leading slash, will be appended to `path_prefix` regardless of non-conformant slashing. - -You can apply this file from getambassador.io with - -``` -kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/demo/demo-auth-enable.yaml -``` - -or, again, apply it from a local file if you prefer. - -Note that the cluster does not yet contain any $productName$ AuthService definition. - -## 3. Test authentication - -If we `curl` to a protected URL: - -``` -$ curl -Lv $AMBASSADORURL/backend/get-quote/ -``` - -We get a 401 since we haven't authenticated. - -``` -* TCP_NODELAY set -* Connected to 54.165.128.189 (54.165.128.189) port 32281 (#0) -> GET /backend/get-quote/ HTTP/1.1 -> Host: 54.165.128.189:32281 -> User-Agent: curl/7.63.0 -> Accept: */* -> -< HTTP/1.1 401 Unauthorized -< www-authenticate: Basic realm="Ambassador Realm" -< content-length: 0 -< date: Thu, 23 May 2019 15:24:55 GMT -< server: envoy -< -* Connection #0 to host 54.165.128.189 left intact -``` - -If we authenticate to the service, we will get a quote successfully: - -``` -$ curl -Lv -u username:password $AMBASSADORURL/backend/get-quote/ - -* TCP_NODELAY set -* Connected to 54.165.128.189 (54.165.128.189) port 32281 (#0) -* Server auth using Basic with user 'username' -> GET /backend/get-quote/ HTTP/1.1 -> Host: 54.165.128.189:32281 -> Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= -> User-Agent: curl/7.63.0 -> Accept: */* -> -< HTTP/1.1 200 OK -< content-type: application/json -< date: Thu, 23 May 2019 15:25:06 GMT -< content-length: 172 -< x-envoy-upstream-service-time: 0 -< server: envoy -< -{ - "server": "humble-blueberry-o2v493st", - "quote": "Nihilism gambles with lives, happiness, and even destiny itself!", - "time": "2019-05-23T15:25:06.544417902Z" -* Connection #0 to host 54.165.128.189 left intact -} -``` - -## More - -For more details about configuring authentication, see the [`External` filter](/docs/edge-stack/latest/topics/using/filters/) documentation. diff --git a/content/en/docs/3.2/howtos/cert-manager.md b/content/en/docs/3.2/howtos/cert-manager.md deleted file mode 100644 index 975dd3ff..00000000 --- a/content/en/docs/3.2/howtos/cert-manager.md +++ /dev/null @@ -1,230 +0,0 @@ -# Using cert-manager - -[//]: # (+FIX+ link to "TLS and certificates" concept) - -$AESproductName$ has simple and easy built-in support for automatically [using ACME] with the -`http-01` challenge to create and renew TLS certificates. However, this support is not available -in $OSSproductName$, and it is limited to the ACME `http-01` challenge type. If you're running -$OSSproductName$, or if you require more flexible certificate management (such as using ACME's -`dns-01` challenge, or using a non-ACME certificate source), external certificate management -tools are also supported. - -[using ACME]: ../../topics/running/host-crd/#acme-support - -One such tool is Jetstack's [cert-manager](https://github.com/jetstack/cert-manager), which is a general-purpose tool -for managing certificates in Kubernetes. Cert-manager will automatically create and renew TLS certificates and store -them as Kubernetes secrets for easy use in a cluster. $productName$ will automatically watch for secret -changes and reload certificates upon renewal. - -> **Note:** This document assumes cert-manager v0.15 or greater. This document has been updated to use CRD standards -> specified in v0.15. [Legacy CRD support](https://cert-manager.io/docs/installation/upgrading/upgrading-0.14-0.15/) -> was removed in cert-manager v0.15, see their [upgrading](https://cert-manager.io/docs/installation/upgrading/) -> document for more info. - -## Install cert-manager - -There are many different ways to [install cert-manager](https://cert-manager.io/docs/installation/). For simplicity, we will use Helm. - -1. Create the cert-manager CRDs. - ``` - kubectl apply -f https://github.com/jetstack/cert-manager/releases/latest/download/cert-manager.crds.yaml - ``` - -2. Add the `jetstack` Helm repository. - ``` - helm repo add jetstack https://charts.jetstack.io && helm repo update - ``` - -3. Install cert-manager. - - ``` - kubectl create ns cert-manager - helm install cert-manager --namespace cert-manager jetstack/cert-manager - ``` - -## Issuing certificates - -cert-manager issues certificates from a CA such as [Let's Encrypt](https://letsencrypt.org/). It does this using the ACME protocol which supports various challenge mechanisms for verifying ownership of the domain. - -### Issuer - -An `Issuer` or `ClusterIssuer` identifies which Certificate Authority cert-manager will use to issue a certificate. `Issuer` is a namespaced resource allowing you to use different CAs in each namespace, a `ClusterIssuer` is used to issue certificates in any namespace. Configuration depends on which ACME [challenge](#challenge) you are using. - -### Certificate - -A [Certificate](https://cert-manager.io/docs/concepts/certificate/) is a namespaced resource that references an `Issuer` or `ClusterIssuer` for issuing certificates. `Certificate`s define the DNS name(s) a key and certificate should be issued for, as well as the secret to store those files (e.g. `ambassador-certs`). Configuration depends on which ACME [challenge](#challenge) you are using. - -By duplicating issuers, certificates, and secrets one can support multiple domains with [SNI](../../topics/running/tls/sni). - -## Challenge - -cert-manager supports two kinds of ACME challenges that verify domain ownership in different ways: HTTP-01 and DNS-01. - -### DNS-01 challenge - -The DNS-01 challenge verifies domain ownership by proving you have control over its DNS records. Issuer configuration will depend on your [DNS provider](https://cert-manager.io/docs/configuration/acme/dns01/#supported-dns01-providers). This example uses [AWS Route53](https://cert-manager.io/docs/configuration/acme/dns01/route53/). - -1. Create the IAM policy specified in the cert-manager [AWS Route53](https://cert-manager.io/docs/configuration/acme/dns01/route53/) documentation. - -2. Note the `accessKeyID` and create a `secret` named `prod-route53-credentials-secret` in the cert-manager namespace that has a key value: `secret-access-key` from your AWS IaM credentials. - -3. Create and apply a `ClusterIssuer`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: ClusterIssuer - metadata: - name: letsencrypt-prod - spec: - acme: - email: email@example.com - server: https://acme-v02.api.letsencrypt.org/directory - privateKeySecretRef: - name: letsencrypt-prod - solvers: - - selector: - dnsZones: - - "myzone.route53.com" - dns01: - route53: - region: us-east-1 - accessKeyID: {accessKeyID} - hostedZoneID: {Hosted Zone ID} # optional, allows you to reduce the scope of permissions in Amazon IAM - secretAccessKeySecretRef: - name: prod-route53-credentials-secret - key: secret-access-key - ``` - -4. Create and apply a `Certificate`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: Certificate - metadata: - name: myzone.route53.com - # cert-manager will put the resulting Secret in the same Kubernetes - # namespace as the Certificate. You should create the certificate in - # whichever namespace you want to configure a Host. - spec: - secretName: ambassador-certs - issuerRef: - name: letsencrypt-prod - kind: ClusterIssuer - commonName: myzone.route53.com - dnsNames: - - myzone.route53.com - ``` - -5. Verify the secret is created. - - ``` - $ kubectl get secrets -n ambassador - NAME TYPE DATA AGE - ambassador-certs kubernetes.io/tls 2 1h - ``` - -### HTTP-01 challenge - -The HTTP-01 challenge verifies ownership of the domain by sending a request for a specific file on that domain. cert-manager accomplishes this by sending a request to a temporary pod with the prefix `/.well-known/acme-challenge/`. To perform this challenge: - -1. Create and apply a `ClusterIssuer`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: ClusterIssuer - metadata: - name: letsencrypt-prod - spec: - acme: - email: email@example.com - server: https://acme-v02.api.letsencrypt.org/directory - privateKeySecretRef: - name: letsencrypt-prod - solvers: - - http01: - ingress: - class: nginx - selector: {} - ``` - -2. Create and apply a `Certificate`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: Certificate - metadata: - name: ambassador-certs - # cert-manager will put the resulting Secret in the same Kubernetes - # namespace as the Certificate. You should create the certificate in - # whichever namespace you want to configure a Host. - namespace: ambassador - spec: - secretName: ambassador-certs - issuerRef: - name: letsencrypt-prod - kind: ClusterIssuer - dnsNames: - - example.com - ``` - -3. Apply both the `ClusterIssuer` and `Certificate` - - After applying both of these YAML manifests, you will notice that cert-manager has spun up a temporary pod named `cm-acme-http-solver-xxxx` but no certificate has been issued. Check the cert-manager logs and you will see a log message that looks like this: - - ``` - $ kubectl logs cert-manager-756d6d885d-v7gmg - ... - Preparing certificate default/ambassador-certs with issuer - Calling GetOrder - Calling GetAuthorization - Calling HTTP01ChallengeResponse - Cleaning up old/expired challenges for Certificate default/ambassador-certs - Calling GetChallenge - wrong status code '404' - Looking up Ingresses for selector certmanager.k8s.io/acme-http-domain=161156668,certmanager.k8s.io/acme-http-token=1100680922 - Error preparing issuer for certificate default/ambassador-certs: http-01 self check failed for domain "example.com - ``` - -4. Create a Mapping for the `/.well-known/acme-challenge/` route. - - cert-manager uses an `Ingress` to issue the challenge to `/.well-known/acme-challenge/` that is incompatible with Ambassador. We will need to create a `Mapping` so the cert-manager can reach the temporary pod. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Mapping - metadata: - name: acme-challenge-mapping - spec: - hostname: "*" - prefix: /.well-known/acme-challenge/ - rewrite: "" - service: acme-challenge-service - - --- - apiVersion: v1 - kind: Service - metadata: - name: acme-challenge-service - spec: - ports: - - port: 80 - targetPort: 8089 - selector: - acme.cert-manager.io/http01-solver: "true" - ``` - - Apply the YAML and wait a couple of minutes. cert-manager will retry the challenge and issue the certificate. - -5. Verify the secret is created: - - ``` - $ kubectl get secrets - NAME TYPE DATA AGE - ambassador-certs kubernetes.io/tls 2 1h - ambassador-token-846d5 kubernetes.io/service-account-token 3 2h - ``` diff --git a/content/en/docs/3.2/howtos/client-cert-validation.md b/content/en/docs/3.2/howtos/client-cert-validation.md deleted file mode 100644 index 10fe639d..00000000 --- a/content/en/docs/3.2/howtos/client-cert-validation.md +++ /dev/null @@ -1,110 +0,0 @@ -# Client certificate validation - -[//]: # (+FIX+ link to "TLS and client certs" concept) - -Sometimes, for additional security or authentication purposes, you will want -the server to validate who the client is before establishing an encrypted -connection. - -To support this, $productName$ can be configured to use a provided CA certificate -to validate certificates sent from your clients. This allows for client-side -mTLS where both $productName$ and the client provide and validate each other's -certificates. - -## Prerequisites - -- [openssl](https://www.openssl.org/source/) For creating client certificates -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [$productName$](../../tutorials/getting-started) -- [cURL](https://curl.haxx.se/download.html) - - -## Configuration - -1. Create a certificate and key. - - This can be done with a single command with `openssl`: - - ``` - openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 - ``` - - Enter a passcode for PEM files and fill in the certificate information. - Since this certificate will only be shared between a client and $productName$, - the Common Name must be set to something. Everything else can be left blank. - - **Note:** If using MacOS, - [you must](https://curl.haxx.se/mail/archive-2014-10/0053.html) - add the certificate and key as a PKCS encoded file to your Keychain. To do - this: - - 1. Encode `cert.pem` and `key.pem` created above in PKCS format - - ``` - openssl pkcs12 -inkey key.pem -in cert.pem -export -out certificate.p12 - ``` - - 2. Open "Keychain Access" on your system and select "File"->"Import Items..." - - 3. Navigate to your working directory and select the `certificate.p12` file - we just created above. - -2. Create a secret to hold the client CA certificate. - - ``` - kubectl create secret generic client-cacert --from-file=tls.crt=cert.pem - ``` - -3. Configure $productName$ to use this certificate for client certificate validation. - - First create a `Host` to manage your domain: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Host - metadata: - name: example-host - spec: - hostname: host.example.com - acmeProvider: - email: julian@example.com - ``` - - Then create a `TLSContext` to configure advanced TLS options like client - certificate validation: - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: TLSContext - metadata: - name: example-host-context - spec: - hosts: - - host.example.com - secret: host.example.com - ca_secret: client-cacert - cert_required: false # Optional: Configures $productName$ to reject the request if the client does not provide a certificate. Default: false - ``` - - **Note**: Client certificate validation requires $productName$ be configured to terminate TLS - - $productName$ is now be configured to validate certificates that the client provides. - -4. Test that $productName$ is validating the client certificates with `curl` - - **Linux**: - ``` - curl -v --cert cert.pem --key key.pem https://host.example.com/ - ``` - - **MacOS**: - ``` - curl -v --cert certificate.p12:[password] https://host.example.com/ - ``` - - Looking through the verbose output, you can see we are sending a client - certificate and $productName$ is validating it. - - If you need further proof, simply create a new set of certificates and - try sending the curl with those. You will see $productName$ deny the request. diff --git a/content/en/docs/3.2/howtos/configure-communications.md b/content/en/docs/3.2/howtos/configure-communications.md deleted file mode 100644 index 1ac09d2c..00000000 --- a/content/en/docs/3.2/howtos/configure-communications.md +++ /dev/null @@ -1,763 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -Configuring $productName$ Communications -======================================== - -For $productName$ to do its job of managing network communications for your services, it first needs to know how its own communications should be set up. This is handled by a combination of resources: the `Listener`, the `Host`, and the `TLSContext`. - -- `Listener`: defines where, and how, $productName$ should listen for requests from the network. -- `Host`: defines which hostnames $productName$ should care about, and how to handle different kinds of requests for those hosts. `Host`s can be associated with one or more `Listener`s. -- `TLSContext`: defines whether, and how, $productName$ will manage TLS certificates and options. `TLSContext`s can be associated with one or more `Host`s. - -Once the basic communications setup is in place, $productName$ `Mapping`s and `TCPMapping`s can be associated with `Host`s to actually do routing. - - - Remember that Listener and Host resources are  - required for a functioning $productName$ installation that can route traffic!
- Learn more about Listener.
- Learn more about Host. - - - - Remember than $productName$ does not make sure that a wildcard Host exists! If the - wildcard behavior is needed, a Host with a hostname of "*" - must be defined by the user. - - - - Several different resources work together to configure communications. A working knowledge of all of them - can be very useful:
- Learn more about Listener.
- Learn more about Host.
- Learn more about Mapping.
- Learn more about TCPMapping.
- Learn more about TLSContext. - - -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]: ../../topics/running/tls -[certificates]: ../../topics/running/tls#certificates-and-secrets -[check the logs]: ../../topics/running/debugging#review-logs - -Examples / Cookbook -------------------- - -### Basic HTTP and HTTPS - -A useful configuration is to support either HTTP or HTTPS, in this case on either port 8080 or port 8443. This -tends to make it as easy as possible to communicate with the services behind the $productName$ instance. It uses -two `Listener`s and at least one `Host`. - - -#### `Listener`s: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: http-listener -spec: - port: 8080 - protocol: HTTPS # NOT A TYPO, see below - securityModel: XFP - hostBinding: - namespace: - from: SELF # See below ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: - namespace: - from: SELF # See below -``` - -- Both `Listener`s use `protocol: HTTPS` to allow Envoy to inspect incoming connections, determine - whether or not TLS is in play, and set `X-Forwarded-Proto` appropriately. The `securityModel` then specifies - that `X-Forwarded-Proto` will determine whether requests will be considered secure or insecure. - -- The `hostBinding` shown here will allow any `Host` in the same namespace as the `Listener`s - to be associated with both `Listener`s; in turn, that will allow access to that `Host`'s - `Mapping`s from either port. For greater control, use a `selector` instead. - -- Note that the `Listener`s do not specify anything about TLS certificates. The `Host` - handles that; see below. - - - Learn more about Listener - - -#### `Host` - -This example will assume that we expect to be reachable as `foo.example.com`, and that the `foo.example.com` -certificate is stored in the Kubernetes `Secret` named `foo-secret`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: "foo.example.com" - tlsSecret: - name: foo-secret - requestPolicy: - insecure: - action: Redirect -``` - -- The `tlsSecret` specifies the certificate in use for TLS termination. -- The `requestPolicy` specifies routing HTTPS and redirecting HTTP to HTTPS. -- Since the `Host` does not specify a `selector`, only `Mapping`s with a `hostname` that matches - `foo.example.com` will be associated with this `Host`. -- **Note well** that simply defining a `TLSContext` is not sufficient to terminate TLS: you must define either - a `Host` or an `Ingress`. -- Note that if no `Host` is present, but a TLS secret named `fallback-secret` is available, the system will - currently define a `Host` using `fallback-secret`. **This behavior is subject to change.** - - - Learn more about Host - - -### HTTP-Only - -Another straightforward configuration is to support only HTTP, in this case on port 8080. This uses a single -`Listener` and a single `Host`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: http-listener -spec: - port: 8080 - protocol: HTTP - securityModel: INSECURE - hostBinding: - namespace: - from: SELF # See below ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: "foo.example.com" - requestPolicy: - insecure: - action: Route -``` - -- Here, we listen only on port 8080, and only for HTTP. HTTPS will be rejected. -- Since requests are only allowed using HTTP, we declare all requests `INSECURE` by definition. -- The `Host` specifies routing HTTP, rather than redirecting it. - - - - Learn more about Listener
- Learn more about Host - - -### TLS using ACME ($AESproductName$ only) - -This scenario uses ACME to get certificates for `foo.example.com` and `bar.example.com`. HTTPS traffic to either -host is routed; HTTP traffic to `foo.example.com` will be redirected to HTTPS, but HTTP traffic to `bar.example.com` -will be rejected outright. - -Since this example uses ACME, **it is only supported in $AESproductName$**. - -For demonstration purposes, we show this example listening for HTTPS on port 9999, using `X-Forwarded-Proto`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener-9999 -spec: - port: 9999 - protocol: HTTPS - securityModel: XFP - hostBinding: # Edit as needed - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - acmeProvider: - email: julian@example.com ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - acmeProvider: - email: julian@example.com - requestPolicy: - insecure: - action: Reject -``` - -(`Mapping`s are not shown.) - -- Our `Listener`s will accept HTTPS and HTTP on port 9999, and the protocol used will dictate whether - the requests are secure (HTTPS) or insecure (HTTP). -- `foo-host` defaults to ACME with Let's Encrypt, since `acmeProvider.authority` is not provided. -- `foo-host` defaults to redirecting insecure requests, since the default for `requestPolicy.insecure.action` is `Redirect`. -- `bar-host` uses Let's Encrypt as well, but it will reject insecure requests. - -**If you use ACME for multiple Hosts, add a wildcard Host too.** -This is required to manage a known issue. This issue will be resolved in a future Ambassador Edge Stack release. - - - Learn more about Listener
- Learn more about Host - - -### Multiple TLS Certificates - -This scenario uses TLS without ACME. Each of our two `Host`s uses a distinct TLS certificate. HTTPS -traffic to either`foo.example.com` or `bar.example.com` is routed, but this time `foo.example.com` will redirect -HTTP requests, while `bar.example.com` will route them. - -Since this example does not use ACME, it is supported in $productName$ as well as $AESproductName$. - -For demonstration purposes, we show this example listening for HTTPS on port 4848, using `X-Forwarded-Proto`. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: foo-example-secret -data: - tls.crt: -certificate PEM- - tls.key: -secret key PEM- ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: bar-example-secret -data: - tls.crt: -certificate PEM- - tls.key: -secret key PEM- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener-4848 -spec: - port: 4848 - protocol: HTTPS - securityModel: XFP - hostBinding: # Edit as needed - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - tlsSecret: - name: foo-example-secret ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - tlsSecret: - name: bar-example-secret - requestPolicy: - insecure: - action: Route -``` - -- `foo-host` and `bar-host` simply reference the `tlsSecret` to use for termination. - - If the secret involved contains a wildcard cert, or a cert with multiple SAN, both `Host`s could - reference the same `tlsSecret`. -- `foo-host` relies on the default insecure routing action of `Redirect`. -- `bar-host` must explicitly specify routing HTTP. - - - - Learn more about Listener
- Learn more about Host - - -### Using a `TLSContext` - -If you need to share other TLS settings between two `Host`s, you can reference a `TLSContext` as well as -the `tlsSecret`. This is the same as the previous example, but we use a `TLSContext` to set `ALPN` information, -and we assume that the `Secret` contains a wildcard cert. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: wildcard-example-secret -data: - tls.crt: -wildcard here- - tls.key: -wildcard here- ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-context -spec: - secret: wildcard-example-secret - alpn_protocols: [h2, istio] ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener-4848 -spec: - port: 4848 - protocol: HTTPS - securityModel: XFP - hostBinding: # Edit as needed - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - tlsContext: - name: example-context - tlsSecret: - name: wildcard-example-secret ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - tlsContext: - name: example-context - tlsSecret: - name: wildcard-example-secret - requestPolicy: - insecure: - action: Route -``` - -- Note that specifying the `tlsSecret` is still necessary, even when `tlsContext` is specified. - - - - Learn more about Listener
- Learn more about Host - - -### ACME With a TLSContext ($AESproductName$ Only) - -In $AESproductName$, you can use a `TLSContext` with ACME as well. This example is the same as "TLS using ACME", -but we use a `TLSContext` to set `ALPN` information. Again, ACME is only supported in $AESproductName$. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-context -spec: - secret: example-acme-secret - alpn_protocols: [h2, istio] ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - acmeProvider: - email: julian@example.com - tlsContext: - name: example-context - tlsSecret: - name: example-acme-secret -``` - -- Note that we don't provide the `Secret`: the ACME client will create it for us. - - - - Learn more about Listener
- Learn more about Host - - -### Using an L7 Load Balancer to Terminate TLS - -In this scenario, a layer 7 load balancer ahead of $productName$ will terminate TLS, so $productName$ will always see HTTP with a known good `X-Forwarded-Protocol`. We'll use that to route HTTPS and redirect HTTP. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: lb-listener -spec: - port: 8443 - protocol: HTTP - securityModel: XFP - l7Depth: 1 - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: "foo.example.com" - requestPolicy: - insecure: - action: Redirect -``` - -- We set `l7Depth` to 1 to indicate that there's a single trusted L7 load balancer ahead of us. -- We specifically set this Listener to HTTP-only, but we stick with port 8443 just because we expect people setting up TLS at all to expect to use port 8443. (There's nothing special about the port number, pick whatever you like.) -- Our `Host` does not specify a `tlsSecret`, so $productName$ will not try to terminate TLS. -- Since the `Listener` still pays attention to `X-Forwarded-Proto`, both secure and insecure requests - are possible, and we use the `Host` to route HTTPS and redirect HTTP. - - - - Learn more about Listener
- Learn more about Host - - -### Using a Split L4 Load Balancer to Terminate TLS - -Here, we assume that $productName$ is behind a load balancer setup that handles TLS at layer 4: - -- Incoming cleartext traffic is forwarded to $productName$ on port 8080. -- Incoming TLS traffic is terminated at the load balancer, then forwarded to $productName$ _as cleartext_ on port 8443. -- This might involve multiple L4 load balancers, but the actual number doesn't matter. -- The actual port numbers we use don't matter either, as long as $productName$ and the load balancer(s) agree on which port is for which traffic. - -We're going to route HTTPS for both `foo.example.com` and `bar.example.com`, redirect HTTP for `foo.example.com`, and reject HTTP for `bar.example.com`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: split-lb-one-listener -spec: - protocol: HTTP - port: 8080 - securityModel: INSECURE - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: split-lb-two-listener -spec: - protocol: HTTP - port: 8443 - securityModel: SECURE - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - requestPolicy: - insecure: - action: Reject -``` - -- Since L4 load balancers cannot set `X-Forwarded-Protocol`, we don't use it at all here: instead, we dictate that 8080 and 8443 both speak cleartext HTTP, but everything arriving at port 8080 is insecure and everything at port 8443 is secure. - - - - Learn more about Listener
- Learn more about Host - - -### Listening on Multiple Ports - -There's no reason you need to use ports 8080 and 8443, or that you're limited to two ports. Here we'll use ports 9001 and 9002 for HTTP, and port 4001 for HTTPS. We'll route traffic irrespective of protocol. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-9001 -spec: - protocol: HTTP - port: 9001 - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-9002 -spec: - protocol: HTTP - port: 9002 - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-4001 -spec: - protocol: HTTPS - port: 4001 - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: route-host -spec: - requestPolicy: - insecure: - action: Route -``` - -- We can use `X-Forwarded-Proto` for all our `Listener`s: the HTTP-only `Listener`s will set it correctly. -- Each `Listener` can specify only one port, but there's no hardcoded limit on the number of `Listener`s you can have. - - - - Learn more about Listener
- Learn more about Host - - -### Using Labels to Associate `Host`s and `Listener`s - -In the examples above, the `Listener`s all associate with any `Host` in their namespace. In this -example, we will use Kubernetes labels to control the association instead. - -Here, we'll listen for HTTP to `foo.example.com` on port 8888, and for either HTTP or HTTPS to `bar.example.com` on -port 9999 (where we'll redirect HTTP to HTTPS). Traffic to `baz.example.com` will work on both ports, and we'll route -HTTP for it rather than redirecting. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-8888 -spec: - protocol: HTTP - port: 8888 - securityModel: XFP - hostBinding: - selector: - matchLabels: - tenant: foo ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-9999 -spec: - protocol: HTTPS - port: 9999 - securityModel: XFP - hostBinding: - selector: - matchLabels: - tenant: bar ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: bar-secret -data: - tls.crt: -wildcard here- - tls.key: -wildcard here- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host - labels: - tenant: foo -spec: - hostname: foo.example.com - requestPolicy: - insecure: - action: Route ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host - labels: - tenant: bar -spec: - hostname: bar.example.com - tlsSecret: - name: bar-secret ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: baz-host - labels: - tenant: foo - tenant: bar -spec: - hostname: baz.example.com - tlsSecret: - name: bar-secret - requestPolicy: - insecure: - action: Route -``` - -- Note the `labels` on each `Host`, which the `hostBinding` on the `Listener` can reference. - - Note also that only label selectors are supported at the moment. - - - - Learn more about Listener
- Learn more about Host - - -### Wildcard `Host`s and `Mapping`s - -In a `Mapping`, the `host` is now treated as a glob rather than an exact match, with the goal of vastly reducing the need for `host_regex`. (The `hostname` in a `Host` has always been treated as a glob). - -- **Note that only prefix and suffix matches are supported**, so `*.example.com` and `foo.*` are both fine, but `foo.*.com` will not work -- you'll need to use `host_regex` if you really need that. (This is an Envoy limitation.) - -In this example, we'll accept both HTTP and HTTPS, but: - -- Cleartext traffic to any host in `lowsec.example.com` will be routed. -- Cleartext traffic to any host in `normal.example.com` will be redirected. -- Any other cleartext traffic will be rejected. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: example-secret -data: - tls.crt: -wildcard for *.example.com here- - tls.key: -wildcard for *.example.com here- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-8443 -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: lowsec-host -spec: - hostname: "*.lowsec.example.com" - tlsSecret: - name: example-secret - requestPolicy: - insecure: - action: Route ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: normal-host -spec: - hostname: "*.normal.example.com" - tlsSecret: - name: example-secret - requestPolicy: # We could leave this out since - insecure: # redirecting is the default, but - action: Redirect # it's spelled out for clarity. ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: catchall-host -spec: - hostname: "*.example.com" - tlsSecret: - name: example-secret - requestPolicy: - insecure: - action: Reject -``` - -- We'll listen for HTTP or HTTPS on port 8443. -- The three `Host`s apply different insecure routing actions depending on the hostname. -- You could also do this with `host_regex`, but using `host` with globs will give better performance. - - Being able to _not_ associate a given `Mapping` with a given `Host` when the `Mapping`'s - `host` doesn't match helps a lot when you have many `Host`s. - - Reliably determining if a regex (for the `Mapping`) matches a glob (for the `Host`) isn't really possible, so we can't prune `host_regex` `Mapping`s at all. - - - Learn more about Listener
- Learn more about Host - diff --git a/content/en/docs/3.2/howtos/consul.md b/content/en/docs/3.2/howtos/consul.md deleted file mode 100644 index d75e35ce..00000000 --- a/content/en/docs/3.2/howtos/consul.md +++ /dev/null @@ -1,564 +0,0 @@ - -import Alert from '@material-ui/lab/Alert'; - -# Consul integration - -
-

Contents

- -- [Consul integration](#consul-integration) - - [Architecture overview](#architecture-overview) - - [Installing Consul](#installing-consul) - - [Installing $productName$](#installing-consul) - - [Using Consul for service discovery](#using-consul-for-service-discovery) - - [Using Consul for authorization and encryption](#using-consul-for-authorization-and-encryption) - - [Environment variables](#environment-variables) - - [More information](#more-information) - -
- -[Consul](https://www.consul.io) is a widely used service mesh. -$productName$ natively supports service discovery and unauthenticated -communication to services in Consul. Additionally, the *Ambassador -Consul Connector* enables $productName$ to encrypt and authenticate -its communication via mTLS with services in Consul that make use of -[Consul's *Connect* feature](https://www.consul.io/docs/connect). - -## Architecture overview - -Using Consul with $productName$ is particularly useful when deploying -$productName$ in hybrid cloud environments where you deploy -applications on VMs and Kubernetes. In this environment, Consul -enables $productName$ to securely route over TLS to any application -regardless of where it is deployed. - -In this architecture, Consul serves as the source of truth for your -entire data center, tracking available endpoints, service -configuration, and secrets for TLS encryption. New applications and -services automatically register themselves with Consul using the -Consul agent or API. When you send a request through $productName$, -$productName$ sends the request to an endpoint based on the data in -Consul. - -![ambassador-consul](../images/consul-ambassador.png) - -This guide first instructs you on registering a service with Consul -and using $productName$ to dynamically route requests to that service -based on Consul's service discovery data, and subsequently instructs -you on using using the Ambassador Consul Connector to use Consul for -authorizing and encrypting requests. - -## Installing Consul - -If you already have Consul installed in your cluster, then go ahead -and skip to the next section. - -1. Before you install Consul, make sure to check the Consul - documentation for any setup steps specific to your platform. Below - you can find setup guides for some of the more popular Kubernetes - platforms. This step is primarily to ensure you have the proper - permissions to set up Consul. You can skip these guides if your - cluster is already configured to grant you the necessary - permissions. - - - [Microsoft Azure Kubernetes Service (AKS)](https://learn.hashicorp.com/tutorials/consul/kubernetes-aks-azure?utm_source=consul.io&utm_medium=docs) - - [Amazon Elastic Kubernetes Service (EKS)](https://learn.hashicorp.com/tutorials/consul/kubernetes-eks-aws?utm_source=consul.io&utm_medium=docs) - - [Google Kubernetes Engine (GKE)](https://learn.hashicorp.com/tutorials/consul/kubernetes-gke-google?utm_source=consul.io&utm_medium=docs) - - - - If you did not find your Kubernetes platform above, check the - [Consul documentation here](https://www.consul.io/docs/k8s) to see - if there are specific setup instructions for your platform. - - - -2. Add the Hashicorp repository for installing Consul with Helm. If - you do not have Helm installed, you can find an [installation guide - here](https://helm.sh/docs/intro/install/). - - ```shell - helm repo add hashicorp https://helm.releases.hashicorp.com - ``` - -3. Create a new `consul-values.yaml` YAML file for the Consul - installation values and copy the values below into that file. - - ```yaml - global: - datacenter: dc1 - - ui: - service: - type: 'LoadBalancer' - - syncCatalog: - enabled: true - - server: - replicas: 1 - bootstrapExpect: 1 - - connectInject: - enabled: true - ``` - - - - Note: you are free to change the value of the `datacenter` field in - the install values. This is the the name of your Consul - Datacenter. - - - -4. Install Consul with Helm using the `consul-values.yaml` values file - you just created. - - ```shell - helm install -f consul-values.yaml hashicorp hashicorp/consul - ``` - -## Installing $productName$ - -If you have not already installed $productName$ in to your cluster, -then go to the [quick start guide](../../tutorials/getting-started) -before continuing any further in this guide. - -## Using Consul for service discovery - -This section of the guide instructs you on configuring $productName$ -to look for services registered to Consul, registering a demo -application with Consul, and configuring $productName$ to route to -this application using endpoint data from Consul. - -In this tutorial, you deploy the application in Kubernetes. However, -this application can be deployed anywhere in your data center, such as -on a VM. - -1. Configure $productName$ to look for services registered to Consul - by creating the `ConsulResolver`. Use `kubectl` to apply the - following manifest: - - ```shell - kubectl apply -f < - - **Note:** If you changed the name of your `datacenter` in the - Consul install values, make sure to change it in the resolver above - to match the name of your datacenter. - - If you changed the name of the helm install from `hashicorp` to - another value, make sure to update the value of the `address` field - in your resolver to match it. - - If you are having trouble figuring out what your `address` field - should be, it follow this format: - `http://{consul_server_pod}.{consul_server_service}.{namespace}.svc.cluster.local:{consul_port}`. - The default Consul port should be `8500` unless you changed it. - - - - This tells $productName$ that Consul is a service discovery endpoint. - - You must set the resolver to your `ConsulResolver` on a - per-`Mapping` basis, otherwise for that `Mapping` $productName$ - uses the default resolver. That is, in order for a `Mapping` to - make use of a service registered in Consul, you need to add - `resolver: consul-dc1` to that `Mapping`. - - For more information about resolver configuration, see the - [resolver reference documentation](../../topics/running/resolvers). - (If you're using Consul deployed elsewhere in your data center, - make sure the `address` points to your Consul FQDN or IP address). - -2. Deploy the Quote demo application. Use `kubectl` to - apply the following manifest: - - ```shell - kubectl apply -f < - - The `SERVICE_NAME` environment variable in the `quote-consul` - `Deployment` specifies the service name for Consul. The default - value is set to "quote-consul", so you only need to include it if - you want to change the service name. - - - - The Quote application contains code to automatically - register itself with Consul, using the `CONSUL_IP` and `POD_IP` - environment variables specified within the `quote-consul` container - spec. - - When you apply this manifest, it registers the `Pod` in the - `quote-consul` `Deployment` as a Consul service with the name - `quote-consul` and the IP address of the `Pod`. - - - - The `"consul.hashicorp.com/connect-inject": "false"` annotation - tells Consul that for this `Deployment` you do not want to use the - sidecar proxy that is part of Consul's Connect feature. Without - Consul's sidecar, the service needs to include code to make a - request to Consul to register the service. The manifest includes - the environment variables `CONSUL_IP`, `POD_IP`, and `SERVICE_NAME` - to provide the Quote service with enough information - to build that request and send it to Consul. To see how this code - works, see our [our Git repo for the Quote - service](https://github.com/datawire/quote). - - - -3. Verify the `quote-consul` `Deployment`'s `Pod` has been registered - with Consul. You can verify this by accessing the Consul UI. - - First use `kubectl port-forward` to make the UI available on your - local workstation: - - ```shell - kubectl port-forward service/hashicorp-consul-ui 8500:80 - ``` - - Then, while the port-forward is running, go to - http://localhost:8500/ in a web browser. You should see a service - named `quote-consul`. - - After you have verified that you see the `quote-consul` service in - your web browser, you may kill the port-forward. - - - - Port forwarding not working for you? Make sure the service name - matches your Consul UI service by checking `kubectl get svc -A` - - - -4. Configure $productName$ to make use of this `quote-consul` service. - Use `kubectl` to apply the following manifest: - - ```shell - kubectl apply -f < - -**Congratulations!** You're successfully routing traffic to the Quote -application, the location of which is registered in -Consul. - - - -## Using Consul for authorization and encryption - -In this part of the guide, you'll install a different version of the -demo application that now uses Consul's *Connect* feature to authorize -its incoming connections using mTLS, and install *Ambassador Consul -Connector* to enable $productName$ to authenticate to such services. - -The following steps assume you've already set up Consul for service -discovery, as detailed above. - -1. The Ambassador Consul Connector retrieves the TLS certificate - issued by the Consul CA and stores it in a Kubernetes `Secret` for - $productName$ to use. Deploy the Ambassador Consul Connector with - `kubectl`: - - ```shell - kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/consul/ambassador-consul-connector.yaml - ``` - - This installs in to your cluster: - - - RBAC resources. - - The Ambassador Consul Connector service. - - A `TLSContext` named `ambassador-consul` to load the - `ambassador-consul-connect` `Secret` into $productName$. - -2. Deploy a new version of the demo application, and configure it to - inject the Consul Connect sidecar by setting - `"consul.hashicorp.com/connect-inject"` to `true`. Note that in - this version of the configuration, you do not have to configure - environment variables for the location of the Consul server. Use - `kubectl` to apply the following manifest: - - ```yaml - kubectl apply -f - < - - Note: Annotations are used to attach metadata to Kubernetes - objects. You can use annotations to link external information to - objects, working in a similar, yet different, fashion to labels. - For more information on annotations, refer to the [Annotating - Kubernetes Services for - Humans](https://kubernetes.io/blog/2021/04/20/annotating-k8s-for-humans/) - article, or get started with annotations in your own cluster with - the [Ambassador Cloud Quick start - guide](https://www.getambassador.io/docs/cloud/latest/service-catalog/quick-start/). - - - - This deploys a demo application `Deployment` called `quote-connect` - (different than the `quote-consul` `Deployment` in the previous - section) with the Consul Connect sidecar proxy. The Connect - sidecar registers the application with Consul, requires TLS to - access the application, and exposes other [Consul Service - Segmentation](https://www.consul.io/docs/connect) features. - - The annotation `consul.hashicorp.com/connect-inject` being set to - `true` in this `Deployment` tells Consul that you want this - `Deployment` to use the Consul Connect sidecar. The sidecar - proxies requests to the service that it is attached to. Keep this - in mind mind when debug requests to the service. - -4. Verify the `quote-connect` `Deployment`'s `Pod` has been registered - with Consul. You can verify this by accessing the Consul UI. - - First use `kubectl port-forward` to make the UI available on your - local workstation: - - ```shell - kubectl port-forward service/hashicorp-consul-ui 8500:80 - ``` - - Then, while the port-forward is running, open - http://localhost:8500/ in a web browser. You should see a service - named `quote-connect`. - - After you have verified that you see the `quote-connect` service in - your web browser, you may kill the port-forward. - -5. Create a `Mapping` to configure $productName$ route to the - `quote-connect` service in Consul. Use `kubectl` to apply the - following manifest: - - ```shell - kubectl apply -f < - -**Congratulations!** You successfully configured the service to work -with the Consul Connect sidecar. - - - -### Environment variables - -The Ambassador Consul Connector can be configured with the following -environment variables. The defaults are best for most use-cases. - -| Environment Variable | Description | Default | -|------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------| -| `_AMBASSADOR_ID` | Set 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`) | `""` | -| `_CONSUL_HOST` | Set the IP or DNS name of the target Consul HTTP API server | `127.0.0.1` | -| `_CONSUL_PORT` | Set the port number of the target Consul HTTP API server | `8500` | -| `_AMBASSADOR_TLS_SECRET_NAME` | Set the name of the Kubernetes `v1.Secret` created by this program that contains the Consul-generated TLS certificate. | `$AMBASSADOR_ID-consul-connect` | -| `_AMBASSADOR_TLS_SECRET_NAMESPACE` | Set the namespace of the Kubernetes `v1.Secret` created by this program. | (same Namespace as the Pod running this integration) | - -## More information - -For more about $productName$'s integration with Consul, read the -[service discovery configuration](../../topics/running/resolvers) -documentation. diff --git a/content/en/docs/3.2/howtos/dist-tracing.md b/content/en/docs/3.2/howtos/dist-tracing.md deleted file mode 100644 index ec5b160f..00000000 --- a/content/en/docs/3.2/howtos/dist-tracing.md +++ /dev/null @@ -1,49 +0,0 @@ -# Explore distributed tracing and Kubernetes monitoring - -The Kubernetes monitoring and distributed tracing landscape is hard to grasp. Although this conceptual approach to [observability is nothing new](https://blog.getambassador.io/distributed-tracing-with-java-microdonuts-kubernetes-and-the-ambassador-api-gateway-ace15b62a89e) — companies like New Relic revolutionized single-application performance monitoring (APM) over a decade ago — it took a few years and the [Dapper publication](https://research.google/pubs/pub36356/) for this idea to migrate to distributed applications. The importance of this technology is only increasing, as more and more of us are building [“deep systems”](https://lightstep.com/deep-systems/). - -As the industry is slowly but surely maturing, standardization is underway. Standardization means proprietary vendor solutions and open source projects are able to collaborate, making our lives easier. For newcomers, understanding the plethora of options, concepts, specifications, and implementations available is still a daunting task: - -* How are Zipkin and Jaeger related? -* What is header propagation? -* Which headers format should I use? -* Who owns the initialization of a trace context? -* How are the data points collected? - -The [K8s Initializer](https://app.getambassador.io/initializer/) can make it easy to enable distributed tracing in any microservices-based system by offering an opinionated and preconfigured application stack that will get you up and running in no time. This way, you can focus on understanding your service topology and interactions rather than waste days on attempting to understand competing standard integrations and tuning configuration switches. - -## One-Click Tracing Configuration with the K8s Initializer - -The K8s Initializer is a tool we built for you to quickly bootstrap any Kubernetes cluster with your own application-ready playground. It will generate YAML manifests for ingress, observability, and more in just a few clicks. Once installed on a local or remote Kubernetes cluster, the generated Kubernetes manifest resources will give you a perfect sandbox environment to deploy your own applications and explore standard integrations. - -Specifically for observability and distributed tracing, the K8s Initializer bundles a Jaeger installation to collect and visualize traces along with a pre-configured Ambassador Edge Stack acting as the ingress controller that will create a trace context on every request. A single selection is required. - -As per the option we selected, we’ll be generating Zipkin-format traces and use B3 headers for propagation between our services. There you have it! Instrument your Java, Python, Golang or Node.js applications with Zipkin and B3 header propagation libraries, then configure your code to send the trace data to the `jaeger-collector.monitoring:9411` service endpoint. - -All that is left to do is making a few requests and visualizing the trace data in the Jaeger UI. - -## Visualizing Trace Data - -As we installed the Ambassador Edge Stack as our ingress controller for Kubernetes via the K8s Initializer, it will instrument parent trace spans for each request coming into our Kubernetes cluster from the internet. The K8s Initializer also pre-configured Ambassador to exposes the Jaeger UI on a subpath: `https://$AMBASSADOR_IP/jaeger/` - -Simply by visiting this URL on our installation, we are able to visualize the generated and collected trace information emitted by our Ambassador installation: - -![Jaeger screenshot](../../images/jaeger.png) - -## Tracing the Future: OpenTelemetry - -The [OpenTelemetry project](https://opentelemetry.io/) was created with the intent of stopping the proliferation of API standards and libraries one might need to support for all their observability needs, effectively replacing the Zipkin-API, OpenCensus, OpenTracing and more competing implementations. - -> OpenTelemetry provides a single set of APIs, libraries, agents, and collector services to capture distributed traces and metrics from your application. You can analyze them using Prometheus, Jaeger, and other observability tools.
--[https://opentelemetry.io/](https://opentelemetry.io/) - -It’s at this point in the conversation that someone inevitably mentions that XKCD... - -![XKCD #927](../../images/xkcd.png) - -OpenTelemetry ultimately supports multiple formats in its [OpenTelemetry-Collector](https://github.com/open-telemetry/opentelemetry-collector), easing the transition from one technology to another when installed as a middleware and translator to relay trace data to other collectors. Along with many of its long-awaited features, it supports multiple trace exporters for Jaeger, Zipkin and proprietary APIs. - -## Learn More -In this tutorial, we’ve shown you how to monitor your Kubernetes application with distributed tracing in just a few clicks with the K8s Initializer. To learn more about these tools and distributed tracing, we also recommend [A Complete Guide to Distributed Tracing by the Lightstep Team](https://lightstep.com/distributed-tracing/). - -We also have guides to setup Edge Stack with [Datadog](../tracing-datadog/), [Zipkin](../tracing-zipkin/), and [Prometheus and Grafana](../prometheus). diff --git a/content/en/docs/3.2/howtos/external-dns.md b/content/en/docs/3.2/howtos/external-dns.md deleted file mode 100644 index f0f51dbb..00000000 --- a/content/en/docs/3.2/howtos/external-dns.md +++ /dev/null @@ -1,130 +0,0 @@ -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 - -Start by checking the [ExternalDNS repo's deployment instructions](https://github.com/kubernetes-sigs/external-dns#deploying-to-a-cluster) to get information about the supported DNS providers and steps to setup ExternalDNS for your provider. Each DNS provider will have its own required steps as well as annotations, arguments, and permissions needed for the following configuration. - - -### Installation - -Configuration for a `ServiceAccount`, `ClusterRole`, and `ClusterRoleBinding` are necessary for the ExternalDNS deployment to support compatability 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 above for annotations and arguments for your DNS Provider. - - -1. Create a YAML file named `externaldns-config.yaml`, and copy the following configuration into it. - - - Ensure that the apiGroups include "getambassador.io" following "networking.k8s.io" and the resources include "hosts" after "ingresses". - - - ```yaml - --- - apiVersion: v1 - kind: ServiceAccount - metadata: - name: external-dns - annotations: - eks.amazonaws.com/role-arn: {ARN} # AWS ARN role - --- - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRole - metadata: - name: external-dns - rules: - - apiGroups: [""] - resources: ["services","endpoints","pods"] - verbs: ["get","watch","list"] - - apiGroups: ["extensions","networking.k8s.io", "getambassador.io"] - resources: ["ingresses", "hosts"] - verbs: ["get","watch","list"] - - apiGroups: [""] - resources: ["nodes"] - verbs: ["list","watch"] - --- - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRoleBinding - metadata: - name: external-dns-viewer - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: external-dns - subjects: - - kind: ServiceAccount - name: external-dns - namespace: default - --- - apiVersion: apps/v1 - kind: Deployment - metadata: - name: external-dns - spec: - strategy: - type: Recreate - selector: - matchLabels: - app: external-dns - template: - metadata: - labels: - app: external-dns - annotations: - iam.amazonaws.com/role: {ARN} # AWS ARN role - spec: - serviceAccountName: external-dns - containers: - - name: external-dns - image: registry.opensource.zalan.do/teapot/external-dns:latest - args: - - --source=ambassador-host - - --domain-filter=example.net # will make ExternalDNS see only the hosted zones matching provided domain, omit to process all available hosted zones - - --provider=aws - - --policy=upsert-only # would prevent ExternalDNS from deleting any records, omit to enable full synchronization - - --aws-zone-type=public # only look at public hosted zones (valid values are public, private or no value for both) - - --registry=txt - - --txt-owner-id= {Hosted Zone ID} # Insert Route53 Hosted Zone ID here - ``` - -2. Review the arguments section from the ExternalDNS deployment - - Configure or remove arguments to fit your needs. Additional arguments required for your DNS provider can be found by checking the [ExternalDNS repo's deployment instructions](https://github.com/kubernetes-sigs/external-dns#deploying-to-a-cluster). - - * `--source=ambassador-host` - required across all DNS providers to tell ExternalDNS to look for hostnames in the $productName$ `Host` configurations. - -3. Apply the above config with the following command to deploy ExternalDNS to your cluster and configure support for $productName$ - - ```shell - kubectl apply -f externaldns-ambassador.yaml - ``` - - - For the above example, ensure that you are using an EKS cluster, or register your cluster with AWS so that ExternalDNS can view and edit your AWS Hosted Zones. If you are using a cluster outside EKS and not registered with AWS you will see permissions errors from the ExternalDNS pod when attempting to list the Hosted Zones. - - -## Usage - -After applying the above configuration, ExternalDNS is ready to use. Configure a `Host` with the following annotation to allow ExternalDNS to get the IP address of your $productName$'s LoadBalancer and register it with your DNS provider. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: your-hostname - annotations: - external-dns.ambassador-service: $productDeploymentName$.$productNamespace$ -spec: - acmeProvider: - authority: none - hostname: your-hostname.example.com -``` - - -Victory! ExternalDNS is now running and configured to report $productName$'s IP and hostname with your DNS provider. diff --git a/content/en/docs/3.2/howtos/filter-dev-guide.md b/content/en/docs/3.2/howtos/filter-dev-guide.md deleted file mode 100644 index eefe8b6b..00000000 --- a/content/en/docs/3.2/howtos/filter-dev-guide.md +++ /dev/null @@ -1,97 +0,0 @@ -# Developing custom filters for routing - -Sometimes you may want $AESproductName$ to manipulate an incoming request. Some example use cases: - -* Inspect an incoming request, and add a custom header that can then be used for routing -* Add custom Authorization headers -* Validate an incoming request fits an OpenAPI specification before passing the request to a target service - -$AESproductName$ supports these use cases by allowing you to execute custom logic in `Filters`. Filters are written in Golang, and managed by $AESproductName$. If you want to write a filter in a language other than Golang, $AESproductName$ also has an HTTP/gRPC interface for Filters called `External`. - -## Prerequisites - -`Plugin` `Filter`s are built as [Go plugins](https://golang.org/pkg/plugin/) and loaded directly into the $AESproductName$ container so they can run in-process with the rest of $AESproductName$. - -To build a `Plugin` `Filter` into the $AESproductName$ container you will need -- Linux or MacOS host (Windows Subsystem for Linux is ok) -- [Docker](https://docs.docker.com/install/) -- [rsync](https://rsync.samba.org/) - -The `Plugin` `Filter` is built by `make` which uses Docker to create a stable build environment in a container and `rsync` to copy files between the container and your host machine. - -See the [README](https://github.com/datawire/apro-example-plugin) for more information on how the `Plugin` works. - -## Creating and deploying filters - -We've created an example filter that you can customize for your particular use case. - -1. Start with the example filter: `git clone - https://github.com/datawire/apro-example-plugin/`. - -2. Make code changes to `param-plugin.go`. Note: If you're developing a non-trivial filter, see the rapid development section below for a faster way to develop and test your filter. - -3. Run `make DOCKER_REGISTRY=...`, setting `DOCKER_REGISTRY` to point - to a registry you have access to. This will generate a Docker image - named `$DOCKER_REGISTRY/amb-sidecar-plugin:VERSION`. - -4. Push the image to your Docker registry: `docker push $DOCKER_REGISTRY/amb-sidecar-plugin:VERSION`. - -5. Configure $AESproductName$ to use the plugin by creating a `Filter` - and `FilterPolicy` CRD, as per the [filter reference](/docs/edge-stack/latest/topics/using/filters/). - -6. Update the standard $AESproductName$ manifest to use your Docker - image instead of the standard sidecar. - - ```patch - value: '60' - - name: AMBASSADOR_INTERNAL_URL - value: https://127.0.0.1:8443 - - image: docker.io/datawire/aes:$version$ - + image: DOCKER_REGISTRY/aes-plugin:VERSION - imagePullPolicy: Always - livenessProbe: - httpGet: - ``` - -## Rapid development of a custom filter - -During development, you may want to sidestep the deployment process for a faster development loop. The `aes-plugin-runner` helps you rapidly develop $AESproductName$ filters locally. - -To install the runner, download the latest version: - -Mac 64-bit | -Linux 64-bit - -Note that the plugin runner must match the version of $AESproductName$ that you are running. Place the binary somewhere in your `$PATH`. - -Information about open-source code used in `aes-plugin-runner` can be found by running `aes-plugin-runner --version`. - -Now, you can quickly test and develop your filter. - -1. In your filter directory, type: `aes-plugin-runner :8080 ./param-plugin.so`. -2. Test the filter by running `curl`: - - ``` - $ curl -Lv localhost:8080?db=2 - * Rebuilt URL to: localhost:8080/?db=2 - * Trying ::1... - * TCP_NODELAY set - * Connected to localhost (::1) port 8080 (#0) - > GET /?db=2 HTTP/1.1 - > Host: localhost:8080 - > User-Agent: curl/7.54.0 - > Accept: */* - > - < HTTP/1.1 200 OK - < X-Dc: Even - < Date: Mon, 25 Feb 2019 19:58:38 GMT - < Content-Length: 0 - < - * Connection #0 to host localhost left intact - ``` - -Note in the example above the `X-Dc` header is added. This lets you inspect the changes the filter is making to your HTTP header. - -## Further reading - -For more details about configuring filters and the `plugin` interface, see the [filter reference](/docs/edge-stack/latest/topics/using/filters/). diff --git a/content/en/docs/3.2/howtos/grpc.md b/content/en/docs/3.2/howtos/grpc.md deleted file mode 100644 index 3967ddf7..00000000 --- a/content/en/docs/3.2/howtos/grpc.md +++ /dev/null @@ -1,403 +0,0 @@ -# gRPC Connections - -$productName$ makes it easy to access your services from outside your application. This includes gRPC services, although a little bit of additional configuration is required: by default, Envoy connects to upstream services using HTTP/1.x and then upgrades to HTTP/2 whenever possible. However, gRPC is built on HTTP/2 and most gRPC servers do not speak HTTP/1.x at all. $productName$ must tell its underlying Envoy that your gRPC service only wants to speak to that HTTP/2, using the `grpc` attribute of a `Mapping`. - -## Writing a gRPC service for $productName$ - -There are many examples and walkthroughs on how to write gRPC applications so that is not what this article will aim to accomplish. If you do not yet have a service written you can find examples of gRPC services in all supported languages here: [gRPC Quickstart](https://grpc.io/docs/quickstart/) - -This document will use the [gRPC python helloworld example](https://github.com/grpc/grpc/tree/master/examples/python/helloworld) to demonstrate how to configure a gRPC service with $productName$. - -Follow the example up through [Run a gRPC application](https://grpc.io/docs/languages/python/quickstart/#run-a-grpc-application) to get started. - -### Dockerize - -After building our gRPC application and testing it locally, we need to package it as a Docker container and deploy it to Kubernetes. - -To run a gRPC application, we need to include the client/server and the protocol buffer definitions. - -For gRPC with python, we need to install `grpcio` and the common protos. - -```Dockerfile -FROM python:2.7 - -WORKDIR /grpc - -ENV PATH "$PATH:/grpc" - -COPY greeter_server.py /grpc -COPY helloworld_pb2.py /grpc -COPY helloworld_pb2_grpc.py /grpc - -RUN python -m pip install grpcio -RUN python -m pip install grpcio-tools googleapis-common-protos - -CMD ["python", "./greeter_server.py"] - -EXPOSE 50051 -``` - -Create the container and test it: - -``` -$ docker build -t /grpc_example -$ docker run -p 50051:50051 /grpc_example -``` - -Where `` is your Docker user or registry. - -Switch to another terminal and from the same directory, run the `greeter_client`. The output should be the same as running it outside of the container. - -``` -$ docker run -p 50051:50051 /grpc_example -Greeter client received: Hello, you! -``` - -Once you verify the container works, push it to your Docker registry: - -``` -$ docker push /grpc_example -``` - -### Mapping gRPC services - -$productName$ `Mapping`s are based on URL prefixes; for gRPC, the URL prefix is the full-service name, including the package path (`package.service`). These are defined in the `.proto` definition file. In the example [proto definition file](https://github.com/grpc/grpc/blob/master/examples/protos/helloworld.proto) we see: - -``` -package helloworld; - -// The greeting service definition. -service Greeter { ... } -``` - -so the URL `prefix` is `helloworld.Greeter` and the mapping would be: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py -spec: - hostname: "*" - grpc: True - prefix: /helloworld.Greeter/ - rewrite: /helloworld.Greeter/ - service: grpc-example -``` - -Note the `grpc: true` line - this is what tells Envoy to use HTTP/2 so the request can communicate with your backend service. Also note that you'll need `prefix` and `rewrite` the same here, since the gRPC service needs the package and service to be in the request to do the right thing. - -### Deploying to Kubernetes - -`grpc_example.yaml` - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - acmeProvider: - authority: none - requestPolicy: - insecure: - action: Route ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py -spec: - hostname: "*" - grpc: True - prefix: /helloworld.Greeter/ - rewrite: /helloworld.Greeter/ - service: grpc-example - ---- -apiVersion: v1 -kind: Service -metadata: - labels: - service: grpc-example - name: grpc-example -spec: - type: ClusterIP - ports: - - name: grpc-greet - port: 80 - targetPort: grpc-api - selector: - service: grpc-example ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: grpc-example -spec: - replicas: 1 - selector: - matchLabels: - service: grpc-example - template: - metadata: - labels: - service: grpc-example - spec: - containers: - - name: grpc-example - image: /grpc_example - ports: - - name: grpc-api - containerPort: 50051 - restartPolicy: Always -``` - -The Host is declared here because we are using gRPC without TLS. Since $productName$ terminates TLS by default, in the Host we add a `requestPolicy` which allows insecure connections. After adding the $productName$ mapping to the service, the rest of the Kubernetes deployment YAML file is pretty straightforward. We need to identify the container image to use, expose the `containerPort` to listen on the same port the Docker container is listening on, and map the service port (80) to the container port (50051). - -> For more information on insecure routing, please refer to the [`Host` documentation](../../topics/running/host-crd#secure-and-insecure-requests). - - -Once you have the YAML file and the correct Docker registry, deploy it to your cluster with `kubectl`. - -``` -$ kubectl apply -f grpc_example.yaml -``` - -### Testing the Deployment - -Make sure to test your Kubernetes deployment before making more advanced changes (like adding TLS). To test any service with $productName$, we will need the hostname of the running $productName$ service which you can get with: - -``` -$ kubectl get service ambassador -o wide -``` -Which should return something similar to: - -``` -NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE -ambassador 10.11.12.13 35.36.37.38 80:31656/TCP 1m -``` -where `EXTERNAL-IP` is the `$AMBASSADORHOST` and 80 is the `$PORT`. - -You will need to open the `greeter_client.py` and change `localhost:50051` to `$AMBASSADORHOST:$PORT` - -```diff -- with grpc.insecure_channel('localhost:50051') as channel: -+ with grpc.insecure_channel(‘$AMBASSADORHOST:$PORT’) as channel: - stub = helloworld_pb2_grpc.GreeterStub(channel) - response = stub.SayHello(helloworld_pb2.HelloRequest(name='you')) - print("Greeter client received: " + response.message) -``` - -After making that change, simply run the client again and you will see the gRPC service in your cluster respond: - -``` -$ python greeter_client.py -Greeter client received: Hello, you! -``` - -### gRPC and TLS - -There is some extra configuration required to connect to a gRPC service through $productName$ over an encrypted channel. Currently, the gRPC call is being sent over cleartext to $productName$ which proxies it to the gRPC application. - -![](../images/grpc-tls.png) - -If you want to add TLS encryption to your gRPC calls, first you need to tell $productName$ to add [ALPN protocols](../../topics/running/tls) which are required by HTTP/2 to do TLS. - -For example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls -spec: - hosts: - - "*" - secret: ambassador-cert - alpn_protocols: h2 -``` - -Next, you need to change the client code slightly and tell it to open a secure RPC channel with $productName$. - -```diff -- with grpc.insecure_channel(‘$AMBASSADORHOST:$PORT’) as channel: -+ with grpc.secure_channel(‘$AMBASSADORHOST:$PORT’, grpc.ssl_channel_credentials()) as channel: - stub = helloworld_pb2_grpc.GreeterStub(channel) - response = stub.SayHello(helloworld_pb2.HelloRequest(name='you')) - print("Greeter client received: " + response.message) -``` - -`grpc.ssl_channel_credentials(root_certificates=None, private_key=None, certificate_chain=None)`returns the root certificate that will be used to validate the certificate and public key sent by $productName$. The default values of `None` tells the gRPC runtime to grab the root certificate from the default location packaged with gRPC and ignore the private key and certificate chain fields. Generally, passing no arguments to the method that requests credentials gives the same behavior. Refer to the languages [API Reference](https://grpc.io/docs/) if this is not the case. - -$productName$ is now terminating TLS from the gRPC client and proxying the call to the application over cleartext. - -![](../images/gRPC-TLS-Ambassador.png) - -If you want to configure authentication in another language, [gRPC provides examples](https://grpc.io/docs/guides/auth.html) with proper syntax for other languages. - -#### Working with Host headers that include the port - -Some gRPC clients automatically include the port in the Host header. This is a problem when using TLS because the certificate will match `myurl.com` but the Host header will be `myurl.com:443`, resulting in the error `rpc error: code = Unimplemented desc =`. If you run into this issue, there are two ways to solve it depending on your use case, both using the Module resource. - -The first is to set the `strip_matching_host_port` [property](../../topics/running/ambassador#strip-matching-host-port) to `true`. However, this only works if the port in the header matches the port that Envoy listens on (8443 by default). In the default installation of $productName$, the public port is 443, which then maps internally to 8443, so this only works for custom installations where the public service port matches the port in the Listener resource. - -The second solution is to use the following [Lua script](../../topics/running/ambassador#lua-scripts), which always strips the port: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador - namespace: ambassador -spec: - config: - lua_scripts: | - function envoy_on_request(request_handle) - local authority = request_handle:headers():get(":authority") - if(string.find(authority, ":") ~= nil) - then - local authority_index = string.find(authority, ":") - local stripped_authority = string.sub(authority, 1, authority_index - 1) - request_handle:headers():replace(":authority", stripped_authority) - end - end -``` - -#### Originating TLS with gRPC service - -![](../images/gRPC-TLS-Originate.png) - -$productName$ can originate TLS with your gRPC service so the entire RPC channel is encrypted. To configure this, first get some TLS certificates and configure the server to open a secure channel with them. Using self-signed certs this can be done with OpenSSL and adding a couple of lines to the server code. - -```diff -def serve(): - server = grpc.server(futures.ThreadPoolExecutor(max_workers=10)) -+ with open('certs/server.key', 'rb') as f: -+ private_key = f.read() -+ with open('certs/server.crt', 'rb') as f: -+ cert_chain = f.read() -+ server_creds = grpc.ssl_server_credentials( ( (private_key, cert_chain), ) ) - helloworld_pb2_grpc.add_GreeterServicer_to_server(Greeter(), server) -- server.add_insecure_port('[::]:50052') -+ server.add_secure_port('[::]:50052', server_creds) - server.start() -``` - -Rebuild your docker container **making sure the certificates are included** and follow the same steps of testing and deploying to Kubernetes. You will need to make a small change to the client code to test locally. - -```diff -- with grpc.insecure_channel(‘localhost:$PORT’) as channel: -+ with grpc.secure_channel(‘localhost:$PORT’, grpc.ssl_channel_credentials(open('certs/server.crt', 'rb').read())) as channel: - stub = helloworld_pb2_grpc.GreeterStub(channel) - response = stub.SayHello(helloworld_pb2.HelloRequest(name='you')) - print("Greeter client received: " + response.message) -``` - -Once deployed we will need to tell $productName$ to originate TLS to the application. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py-tls -spec: - hostname: "*" - grpc: True - tls: upstream - prefix: /hello.Greeter/ - rewrite: /hello.Greeter/ - service: https://grpc-py - ---- -apiVersion: v1 -kind: Service -metadata: - labels: - service: grpc-py - name: grpc-py -spec: - type: ClusterIP - ports: - - name: grpc-greet - port: 443 - targetPort: grpc-api - selector: - service: grpc-py -``` - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: upstream -spec: - alpn_protocols: h2 - secret: ambassador-cert -``` - -We need to tell $productName$ to route to the `service:` over https and have the service listen on `443`. We also need to tell $productName$ to use ALPN protocols when originating TLS with the application, the same way we did with TLS termination. This is done by setting `alpn_protocols: ["h2"]` in a `TLSContext` telling the service to use that tls-context in the mapping by setting `tls: upstream`. - -Refer to the [TLS document](../../topics/running/tls/origination#advanced-configuration-using-a-tlscontext) for more information on TLS origination. - -### gRPC headers - -gRPC services use [HTTP/2 headers](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md). This means that some header-based routing rules will need to be rewritten to support HTTP/2 headers. For example, `host: subdomain.host.com` needs to be rewritten using the `headers: ` attribute with the `:authority` header: - -``` -headers: - :authority: subdomain.host.com -``` - -## Note - -### Ingress controllers - -Some [Kubernetes ingress controllers](https://kubernetes.io/docs/concepts/services-networking/ingress/) do not support HTTP/2 fully. As a result, if you are running $productName$ with an ingress controller in front, you may find that gRPC requests fail even with correct $productName$ configuration. - -A simple way around this is to use $productName$ with a `LoadBalancer` service, rather than an Ingress controller. You can also consider using [$productName$ as your Ingress Controller](../../topics/running/ingress-controller). - -### Mappings with hosts - -As with any `Mapping`, your gRPC service's `Mapping` may include a `host`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py -spec: - hostname: "*" - grpc: true - prefix: /helloworld.Greeter/ - rewrite: /helloworld.Greeter/ - service: grpc-example - host: api.example.com -``` - -Some gRPC client libraries produce requests where the `host` or `:authority` header includes the port number. For example, a request to the above service might include `host: api.example.com:443` instead of just `host: api.example.com`. To avoid having $productName$ return a 404 (not found) response to these requests due to the mismatched host, you may want to set `strip_matching_host_port` in the [Ambassador module](../../topics/running/ambassador#strip-matching-host-port). - -Alternately, you may find it cleaner to make sure your gRPC client does not include the port in the `host` header. Here is an example using gRPC/Go. - -```go -hostname := "api.example.com" -port := "443" -config := &tls.Config{ServerName: hostname} -creds := credentials.NewTLS(config) -opts := []grpc.DialOption{ - grpc.WithTransportCredentials(creds), -// ... -} -conn, err := grpc.Dial(hostname+":"+port, opts...) -// ... -``` - -## gRPC-Web - -$productName$ also supports the [gRPC-Web](../../topics/running/ambassador#grpc) protocol for browser-based gRPC applications. diff --git a/content/en/docs/3.2/howtos/http3-aks.md b/content/en/docs/3.2/howtos/http3-aks.md deleted file mode 100644 index 2f9be012..00000000 --- a/content/en/docs/3.2/howtos/http3-aks.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "$productName$ - HTTP/3 support for Azure Kubernetes Service (AKS)" -description: "How to configure HTTP/3 support for Azure Kubernetes Service (AKS). This guide shows how to setup the LoadBalancer service for AKS to support both TCP and UDP communications." ---- - -# Azure Kubernetes Service Engine HTTP/3 configuration - -This guide shows how to setup HTTP/3 support for Azure Kubernetes Service (AKS). The instructions provided in this page are a continuation of the [HTTP/3 in $productName$](../../topics/running/http3) documentation. - -## Configuring an external load balancer for AKS - -To configure an external load balancer for AKS, you need to: - -1. Reserve a public static IP address. -2. Create two `LoadBalancer` services, one for TCP and one for UDP. -3. Assign the public static IP address to the `loadBalancerIP` field. - -An example of the two load balancer services described above looks as follows: - -```yaml -# selectors and labels removed for clarity -apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$ - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - --- - apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$-udp - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http3 - port: 443 # Default support for HTTP/3 requires you to use 443 for the external client-facing port. - targetPort: 8443 - protocol: UDP - -``` - -In the above example, AKS generates two `LoadBalancer` services, one for UDP and the other for TCP. - - -You should verify that the Managed Identity or Serivce Principal has permissions to assign the IP address to the newly created LoadBalancer services. Refer to the Azure Docs - Managed Identity for more information. - diff --git a/content/en/docs/3.2/howtos/http3-eks.md b/content/en/docs/3.2/howtos/http3-eks.md deleted file mode 100644 index d09a1af5..00000000 --- a/content/en/docs/3.2/howtos/http3-eks.md +++ /dev/null @@ -1,252 +0,0 @@ ---- -title: "HTTP/3 with Amazon Elastic Kubernetes Service (EKS) | $productName$" -description: "How to configure HTTP/3 support for Amazon Elastic Kubernetes Service (EKS). This guide shows how to setup the LoadBalancer service for EKS to support both TCP and UDP communications." ---- - -# Amazon Elastic Kubernetes Service HTTP/3 configuration - -This guide shows how to setup HTTP/3 support for Amazon Elastic Kubernetes Service (EKS) The instructions provided in this page are a continuation of the [HTTP/3 in $productName$](../../topics/running/http3) documentation. - -## Create a network load balancer (NLB) - - The virtual private cloud (VPC) for your load balancer needs one public subnet in each availability zone where you have targets. - - ```shell - SUBNET_IDS=( ) - - aws elbv2 create-load-balancer \ - --name ${CLUSTER_NAME}-nlb \ - --type network \ - --subnets ${SUBNET_IDS} - ``` - -## Create a NodePort service - -Now create a `NodePort` service for $productName$ installation with two entries. Use `port: 443` to include support for both TCP and UDP traffic. - ```yaml - # Selectors and labels removed for clarity. - apiVersion: v1 - kind: Service - metadata: - name: $productDeploymentName$-http3 - namespace: $productNamespace$ - spec: - type: NodePort - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - nodePort: 30080 - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - nodePort: 30443 - - name: http3 - port: 443 - targetPort: 8443 - protocol: UDP - nodePort: 30443 - ``` - -## Create target groups - -Run the following command with the variables for your VPC ID and cluster name: - - ```shell - VPC_ID= - CLUSTER_NAME= - - aws elbv2 create-target-group --name ${CLUSTER_NAME}-tcp-tg \ - --protocol TCP --port 30080 --vpc-id ${VPC_ID} \ - --health-check-protocol TCP \ - --health-check-port 30080 \ - --target-type instance - - aws elbv2 create-target-group --name ${CLUSTER_NAME}-tcp-udp-tg \ - --protocol TCP_UDP --port 30443 --vpc-id ${VPC_ID} \ - --health-check-protocol TCP \ - --health-check-port 30443 \ - --target-type instance - ``` - -## Register your instances - -Next, register your cluster's instance with the the instance IDs and Amazon Resource Names (ARN). - -To get your cluster's instance IDs, enter the following command: - ```shell - aws ec2 describe-instances \ - --filters Name=tag:eks:cluster-name,Values=${CLUSTER_NAME} \ - --output text - --query 'Reservations[*].Instances[*].InstanceId' \ - ``` - -To get your ARNs, enter the following command: - ```shell - TCP_TG_NAME=${CLUSTER_NAME}-tcp-tg-name - TCP_UDP_TG_NAME=${CLUSTER_NAME}-tcp-udp-tg-name - - aws elbv2 describe-target-groups \ - --query 'TargetGroups[?TargetGroupName==`'${TCP_TG_NAME}'`].TargetGroupArn' \ - --output text - aws elbv2 describe-target-groups \ - --query 'TargetGroups[?TargetGroupName==`'${TCP_UDP_TG_NAME}'`]. TargetGroupArn' \ - --output text - ``` - -Register the instances with the target groups and load balancer using the instance IDs and ARNs you retrieved. - ```shell - INSTANCE_IDS=( ) - REGION= - TG_NAME= - TCP_TG_ARN=arn:aws:elasticloadbalancing:${REGION}:079.....:targetgroup/${TG_NAME}/... - TCP_UDP_TG_ARN=arn:aws:elasticloadbalancing:${REGION}:079.....:targetgroup/${TG_NAME}/... - - aws elbv2 register-targets --target-group-arn ${TCP_TG_ARN} --targets ${INSTANCE_IDS} - aws elbv2 register-targets --target-group-arn ${TCP_UDP_TG_ARN} --targets ${INSTANCE_IDS} - ``` - -## Create listeners in AWS. - -Register your cluster's instance with the instance IDs and ARNs. - -To get the load balancer's ARN, enter the following command: - ```shell - aws elbv2 describe-load-balancers --name ${CLUSTER_NAME}-nlb \ - --query 'LoadBalancers[0].LoadBalancerArn' \ - --output text - ``` - -Create a TCP listener on port 80 that that forwards to the TargetGroup {TCP_TG_ARN}. - ```shell - aws elbv2 create-listener --load-balancer-arn ${LB_ARN} \ - --protocol TCP --port 80 \ - --default-actions Type=forward,TargetGroupArn=${TCP_TG_ARN} - ``` - - Create a TCP_UDP listener on port 443 that forwards to the TargetGroup {TCP_UDP_TG_ARN}. - ```shell - aws elbv2 create-listener --load-balancer-arn ${LB_ARN} \ - --protocol TCP_UDP --port 443 \ - --default-actions Type=forward,TargetGroupArn=${TCP_UDP_TG_ARN} - ``` - -## Update the security groups - -Now you need to update your security groups to receive traffic. This security group covers all node groups attached to the EKS cluster: - ```shell - aws eks describe-cluster --name ${CLUSTER_NAME} | grep clusterSecurityGroupId - ``` - -Now authorize the cluster security group to allow internet traffic: - ```shell - for x in ${CLUSTER_SG}; do \ - aws ec2 authorize-security-group-ingress --group-id $$x --protocol tcp --port 30080 --cidr 0.0.0.0/0; \ - aws ec2 authorize-security-group-ingress --group-id $$x --protocol tcp --port 30443 --cidr 0.0.0.0/0; \ - aws ec2 authorize-security-group-ingress --group-id $$x --protocol udp --port 30443 --cidr 0.0.0.0/0; \ - done - ``` - -## Get the DNS name for the load balancers - -Enter the following command to get the DNS name for your load balancers and create a CNAME record at your domain provider: - ```shell - aws elbv2 describe-load-balancers --name ${CLUSTER_NAME}-nlb \ - --query 'LoadBalancers[0].DNSName' \ - --output text - ``` - -## Create Listener resources - -Now you need to create the `Listener` resources for $productName$. The first `Listener` in the example below handles traffic for HTTP/1.1 and HTTP/2, while the second `Listener` handles all HTTP/3 traffic. - - ```yaml - kubectl apply -f - < - acmeProvider: - authority: none - tlsSecret: - name: tls-cert # The QUIC network protocol requires TLS with a valid certificate - tls: - min_tls_version: v1.3 - max_tls_version: v1.3 - alpn_protocols: h2,http/1.1 - EOF - ``` - -## Apply the quote service and a Mapping to test the HTTP/3 configuration. - -Finally, apply the quote service to a $productName$ `Mapping`. - - ```shell - kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$version$/quickstart/qotm.yaml - kubectl apply -f - </backend/ - ``` -Your domain now shows that it is being served with HTTP/3. diff --git a/content/en/docs/3.2/howtos/http3-gke.md b/content/en/docs/3.2/howtos/http3-gke.md deleted file mode 100644 index 677e89e3..00000000 --- a/content/en/docs/3.2/howtos/http3-gke.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: "$productName$ - HTTP/3 support for Google Kubernetes Engine (GKE)" -description: "How to configure HTTP/3 support for Google Kubernetes Engine (GKE). This guide shows how to setup the LoadBalancer service for GKE to support both TCP and UDP communications." ---- - -# Google Kubernetes Service Engine HTTP/3 configuration - -This guide shows how to setup HTTP/3 support for Google Kubernetes Engine (GKE). The instructions provided in this page are a continuation of the [HTTP/3 in $productName$](../../topics/running/http3) documentation. - -## Configuring an external load balancer for GKE - -Currently, GKE only supports adding feature flags to `alpha` clusters, and doesn't support the creation of mixed protocol services of type `LoadBalancer`. To configure an external load balancer for GKE, you need to: - -1. Reserve a public static IP address. -2. Create two `LoadBalancer` services, one for TCP and one for UDP. -3. Assign the public static IP address to the `loadBalancerIP` field. - -An example of the two load balancer services described above looks as follows: - -```yaml -# selectors and labels removed for clarity -apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$ - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - --- - apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$-udp - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http3 - port: 443 # Default support for HTTP/3 requires you to use 443 for the external client-facing port. - targetPort: 8443 - protocol: UDP - -``` - -In the above example, GKE generates two `LoadBalancer` services, one for UDP and the other for TCP. diff --git a/content/en/docs/3.2/howtos/index.md b/content/en/docs/3.2/howtos/index.md deleted file mode 100644 index f16cdd46..00000000 --- a/content/en/docs/3.2/howtos/index.md +++ /dev/null @@ -1,25 +0,0 @@ -# "How-to" guides - -These guides are designed to help users quickly accomplish common tasks. The guides assume a certain level of understanding of $productName$. Many of these guides are contributed by third parties; we welcome contributions via Pull Request at https://github.com/emissary-ingress/emissary. - -* Integrating with Service Mesh. $productName$ natively integrates with many service meshes. - * [HashiCorp Consul](consul) - * [Istio](istio) - * [Linkerd](linkerd2) -* Distributed tracing. $productName$ natively supports a number of distributed tracing systems to enable developers to visualize request flow in microservice and service-oriented architectures. - * [Datadog](tracing-datadog) - * [Zipkin](tracing-zipkin) -* Monitoring. $productName$ integrates with a number of different monitoring/metrics providers. - * [Prometheus](prometheus) -* [Developing Custom Filters](filter-dev-guide) -* Frameworks and Protocols. $productName$ supports a wide range of protocols and cloud-native frameworks. - * [gRPC](grpc) - * [Knative Serverless Framework](knative) - * [WebSockets](websockets) -* Security. $productName$ supports a number of strategies for securing Kubernetes services. - * [Protecting the Diagnostics Interface](protecting-diag-access) - * [HTTPS and TLS termination](tls-termination) - * [Certificate Manager](cert-manager) can be used to automatically obtain and renew TLS certificates; $AESproductName$ natively integrates this functionality. - * [Client Certificate Validation](client-cert-validation) - * [Basic Authentication](basic-auth) is a tutorial on how to use the external authentication API to code your own authentication service. - * [Basic Rate Limiting](rate-limiting-tutorial) diff --git a/content/en/docs/3.2/howtos/istio.md b/content/en/docs/3.2/howtos/istio.md deleted file mode 100644 index 6fa74fcf..00000000 --- a/content/en/docs/3.2/howtos/istio.md +++ /dev/null @@ -1,445 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Istio integration - -$productName$ and Istio: Edge Proxy and Service Mesh together in one. $productName$ is deployed at the edge of your network and routes incoming traffic to your internal services (aka "north-south" traffic). [Istio](https://istio.io/) is a service mesh for microservices, and is designed to add application-level Layer (L7) observability, routing, and resilience to service-to-service traffic (aka "east-west" traffic). Both Istio and $productName$ are built using [Envoy](https://www.envoyproxy.io). - -$productName$ and Istio can be deployed together on Kubernetes. In this configuration, $productName$ manages -traditional edge functions such as authentication, TLS termination, and edge routing. Istio mediates communication -from $productName$ to services, and communication between services. - -This allows the operator to have the best of both worlds: a high performance, modern edge service ($productName$) combined with a state-of-the-art service mesh (Istio). While Istio has introduced a [Gateway](https://istio.io/latest/docs/tasks/traffic-management/ingress/ingress-control/#configuring-ingress-using-an-istio-gateway) abstraction, $productName$ still has a much broader feature set for edge routing than Istio. For more on this topic, see our blog post on [API Gateway vs Service Mesh](https://blog.getambassador.io/api-gateway-vs-service-mesh-104c01fa4784). - -This guide explains how to take advantage of both $productName$ and Istio to have complete control and observability over how requests are made in your cluster: - -- [Install Istio](#install-istio) and configure auto-injection -- [Install $productName$ with Istio integration](#install-edge) -- [Configure an mTLS `TLSContext`](#configure-an-mtls-tlscontext) -- [Route to services using mTLS](#route-to-services-using-mtls) - -If desired, you may also - -- [Enable strict mTLS](#enable-strict-mtls) -- [Configure Prometheus metrics collection](#configure-prometheus-metrics-collection) -- [Configure Istio distributed tracing](#configure-istio-distributed-tracing) - -To follow this guide, you need: - -- A Kubernetes cluster version 1.15 and above -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- Istio version 1.10 or higher - -## Install Istio - -Start by [installing Istio](https://istio.io/docs/setup/getting-started/). Any supported installation method for -Istio will work for use with $productName$. - -### Configure Istio Auto-Injection - -Istio functions by supplying a sidecar container running Envoy with every service in the mesh (including -$productName$). The sidecar is what enforces Istio policies for traffic to and from the service, notably -including mTLS encryption and certificate handling. As such, it is very important that the sidecar be -correctly supplied for every service in the mesh! - -While it is possible to manage sidecars by hand, it is far easier to allow Istio to automatically inject -the sidecar as necessary. To do this, set the `istio-injection` label on each Kubernetes Namespace for -which you want auto-injection: - -```yaml -kubectl label namespace $namespace istio-injection=enabled --overwrite -``` - - - The following example uses the `istio-injection` label to arrange for auto-injection in the - `$productNamespace$` Namespace below. You can manage sidecar injection by hand if you wish; what - is critical is that every service that participates in the Istio mesh have the Istio - sidecar. - - -## Install $productName$ with Istio Integration - -Properly integrating $productName$ with Istio provides support for: - -* [Mutual TLS (mTLS)](../../topics/running/tls/mtls/), with certificates managed by Istio, to allow end-to-end encryption -for east-west traffic; -* Automatic generation of Prometheus metrics for services; and -* Istio distributed tracing for end-to-end observability. - -The simplest way to enable everything is to install $productName$ using [Helm](https://helm.sh), though -you can use manual installation with YAML if you wish. - -### Installation with Helm (Recommended) - -To install with Helm, write the following YAML to a file called `istio-integration.yaml`: - -```yaml -# Listeners are required in $productName$ 2.0. -# This will create the two default Listeners for HTTP on port 8080 and HTTPS on port 8443. -createDefaultListeners: true - -# These are annotations that will be added to the $productName$ pods. -podAnnotations: - # These first two annotations tell Istio not to try to do port management for the - # $productName$ pod itself. Though these annotations are placed on the $productName$ - # pods, they are interpreted by Istio. - traffic.sidecar.istio.io/includeInboundPorts: "" # do not intercept any inbound ports - traffic.sidecar.istio.io/includeOutboundIPRanges: "" # do not intercept any outbound traffic - - # We use proxy.istio.io/config to tell the Istio proxy to write newly-generated mTLS certificates - # into /etc/istio-certs, which will be mounted below. Though this annotation is placed on the - # $productName$ pods, it is interpreted by Istio. - proxy.istio.io/config: | - proxyMetadata: - OUTPUT_CERTS: /etc/istio-certs - - # We use sidecar.istio.io/userVolumeMount to tell the Istio sidecars to mount the istio-certs - # volume at /etc/istio-certs, allowing the sidecars to see the generated certificates. Though - # this annotation is placed on the $productName$ pods, it is interpreted by Istio. - sidecar.istio.io/userVolumeMount: '[{"name": "istio-certs", "mountPath": "/etc/istio-certs"}]' - -# We define a single storage volume called "istio-certs". It starts out empty, and Istio -# uses it to communicate mTLS certs between the Istio proxy and the Istio sidecars (see the -# annotations above). -volumes: - - emptyDir: - medium: Memory - name: istio-certs - -# We also tell $productName$ to mount the "istio-certs" volume at /etc/istio-certs in the -# $productName$ pod. This gives $productName$ access to the mTLS certificates, too. -volumeMounts: - - name: istio-certs - mountPath: /etc/istio-certs/ - readOnly: true - -# Finally, we need to set some environment variables for $productName$. -env: - # AMBASSADOR_ISTIO_SECRET_DIR tells $productName$ to look for Istio mTLS certs, and to - # make them available as a secret named "istio-certs". - AMBASSADOR_ISTIO_SECRET_DIR: "/etc/istio-certs" - - # AMBASSADOR_ENVOY_BASE_ID is set to prevent collisions with the Istio sidecar's Envoy, - # which runs with base-id 0. - AMBASSADOR_ENVOY_BASE_ID: "1" -``` - -To install $productName$ with Helm, use these values to configure Istio integration: - -1. Create the `$productNamespace$` Namespace: - - ```yaml - kubectl create namespace $productNamespace$ - ``` - -2. Enable Istio auto-injection for it: - - ```yaml - kubectl label namespace $productNamespace$ istio-injection=enabled --overwrite - ``` - -3. Make sure the Helm repo is configured: - - ```bash - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - -4. Use Helm to install $productName$ in $productNamespace$: - - ```bash - helm install $productHelmName$ --namespace $productNamespace$ -f istio-integration.yaml datawire/$productHelmName$ && \ - kubectl -n $productNamespace$ wait --for condition=available --timeout=90s deploy -lapp.kubernetes.io/instance=$productDeploymentName$ - ``` - -### Installation Using YAML - -To install using YAML files, you need to manually incorporate the contents of the `istio-integration.yaml` -file shown above into your deployment YAML: - -* `pod-annotations` should be configured as Kubernetes `annotations` on the $productName$ Pods; -* `volumes`, `volumeMounts`, and `env` contents should be included in the $productDeploymentName$ Deployment; and -* you must also label the $productNamespace$ Namespace for auto-injection as described above. - -### Configuring an Existing Installation - -If you have already installed $productName$ and want to enable Istio: - -1. Install Istio. -2. Label the $productNamespace$ namespace for Istio auto-injection, as above. -2. Edit the $productName$ Deployments to contain the `annotations`, `volumes`, `volumeMounts`, and `env` elements - shown above. - * If you installed with Helm, you can use `helm upgrade` with `-f istio-integration.yaml` to modify the - installation for you. -3. Restart the $productName$ pods. - -## Configure an mTLS `TLSContext` - -After configuring $productName$ for Istio integration, the Istio mTLS certificates are available within -$productName$: - -- Both the `istio-proxy` sidecar and $productName$ mount the `istio-certs` volume at `/etc/istio-certs`. -- The `istio-proxy` sidecar saves the mTLS certificates into `/etc/istio-certs` (per the `OUTPUT_CERTS` - environment variable). -- $productName$ reads the mTLS certificates from `/etc/istio-certs` (per the `AMBASSADOR_ISTIO_SECRET_DIR` - environment variable) and creates a Secret named `istio-certs`. - - - At present, the Secret name istio-certs cannot be changed. - - -To make use of the `istio-certs` Secret, create a `TLSContext` referencing it: - - ```shell - $ kubectl apply -f - < - You must either explicitly specify port 80 in your 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 - <This guide applies to $OSSproductName$. It will not work correctly -on $AESproductName$. - -$productName$ can validate incoming requests before routing them to a backing service. In this tutorial, we'll configure $productName$ to use a simple third party rate limit service. (If you don't want to implement your own rate limiting service, $AESproductName$ integrates a [powerful, flexible rate limiting service](/docs/edge-stack/latest/topics/using/rate-limits/rate-limits/).) - -## Before you get started - -This tutorial assumes you have already followed the $productName$ [Installation](../../topics/install/) and [Quickstart Tutorial](../../tutorials/quickstart-demo) guides. If you haven't done that already, you should do so now. - -Once completed, you'll have a Kubernetes cluster running $productName$ and the Quote service. Let's walk through adding rate limiting to this setup. - -## 1. Deploy the rate limit service - -$productName$ delegates the actual rate limit logic to a third party service. We've written a [simple rate limit service](https://github.com/emissary-ingress/ratelimit-example) that: - -- listens for requests on port 5000; -- handles gRPC `shouldRateLimit` requests; -- allows requests with the `x-emissary-test-allow: "true"` header; and -- marks all other requests as `OVER_LIMIT`; - -Here's the YAML we'll start with: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: RateLimitService -metadata: - name: ratelimit - namespace: default -spec: - service: "ratelimit-example.default:5000" - protocol_version: v3 - domain: emissary - failure_mode_deny: true ---- -apiVersion: v1 -kind: Service -metadata: - name: ratelimit-example -spec: - selector: - app: ratelimit-example - ports: - - name: http - port: 5000 - targetPort: http ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: ratelimit-example -spec: - replicas: 1 - selector: - matchLabels: - app: ratelimit-example - template: - metadata: - labels: - app: ratelimit-example - spec: - containers: - - name: ratelimit-example - image: docker.io/emissaryingress/ratelimit-example:v3 - imagePullPolicy: Always - ports: - - name: http - containerPort: 5000 - resources: - limits: - memory: "64Mi" - cpu: "100m" -``` - -Once this configuration is applied Kubernetes will startup the example ratelimit service and $productName$ will be configured to use the rate limit service. The `RateLimitService` configuration tells $productName$ to: - -- Send `ShouldRateLimit` check request to `ratelimit-example.default:5000` -- Configure Envoy to talk with the example ratelimit service using transport protocol `v3` (*only supported version*) -- Set the labels `domain` to `emissary` (*labels discussed below*) - -If $productName$ cannot contact the rate limit service, it can either fail open or closed. The default is to fail open but in the example `RateLimitService` above we toggled it via the `failure_mode_deny: true` setting. - -## 2. Configure $productName$ Mappings - -$productName$ only validates requests on `Mapping`s which set labels to use for rate limiting, so you'll need to apply `labels` to your `Mapping`s to enable rate limiting. For more information -on the labelling process, see the [Rate Limits configuration documentation](../../topics/using/rate-limits/). - - - These labels require Mapping resources with apiVersion getambassador.io/v2 or newer — if you're updating an old installation, check the - apiVersion! - - -Labels are added to a `Mapping` using the `labels` field and `domain` configured in the `RateLimitService`. For example: - -```yaml -labels: - emissary: - - request_label_group: - - x-emissary-test-allow: - request_headers: - key: "x-emissary-test-allow" - header_name: "x-emissary-test-allow" -``` - -If we were to apply it the `Mapping` definition for the `quote-backend` service outlined in the quick-start then it would look like this: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: "*" - prefix: /backend/ - service: quote - labels: - emissary: - - request_label_group: - - x-emissary-test-allow: - request_headers: - key: "x-emissary-test-allow" - header_name: "x-emissary-test-allow" -``` - -Note that the `key` could be anything you like, but our example rate limiting service expects it to match the name of the header. Also note that since our `RateLimitService` expects to use labels in the -`emissary` domain, our `Mapping` must match. - -## 2. Test rate limiting - -If we `curl` to a rate-limited URL: - -```shell -curl -i -H "x-emissary-test-allow: probably" http://$LB_ENDPOINT/backend/ -``` - -We get a `429` status code, since we are being rate limited. - -```shell -HTTP/1.1 429 Too Many Requests -content-type: text/html; charset=utf-8 -content-length: 0 -``` - -If we set the correct header value to the service request, we will get a quote successfully: - -```shell -$ curl -i -H "x-emissary-test-allow: true" http://$LB_ENDPOINT/backend/ - -TCP_NODELAY set -* Connected to 35.196.173.175 (35.196.173.175) port 80 (#0) -> GET /backed HTTP/1.1 -> Host: 35.196.173.175 -> User-Agent: curl/7.54.0 -> Accept: */* -> -< HTTP/1.1 200 OK -< content-type: application/json -< date: Thu, 23 May 2019 15:25:06 GMT -< content-length: 172 -< x-envoy-upstream-service-time: 0 -< server: envoy -< -{ - "server": "humble-blueberry-o2v493st", - "quote": "Nihilism gambles with lives, happiness, and even destiny itself!", - "time": "2019-05-23T15:25:06.544417902Z" -* Connection #0 to host 54.165.128.189 left intact -} -``` - -## More - -For more details about configuring the external rate limit service, read the [rate limit documentation](../../topics/using/rate-limits/). diff --git a/content/en/docs/3.2/howtos/route.md b/content/en/docs/3.2/howtos/route.md deleted file mode 100644 index b2d9dc0f..00000000 --- a/content/en/docs/3.2/howtos/route.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -description: "$productName$ uses the Mapping resource to map a resource, like a URL prefix, to a Kubernetes service or web service." ---- - -import Alert from '@material-ui/lab/Alert'; - -# Get traffic from the edge - -
-

Contents

- -* [Examples](#examples) -* [Applying a Mapping Resource](#applying-a-mapping-resouce) -* [Resources](#resources) -* [Services](#services) -* [Extending Mappings](#extending-mappings) -* [Best Practices](#best-practices) -* [What's next?](#img-classos-logo-srcimageslogopng-whats-next) - -
- -The core $productName$ resource used to manage cluster ingress is the `Mapping` resource. - -**A `Mapping` resource routes a URL path (or prefix) to a service (either a Kubernetes service or other web service).** - - - Remember that Listener and Host resources are  - required for a functioning $productName$ installation that can route traffic!
- Learn more about Listener.
- Learn more about Host. - - -## Examples - -This `Mapping` would route requests to `https:///webapp/` to the `webapp-svc` Service. **This is not a -complete example on its own; see below.** - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: webapp-mapping -spec: - prefix: /webapp/ - service: webapp-svc -``` - -| Name | Type | Description | -| :--- | :--- | :--- | -| `metadata.name` | String | Identifies the Mapping. | -| `spec.prefix` | String | The URL prefix identifying your resource. [See below](#resources) on how $productName$ handles resources. | -| `spec.service` | String | The service handling the resource. If a Kubernetes service, it must include the namespace (in the format `service.namespace`) if the service is in a different namespace than $productName$. [See below](#services) on service name formatting.| - -Here's another example using a web service that maps requests to `/httpbin/` to `http://httpbin.org` (again, **this is not a -complete example on its own; see below**): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin-mapping -spec: - prefix: /httpbin/ - service: http://httpbin.org - hostname: '*' -``` - -### Complete example configuration - -For demonstration purposes, here's a possible way of combining a `Listener`, a `Host`, and both `Mapping`s above that is complete and functional: - -- it will accept HTTP or HTTPS on port 8443; -- $productName$ is terminating TLS; -- HTTPS to `foo.example.com` will be routed as above; -- HTTP to `foo.example.com` will be redirected to HTTPS; -- HTTP or HTTPS to other hostnames will be rejected; and -- the associations between the `Listener`, the `Host`, and the `Mappings` use Kubernetes `label`s. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: foo-example-secret -data: - tls.crt: -certificate PEM- - tls.key: -secret key PEM- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-8443 -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: - selector: - matchLabels: - exampleName: basic-https ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host - labels: - exampleName: basic-https -spec: - hostname: "foo.example.com" - tlsSecret: - name: foo-example-secret - selector: - matchLabels: - exampleName: basic-https ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: webapp-mapping - labels: - exampleName: basic-https -spec: - prefix: /webapp/ - service: webapp-svc - hostname: 'foo.example.com' ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin-mapping - labels: - exampleName: basic-https -spec: - prefix: /httpbin/ - service: http://httpbin.org - hostname: 'foo.example.com' - -``` - -Note the addition of `label`s and `selector`s to explicitly specify which resources should associate in this example. - - - Learn more about Listener.
- Learn more about Host. - - -## Applying a Mapping resource - -A Mapping resource can be managed using the same workflow as any other Kubernetes resources (like a Service or Deployment). For example, if the above Mapping is saved into a file called `httpbin-mapping.yaml`, the following command will apply the configuration directly to $productName$: - -``` -kubectl apply -f httpbin-mapping.yaml -``` - -For production use, best practice is to store the file in a version control system and apply the changes with a continuous deployment pipeline. The Ambassador Operating Model provides more detail. - -## Resources - -To $productName$, a resource is a group of one or more URLs that all share a common prefix in the URL path. For example, these URLs all share the `/resource1/` path prefix, so `/resource1/` can be considered a single resource: - -* `https://ambassador.example.com/resource1/foo` -* `https://ambassador.example.com/resource1/bar` -* `https://ambassador.example.com/resource1/baz/zing` - -On the other hand, these URLs share only the prefix `/` -- you _could_ tell $productName$ to treat them as a single resource, but it's probably not terribly useful. - -* `https://ambassador.example.com/resource1/foo` -* `https://ambassador.example.com/resource2/bar` -* `https://ambassador.example.com/resource3/baz/zing` - -Note that the length of the prefix doesn't matter; a prefix like `/v1/this/is/my/very/long/resource/name/` is valid. - -Also note that $productName$ does not actually require the prefix to start and end with `/` -- however, in practice, it's a good idea. Specifying a prefix of `/man` would match all of the following, which probably is not what was intended: - -* `https://ambassador.example.com/man/foo` -* `https://ambassador.example.com/mankind` -* `https://ambassador.example.com/man-it-is/really-hot-today` - -## Services - -$productName$ routes traffic to a service. A service is defined as `[scheme://]service[.namespace][:port]`. Everything except for the service is optional. - -- `scheme` can be either `http` or `https`; if not present, the default is `http`. -- `service` is the name of a service (typically the service name in Kubernetes or Consul); it is not allowed to contain the `.` character. -- `namespace` is the namespace in which the service is running. Starting with $productName$ 1.0.0, if not supplied, it defaults to the namespace in which the Mapping resource is defined. The default behavior can be configured using the [Module resource](../../topics/running/ambassador). When using a Consul resolver, `namespace` is not allowed. -- `port` is the port to which a request should be sent. If not specified, it defaults to `80` when the scheme is `http` or `443` when the scheme is `https`. Note that the [resolver](../../topics/running/resolvers) may return a port in which case the `port` setting is ignored. - -While using service.namespace.svc.cluster.local may work for Kubernetes resolvers, the preferred syntax is service.namespace. - - -## Extending Mappings - -Mapping resources support a rich set of annotations to customize the specific routing behavior. Here's an example service for implementing the [CQRS pattern](https://docs.microsoft.com/en-us/azure/architecture/patterns/cqrs) (using HTTP): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-get -spec: - prefix: /cqrs/ - method: GET - service: getcqrs - hostname: '*' ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-put -spec: - prefix: /cqrs/ - method: PUT - service: putcqrs - hostname: '*' -``` - -## Best Practices - -$productName$'s configuration is assembled from multiple YAML blocks which are managed by independent application teams. This implies that certain best practices should be followed. - -#### $productName$'s configuration should be under version control. - -While you can always read back the $productName$'s configuration from Kubernetes or its diagnostic service, the $productName$ will not do versioning for you. - -#### $productName$ tries to not start with a broken configuration, but it's not perfect. - -Gross errors will result in the $productName$ refusing to start, in which case `kubectl logs` will be helpful. However, it's always possible to map a resource to the wrong service, or use the wrong `rewrite` rules. $productName$ can't detect that on its own, although its [diagnostic service](../../topics/running/diagnostics/) can help you figure it out. - -#### Be careful of mapping collisions. - -If two different developers try to map `/myservice/` to something, this can lead to unexpected behavior. $productName$'s [canary deployment](../../topics/using/canary/) logic means that it's more likely that traffic will be split between them than that it will throw an error -- again, the diagnostic service can help you here. - -#### Unless specified, mapping attributes cannot be applied to any other resource type. - -## 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/content/en/docs/3.2/howtos/tls-termination.md b/content/en/docs/3.2/howtos/tls-termination.md deleted file mode 100644 index 2bbdf4c4..00000000 --- a/content/en/docs/3.2/howtos/tls-termination.md +++ /dev/null @@ -1,192 +0,0 @@ -# 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/content/en/docs/3.2/howtos/tracing-datadog.md b/content/en/docs/3.2/howtos/tracing-datadog.md deleted file mode 100644 index d627e29f..00000000 --- a/content/en/docs/3.2/howtos/tracing-datadog.md +++ /dev/null @@ -1,63 +0,0 @@ -# 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/content/en/docs/3.2/howtos/tracing-zipkin.md b/content/en/docs/3.2/howtos/tracing-zipkin.md deleted file mode 100644 index 37ddc902..00000000 --- a/content/en/docs/3.2/howtos/tracing-zipkin.md +++ /dev/null @@ -1,129 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Distributed tracing with Zipkin - -In this tutorial, we'll configure $productName$ to initiate a trace on some sample requests, and use Zipkin 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. Deploy Zipkin - -In this tutorial, you will use a simple deployment of the open-source [Zipkin](https://github.com/openzipkin/zipkin/wiki) distributed tracing system to store and visualize $productName$-generated traces. The trace data will be stored in memory within the Zipkin container, and you will be able to explore the traces via the Zipkin web UI. - -First, add the following YAML to a file named `zipkin.yaml`. This configuration will create a Zipkin Deployment that uses the [openzipkin/zipkin](https://hub.docker.com/r/openzipkin/zipkin/) container image and also an associated Service. We will also include a `TracingService` that configures $productName$ to use the Zipkin service (running on the default port of 9411) to provide tracing support. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TracingService -metadata: - name: tracing -spec: - service: "zipkin:9411" - driver: zipkin - config: {} ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: zipkin -spec: - replicas: 1 - selector: - matchLabels: - app: zipkin - template: - metadata: - labels: - app: zipkin - spec: - containers: - - name: zipkin - image: openzipkin/zipkin - env: - # note: in-memory storage holds all data in memory, purging older data upon a span limit. - # you should use a proper storage in production environments - - name: STORAGE_TYPE - value: mem ---- -apiVersion: v1 -kind: Service -metadata: - labels: - name: zipkin - name: zipkin -spec: - ports: - - port: 9411 - targetPort: 9411 - selector: - app: zipkin -``` - -Next, deploy this configuration into your cluster: - -``` -$ kubectl apply -f zipkin.yaml -``` - -As a final step we want to restart $productName$ as this is necessary to add the tracing header. This command will restart all the Pods (assuming $productName$ is installed in the ambassador namespace): - -``` -$ kubectl -n ambassador rollout restart deploy -``` - - Restarting $productName$ is required after deploying a Tracing Service for changes to take effect. - - -## 2. 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/backend/ -``` - -## 3. Test traces - -To test things out, we'll need to access the Zipkin UI. If you're on Kubernetes, get the name of the Zipkin pod: - -``` -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -ambassador-5ffcfc798-c25dc 2/2 Running 0 1d -prometheus-prometheus-0 2/2 Running 0 113d -zipkin-868b97667c-58v4r 1/1 Running 0 2h -``` - -And then use `kubectl port-forward` to access the pod: - -``` -$ kubectl port-forward zipkin-868b97667c-58v4r 9411 -``` - -Open your web browser to `http://localhost:9411` for the Zipkin UI. - -If you're on `minikube` you can access the `NodePort` directly, and this ports number can be obtained via the `minikube services list` command. If you are using `Docker for Mac/Windows`, you can use the `kubectl get svc` command to get the same information. - -``` -$ minikube service list -|-------------|----------------------|-----------------------------| -| NAMESPACE | NAME | URL | -|-------------|----------------------|-----------------------------| -| default | ambassador-admin | http://192.168.99.107:30319 | -| default | ambassador | http://192.168.99.107:31893 | -| default | zipkin | http://192.168.99.107:31043 | -|-------------|----------------------|-----------------------------| -``` - -Open your web browser to the Zipkin dashboard `http://192.168.99.107:31043/zipkin/`. - -In the Zipkin UI, click on the "Find Traces" button to get a listing instrumented traces. Each of the traces that are displayed can be clicked on, which provides further information about each span and associated metadata. - -## Learn more - -For more details about configuring the external tracing service, read the documentation on [external tracing](../../topics/running/services/tracing-service). diff --git a/content/en/docs/3.2/howtos/websockets.md b/content/en/docs/3.2/howtos/websockets.md deleted file mode 100644 index 25cac7da..00000000 --- a/content/en/docs/3.2/howtos/websockets.md +++ /dev/null @@ -1,43 +0,0 @@ -# WebSocket connections - -$productName$ makes it easy to access your services from outside your -application, and this includes services that use WebSockets. Only a -small amount of additional configuration is required, which is as -simple as telling the Mapping to allow "upgrading" from the HTTP protocol to -the "websocket" protocol: - -```yaml -allow_upgrade: -- websocket -``` - -## Example WebSocket service - -The example configuration below demonstrates the addition of the `allow_upgrade:` attribute to support websockets. The use of `use_websocket` is now deprecated. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: my-service-mapping -spec: - hostname: "*" - prefix: /my-service/ - service: my-service - allow_upgrade: - - websocket - ---- -kind: Service -apiVersion: v1 -metadata: - name: my-service -spec: - selector: - app: MyApp - ports: - - protocol: TCP - port: 80 - targetPort: 9376 -``` diff --git a/content/en/docs/3.2/images/Auth0_JWT.png b/content/en/docs/3.2/images/Auth0_JWT.png deleted file mode 100644 index e18155f5..00000000 Binary files a/content/en/docs/3.2/images/Auth0_JWT.png and /dev/null differ diff --git a/content/en/docs/3.2/images/Auth0_domain_clientID.png b/content/en/docs/3.2/images/Auth0_domain_clientID.png deleted file mode 100644 index a7f8edf6..00000000 Binary files a/content/en/docs/3.2/images/Auth0_domain_clientID.png and /dev/null differ diff --git a/content/en/docs/3.2/images/Auth0_method_callback_origins.png b/content/en/docs/3.2/images/Auth0_method_callback_origins.png deleted file mode 100644 index 8d31138e..00000000 Binary files a/content/en/docs/3.2/images/Auth0_method_callback_origins.png and /dev/null differ diff --git a/content/en/docs/3.2/images/aes-success.png b/content/en/docs/3.2/images/aes-success.png deleted file mode 100644 index 66f28d3f..00000000 Binary files a/content/en/docs/3.2/images/aes-success.png and /dev/null differ diff --git a/content/en/docs/3.2/images/ambassador-arch.png b/content/en/docs/3.2/images/ambassador-arch.png deleted file mode 100644 index 5a5cb652..00000000 Binary files a/content/en/docs/3.2/images/ambassador-arch.png and /dev/null differ diff --git a/content/en/docs/3.2/images/ambassador-logo.svg b/content/en/docs/3.2/images/ambassador-logo.svg deleted file mode 100644 index 1f0e06a8..00000000 --- a/content/en/docs/3.2/images/ambassador-logo.svg +++ /dev/null @@ -1,49 +0,0 @@ - - - - ambassador logo@1x - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.2/images/ambassador_oidc_flow.jpg b/content/en/docs/3.2/images/ambassador_oidc_flow.jpg deleted file mode 100644 index 4f1c0c7e..00000000 Binary files a/content/en/docs/3.2/images/ambassador_oidc_flow.jpg and /dev/null differ diff --git a/content/en/docs/3.2/images/apple.png b/content/en/docs/3.2/images/apple.png deleted file mode 100644 index 8b8277f1..00000000 Binary files a/content/en/docs/3.2/images/apple.png and /dev/null differ diff --git a/content/en/docs/3.2/images/auth-flow.png b/content/en/docs/3.2/images/auth-flow.png deleted file mode 100644 index e1ba4387..00000000 Binary files a/content/en/docs/3.2/images/auth-flow.png and /dev/null differ diff --git a/content/en/docs/3.2/images/authentication-icon.svg b/content/en/docs/3.2/images/authentication-icon.svg deleted file mode 100644 index 342e8a3d..00000000 --- a/content/en/docs/3.2/images/authentication-icon.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_897228_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.2/images/blackbird.png b/content/en/docs/3.2/images/blackbird.png deleted file mode 100644 index 1f10e5cc..00000000 Binary files a/content/en/docs/3.2/images/blackbird.png and /dev/null differ diff --git a/content/en/docs/3.2/images/canary-release-overview.png b/content/en/docs/3.2/images/canary-release-overview.png deleted file mode 100644 index c683a23d..00000000 Binary files a/content/en/docs/3.2/images/canary-release-overview.png and /dev/null differ diff --git a/content/en/docs/3.2/images/configure-icon.svg b/content/en/docs/3.2/images/configure-icon.svg deleted file mode 100644 index 0f556840..00000000 --- a/content/en/docs/3.2/images/configure-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_858572_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.2/images/consul-ambassador.png b/content/en/docs/3.2/images/consul-ambassador.png deleted file mode 100644 index c4911624..00000000 Binary files a/content/en/docs/3.2/images/consul-ambassador.png and /dev/null differ diff --git a/content/en/docs/3.2/images/container-inner-dev-loop.png b/content/en/docs/3.2/images/container-inner-dev-loop.png deleted file mode 100644 index 06586cd6..00000000 Binary files a/content/en/docs/3.2/images/container-inner-dev-loop.png and /dev/null differ diff --git a/content/en/docs/3.2/images/datawire-logo.svg b/content/en/docs/3.2/images/datawire-logo.svg deleted file mode 100644 index fb45872c..00000000 --- a/content/en/docs/3.2/images/datawire-logo.svg +++ /dev/null @@ -1,27 +0,0 @@ - - - - Group 3 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.2/images/diag-documentation.png b/content/en/docs/3.2/images/diag-documentation.png deleted file mode 100644 index b00ee575..00000000 Binary files a/content/en/docs/3.2/images/diag-documentation.png and /dev/null differ diff --git a/content/en/docs/3.2/images/diag-general-info.png b/content/en/docs/3.2/images/diag-general-info.png deleted file mode 100644 index ef31e0f4..00000000 Binary files a/content/en/docs/3.2/images/diag-general-info.png and /dev/null differ diff --git a/content/en/docs/3.2/images/diag-notices.png b/content/en/docs/3.2/images/diag-notices.png deleted file mode 100644 index e916e743..00000000 Binary files a/content/en/docs/3.2/images/diag-notices.png and /dev/null differ diff --git a/content/en/docs/3.2/images/diag-resolvers.png b/content/en/docs/3.2/images/diag-resolvers.png deleted file mode 100644 index 759de6bd..00000000 Binary files a/content/en/docs/3.2/images/diag-resolvers.png and /dev/null differ diff --git a/content/en/docs/3.2/images/diag-routes-diagnostics-page.png b/content/en/docs/3.2/images/diag-routes-diagnostics-page.png deleted file mode 100644 index ab16fba8..00000000 Binary files a/content/en/docs/3.2/images/diag-routes-diagnostics-page.png and /dev/null differ diff --git a/content/en/docs/3.2/images/diag-routes.png b/content/en/docs/3.2/images/diag-routes.png deleted file mode 100644 index 97a0fb29..00000000 Binary files a/content/en/docs/3.2/images/diag-routes.png and /dev/null differ diff --git a/content/en/docs/3.2/images/diag-service-diag-overview.png b/content/en/docs/3.2/images/diag-service-diag-overview.png deleted file mode 100644 index 0c490c56..00000000 Binary files a/content/en/docs/3.2/images/diag-service-diag-overview.png and /dev/null differ diff --git a/content/en/docs/3.2/images/diag-servicecs-in-use.png b/content/en/docs/3.2/images/diag-servicecs-in-use.png deleted file mode 100644 index c60b19c6..00000000 Binary files a/content/en/docs/3.2/images/diag-servicecs-in-use.png and /dev/null differ diff --git a/content/en/docs/3.2/images/diagnostics-example.png b/content/en/docs/3.2/images/diagnostics-example.png deleted file mode 100644 index 6c825b0c..00000000 Binary files a/content/en/docs/3.2/images/diagnostics-example.png and /dev/null differ diff --git a/content/en/docs/3.2/images/diagnostics.png b/content/en/docs/3.2/images/diagnostics.png deleted file mode 100644 index 29248703..00000000 Binary files a/content/en/docs/3.2/images/diagnostics.png and /dev/null differ diff --git a/content/en/docs/3.2/images/docker-compose.png b/content/en/docs/3.2/images/docker-compose.png deleted file mode 100644 index b8829521..00000000 Binary files a/content/en/docs/3.2/images/docker-compose.png and /dev/null differ diff --git a/content/en/docs/3.2/images/docker.png b/content/en/docs/3.2/images/docker.png deleted file mode 100644 index 1f35e5ea..00000000 Binary files a/content/en/docs/3.2/images/docker.png and /dev/null differ diff --git a/content/en/docs/3.2/images/edge-stack-1.13.4.png b/content/en/docs/3.2/images/edge-stack-1.13.4.png deleted file mode 100644 index 954ac1a9..00000000 Binary files a/content/en/docs/3.2/images/edge-stack-1.13.4.png and /dev/null differ diff --git a/content/en/docs/3.2/images/edge-stack-1.13.7-json-logging.png b/content/en/docs/3.2/images/edge-stack-1.13.7-json-logging.png deleted file mode 100644 index 4a47cbdf..00000000 Binary files a/content/en/docs/3.2/images/edge-stack-1.13.7-json-logging.png and /dev/null differ diff --git a/content/en/docs/3.2/images/edge-stack-1.13.7-memory.png b/content/en/docs/3.2/images/edge-stack-1.13.7-memory.png deleted file mode 100644 index 9c415ba3..00000000 Binary files a/content/en/docs/3.2/images/edge-stack-1.13.7-memory.png and /dev/null differ diff --git a/content/en/docs/3.2/images/edge-stack-1.13.7-tcpmapping-consul.png b/content/en/docs/3.2/images/edge-stack-1.13.7-tcpmapping-consul.png deleted file mode 100644 index c455a47f..00000000 Binary files a/content/en/docs/3.2/images/edge-stack-1.13.7-tcpmapping-consul.png and /dev/null differ diff --git a/content/en/docs/3.2/images/edge-stack-1.13.8-cloud-bugfix.png b/content/en/docs/3.2/images/edge-stack-1.13.8-cloud-bugfix.png deleted file mode 100644 index 6beaf653..00000000 Binary files a/content/en/docs/3.2/images/edge-stack-1.13.8-cloud-bugfix.png and /dev/null differ diff --git a/content/en/docs/3.2/images/emissary-1.13.10-cors-origin.png b/content/en/docs/3.2/images/emissary-1.13.10-cors-origin.png deleted file mode 100644 index b7538e5f..00000000 Binary files a/content/en/docs/3.2/images/emissary-1.13.10-cors-origin.png and /dev/null differ diff --git a/content/en/docs/3.2/images/fast-icon.svg b/content/en/docs/3.2/images/fast-icon.svg deleted file mode 100644 index 354542ee..00000000 --- a/content/en/docs/3.2/images/fast-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1187990_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.2/images/features-icons/basic-authentication.svg b/content/en/docs/3.2/images/features-icons/basic-authentication.svg deleted file mode 100644 index 2bd19edf..00000000 --- a/content/en/docs/3.2/images/features-icons/basic-authentication.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_897228_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.2/images/features-icons/canary-release.svg b/content/en/docs/3.2/images/features-icons/canary-release.svg deleted file mode 100644 index f8de57d9..00000000 --- a/content/en/docs/3.2/images/features-icons/canary-release.svg +++ /dev/null @@ -1,27 +0,0 @@ - - - - Group 25 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.2/images/features-icons/cors.svg b/content/en/docs/3.2/images/features-icons/cors.svg deleted file mode 100644 index e559d924..00000000 --- a/content/en/docs/3.2/images/features-icons/cors.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_111967_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.2/images/features-icons/datadog.png b/content/en/docs/3.2/images/features-icons/datadog.png deleted file mode 100644 index eea05f8c..00000000 Binary files a/content/en/docs/3.2/images/features-icons/datadog.png and /dev/null differ diff --git a/content/en/docs/3.2/images/features-icons/datadog.svg b/content/en/docs/3.2/images/features-icons/datadog.svg deleted file mode 100644 index e46e8118..00000000 --- a/content/en/docs/3.2/images/features-icons/datadog.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Screen Shot 2018-04-05 at 8.22.25 AM - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.2/images/features-icons/diagnostics.svg b/content/en/docs/3.2/images/features-icons/diagnostics.svg deleted file mode 100644 index 940e1bc2..00000000 --- a/content/en/docs/3.2/images/features-icons/diagnostics.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_196445_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.2/images/features-icons/distributed-tracing.png b/content/en/docs/3.2/images/features-icons/distributed-tracing.png deleted file mode 100644 index 6b69e28c..00000000 Binary files a/content/en/docs/3.2/images/features-icons/distributed-tracing.png and /dev/null differ diff --git a/content/en/docs/3.2/images/features-icons/grpc.png b/content/en/docs/3.2/images/features-icons/grpc.png deleted file mode 100644 index b2f5a0d9..00000000 Binary files a/content/en/docs/3.2/images/features-icons/grpc.png and /dev/null differ diff --git a/content/en/docs/3.2/images/features-icons/prometheus.svg b/content/en/docs/3.2/images/features-icons/prometheus.svg deleted file mode 100644 index d5252a66..00000000 --- a/content/en/docs/3.2/images/features-icons/prometheus.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - prometheus_logo_grey - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.2/images/features-icons/rate-limiting.svg b/content/en/docs/3.2/images/features-icons/rate-limiting.svg deleted file mode 100644 index f1b6eacb..00000000 --- a/content/en/docs/3.2/images/features-icons/rate-limiting.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - Group 10 - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.2/images/features-icons/regex-routing.svg b/content/en/docs/3.2/images/features-icons/regex-routing.svg deleted file mode 100644 index 113b53b5..00000000 --- a/content/en/docs/3.2/images/features-icons/regex-routing.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_699774_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.2/images/features-icons/request-transformers.svg b/content/en/docs/3.2/images/features-icons/request-transformers.svg deleted file mode 100644 index 0b13e2dc..00000000 --- a/content/en/docs/3.2/images/features-icons/request-transformers.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_96239_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.2/images/features-icons/shadowing.svg b/content/en/docs/3.2/images/features-icons/shadowing.svg deleted file mode 100644 index 9e85eee1..00000000 --- a/content/en/docs/3.2/images/features-icons/shadowing.svg +++ /dev/null @@ -1,15 +0,0 @@ - - - - shadow - Created with Sketch. - - - - - - - - - - diff --git a/content/en/docs/3.2/images/features-icons/statsd.png b/content/en/docs/3.2/images/features-icons/statsd.png deleted file mode 100644 index 28374438..00000000 Binary files a/content/en/docs/3.2/images/features-icons/statsd.png and /dev/null differ diff --git a/content/en/docs/3.2/images/features-icons/statsd.svg b/content/en/docs/3.2/images/features-icons/statsd.svg deleted file mode 100644 index cabc90db..00000000 --- a/content/en/docs/3.2/images/features-icons/statsd.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - 88eb31f74479e422e4e9abfc6c2b00ee - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.2/images/features-icons/third-party-auth.svg b/content/en/docs/3.2/images/features-icons/third-party-auth.svg deleted file mode 100644 index 5359a24a..00000000 --- a/content/en/docs/3.2/images/features-icons/third-party-auth.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_511233_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.2/images/features-icons/timeouts.svg b/content/en/docs/3.2/images/features-icons/timeouts.svg deleted file mode 100644 index 47f63056..00000000 --- a/content/en/docs/3.2/images/features-icons/timeouts.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_587034_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.2/images/features-icons/tls-termination.svg b/content/en/docs/3.2/images/features-icons/tls-termination.svg deleted file mode 100644 index 6a631a96..00000000 --- a/content/en/docs/3.2/images/features-icons/tls-termination.svg +++ /dev/null @@ -1,17 +0,0 @@ - - - - noun_63544_cc - Created with Sketch. - - - - - - - - - - - - diff --git a/content/en/docs/3.2/images/features-icons/url-rewrite.svg b/content/en/docs/3.2/images/features-icons/url-rewrite.svg deleted file mode 100644 index 023e2e05..00000000 --- a/content/en/docs/3.2/images/features-icons/url-rewrite.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1295942_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.2/images/features-icons/websockets.svg b/content/en/docs/3.2/images/features-icons/websockets.svg deleted file mode 100644 index af17b9c0..00000000 --- a/content/en/docs/3.2/images/features-icons/websockets.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - noun_50814_cc - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.2/images/features-table.jpg b/content/en/docs/3.2/images/features-table.jpg deleted file mode 100644 index 3de2eb4f..00000000 Binary files a/content/en/docs/3.2/images/features-table.jpg and /dev/null differ diff --git a/content/en/docs/3.2/images/gRPC-TLS-Ambassador.png b/content/en/docs/3.2/images/gRPC-TLS-Ambassador.png deleted file mode 100644 index 0189253e..00000000 Binary files a/content/en/docs/3.2/images/gRPC-TLS-Ambassador.png and /dev/null differ diff --git a/content/en/docs/3.2/images/gRPC-TLS-Originate.png b/content/en/docs/3.2/images/gRPC-TLS-Originate.png deleted file mode 100644 index 1b62010d..00000000 Binary files a/content/en/docs/3.2/images/gRPC-TLS-Originate.png and /dev/null differ diff --git a/content/en/docs/3.2/images/github-login.png b/content/en/docs/3.2/images/github-login.png deleted file mode 100644 index cfd4d4bf..00000000 Binary files a/content/en/docs/3.2/images/github-login.png and /dev/null differ diff --git a/content/en/docs/3.2/images/global-features-bg.svg b/content/en/docs/3.2/images/global-features-bg.svg deleted file mode 100644 index a39c5232..00000000 --- a/content/en/docs/3.2/images/global-features-bg.svg +++ /dev/null @@ -1,34 +0,0 @@ - - - - ambassador_logo@2x - Created with Sketch. - - - - - - - - diff --git a/content/en/docs/3.2/images/grafana.png b/content/en/docs/3.2/images/grafana.png deleted file mode 100644 index 03912506..00000000 Binary files a/content/en/docs/3.2/images/grafana.png and /dev/null differ diff --git a/content/en/docs/3.2/images/grpc-tls.png b/content/en/docs/3.2/images/grpc-tls.png deleted file mode 100644 index 4d705ff0..00000000 Binary files a/content/en/docs/3.2/images/grpc-tls.png and /dev/null differ diff --git a/content/en/docs/3.2/images/helm-navy.png b/content/en/docs/3.2/images/helm-navy.png deleted file mode 100644 index a9710143..00000000 Binary files a/content/en/docs/3.2/images/helm-navy.png and /dev/null differ diff --git a/content/en/docs/3.2/images/helm.png b/content/en/docs/3.2/images/helm.png deleted file mode 100644 index 1c5af71b..00000000 Binary files a/content/en/docs/3.2/images/helm.png and /dev/null differ diff --git a/content/en/docs/3.2/images/highly-available-icon.svg b/content/en/docs/3.2/images/highly-available-icon.svg deleted file mode 100644 index 9cb3eff9..00000000 --- a/content/en/docs/3.2/images/highly-available-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1205522_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.2/images/jaeger.png b/content/en/docs/3.2/images/jaeger.png deleted file mode 100644 index 3b821c09..00000000 Binary files a/content/en/docs/3.2/images/jaeger.png and /dev/null differ diff --git a/content/en/docs/3.2/images/kubernetes.png b/content/en/docs/3.2/images/kubernetes.png deleted file mode 100644 index a392a886..00000000 Binary files a/content/en/docs/3.2/images/kubernetes.png and /dev/null differ diff --git a/content/en/docs/3.2/images/left-arrow.svg b/content/en/docs/3.2/images/left-arrow.svg deleted file mode 100644 index 75cdc7f1..00000000 --- a/content/en/docs/3.2/images/left-arrow.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Path 2 - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.2/images/linux.png b/content/en/docs/3.2/images/linux.png deleted file mode 100644 index 1832c594..00000000 Binary files a/content/en/docs/3.2/images/linux.png and /dev/null differ diff --git a/content/en/docs/3.2/images/logo.png b/content/en/docs/3.2/images/logo.png deleted file mode 100644 index 701f63ba..00000000 Binary files a/content/en/docs/3.2/images/logo.png and /dev/null differ diff --git a/content/en/docs/3.2/images/mapping-editor.png b/content/en/docs/3.2/images/mapping-editor.png deleted file mode 100644 index f8b751a1..00000000 Binary files a/content/en/docs/3.2/images/mapping-editor.png and /dev/null differ diff --git a/content/en/docs/3.2/images/network-architecture.png b/content/en/docs/3.2/images/network-architecture.png deleted file mode 100644 index 3217b3e1..00000000 Binary files a/content/en/docs/3.2/images/network-architecture.png and /dev/null differ diff --git a/content/en/docs/3.2/images/penguin-background.svg b/content/en/docs/3.2/images/penguin-background.svg deleted file mode 100644 index 7affc0d5..00000000 --- a/content/en/docs/3.2/images/penguin-background.svg +++ /dev/null @@ -1,102 +0,0 @@ - - - - @2xambassador_logo - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.2/images/pro-iap.png b/content/en/docs/3.2/images/pro-iap.png deleted file mode 100644 index 787265d8..00000000 Binary files a/content/en/docs/3.2/images/pro-iap.png and /dev/null differ diff --git a/content/en/docs/3.2/images/quote.svg b/content/en/docs/3.2/images/quote.svg deleted file mode 100644 index bab6e871..00000000 --- a/content/en/docs/3.2/images/quote.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - “ - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.2/images/right-arrow.svg b/content/en/docs/3.2/images/right-arrow.svg deleted file mode 100644 index 627144c6..00000000 --- a/content/en/docs/3.2/images/right-arrow.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Path 2 Copy - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.2/images/routing-icon.svg b/content/en/docs/3.2/images/routing-icon.svg deleted file mode 100644 index bd860b13..00000000 --- a/content/en/docs/3.2/images/routing-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1062254_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.2/images/self-service-features-bg.svg b/content/en/docs/3.2/images/self-service-features-bg.svg deleted file mode 100644 index 40bc400a..00000000 --- a/content/en/docs/3.2/images/self-service-features-bg.svg +++ /dev/null @@ -1,93 +0,0 @@ - - - - Group 8 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - SELF-SERVICE FEATURES - - - - diff --git a/content/en/docs/3.2/images/shadowing.png b/content/en/docs/3.2/images/shadowing.png deleted file mode 100644 index 097ecbd5..00000000 Binary files a/content/en/docs/3.2/images/shadowing.png and /dev/null differ diff --git a/content/en/docs/3.2/images/speedometers.png b/content/en/docs/3.2/images/speedometers.png deleted file mode 100644 index 7ce2c2a2..00000000 Binary files a/content/en/docs/3.2/images/speedometers.png and /dev/null differ diff --git a/content/en/docs/3.2/images/tp-architecture.png b/content/en/docs/3.2/images/tp-architecture.png deleted file mode 100644 index 20ae3589..00000000 Binary files a/content/en/docs/3.2/images/tp-architecture.png and /dev/null differ diff --git a/content/en/docs/3.2/images/tp-tutorial-1.png b/content/en/docs/3.2/images/tp-tutorial-1.png deleted file mode 100644 index ee68dc7d..00000000 Binary files a/content/en/docs/3.2/images/tp-tutorial-1.png and /dev/null differ diff --git a/content/en/docs/3.2/images/tp-tutorial-2.png b/content/en/docs/3.2/images/tp-tutorial-2.png deleted file mode 100644 index 129dc6ee..00000000 Binary files a/content/en/docs/3.2/images/tp-tutorial-2.png and /dev/null differ diff --git a/content/en/docs/3.2/images/tp-tutorial-3.png b/content/en/docs/3.2/images/tp-tutorial-3.png deleted file mode 100644 index 946629fc..00000000 Binary files a/content/en/docs/3.2/images/tp-tutorial-3.png and /dev/null differ diff --git a/content/en/docs/3.2/images/tp-tutorial-4.png b/content/en/docs/3.2/images/tp-tutorial-4.png deleted file mode 100644 index cb6e7a9d..00000000 Binary files a/content/en/docs/3.2/images/tp-tutorial-4.png and /dev/null differ diff --git a/content/en/docs/3.2/images/trad-inner-dev-loop.png b/content/en/docs/3.2/images/trad-inner-dev-loop.png deleted file mode 100644 index 618b674f..00000000 Binary files a/content/en/docs/3.2/images/trad-inner-dev-loop.png and /dev/null differ diff --git a/content/en/docs/3.2/images/windows.png b/content/en/docs/3.2/images/windows.png deleted file mode 100644 index a065dc17..00000000 Binary files a/content/en/docs/3.2/images/windows.png and /dev/null differ diff --git a/content/en/docs/3.2/images/xkcd.png b/content/en/docs/3.2/images/xkcd.png deleted file mode 100644 index ed0d5c33..00000000 Binary files a/content/en/docs/3.2/images/xkcd.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/edge-stack-1.13.4.png b/content/en/docs/3.2/release-notes/edge-stack-1.13.4.png deleted file mode 100644 index 954ac1a9..00000000 Binary files a/content/en/docs/3.2/release-notes/edge-stack-1.13.4.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/edge-stack-1.13.7-json-logging.png b/content/en/docs/3.2/release-notes/edge-stack-1.13.7-json-logging.png deleted file mode 100644 index 4a47cbdf..00000000 Binary files a/content/en/docs/3.2/release-notes/edge-stack-1.13.7-json-logging.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/edge-stack-1.13.7-memory.png b/content/en/docs/3.2/release-notes/edge-stack-1.13.7-memory.png deleted file mode 100644 index 9c415ba3..00000000 Binary files a/content/en/docs/3.2/release-notes/edge-stack-1.13.7-memory.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/edge-stack-1.13.7-tcpmapping-consul.png b/content/en/docs/3.2/release-notes/edge-stack-1.13.7-tcpmapping-consul.png deleted file mode 100644 index c455a47f..00000000 Binary files a/content/en/docs/3.2/release-notes/edge-stack-1.13.7-tcpmapping-consul.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/edge-stack-1.13.8-cloud-bugfix.png b/content/en/docs/3.2/release-notes/edge-stack-1.13.8-cloud-bugfix.png deleted file mode 100644 index 6beaf653..00000000 Binary files a/content/en/docs/3.2/release-notes/edge-stack-1.13.8-cloud-bugfix.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/edge-stack-2.0.0-host_crd.png b/content/en/docs/3.2/release-notes/edge-stack-2.0.0-host_crd.png deleted file mode 100644 index c77ef528..00000000 Binary files a/content/en/docs/3.2/release-notes/edge-stack-2.0.0-host_crd.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/edge-stack-2.0.0-ingressstatus.png b/content/en/docs/3.2/release-notes/edge-stack-2.0.0-ingressstatus.png deleted file mode 100644 index 6856d308..00000000 Binary files a/content/en/docs/3.2/release-notes/edge-stack-2.0.0-ingressstatus.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/edge-stack-2.0.0-insecure_action_hosts.png b/content/en/docs/3.2/release-notes/edge-stack-2.0.0-insecure_action_hosts.png deleted file mode 100644 index 79c20bad..00000000 Binary files a/content/en/docs/3.2/release-notes/edge-stack-2.0.0-insecure_action_hosts.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/edge-stack-2.0.0-listener.png b/content/en/docs/3.2/release-notes/edge-stack-2.0.0-listener.png deleted file mode 100644 index ea45a02b..00000000 Binary files a/content/en/docs/3.2/release-notes/edge-stack-2.0.0-listener.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/edge-stack-2.0.0-prune_routes.png b/content/en/docs/3.2/release-notes/edge-stack-2.0.0-prune_routes.png deleted file mode 100644 index bc43229f..00000000 Binary files a/content/en/docs/3.2/release-notes/edge-stack-2.0.0-prune_routes.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/edge-stack-2.0.0-tlscontext.png b/content/en/docs/3.2/release-notes/edge-stack-2.0.0-tlscontext.png deleted file mode 100644 index 68dbad80..00000000 Binary files a/content/en/docs/3.2/release-notes/edge-stack-2.0.0-tlscontext.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/edge-stack-2.0.0-v3alpha1.png b/content/en/docs/3.2/release-notes/edge-stack-2.0.0-v3alpha1.png deleted file mode 100644 index c0ac3596..00000000 Binary files a/content/en/docs/3.2/release-notes/edge-stack-2.0.0-v3alpha1.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/emissary-1.13.10-cors-origin.png b/content/en/docs/3.2/release-notes/emissary-1.13.10-cors-origin.png deleted file mode 100644 index b7538e5f..00000000 Binary files a/content/en/docs/3.2/release-notes/emissary-1.13.10-cors-origin.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/emissary-ga.png b/content/en/docs/3.2/release-notes/emissary-ga.png deleted file mode 100644 index 062f043a..00000000 Binary files a/content/en/docs/3.2/release-notes/emissary-ga.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/tada.png b/content/en/docs/3.2/release-notes/tada.png deleted file mode 100644 index c8832e8e..00000000 Binary files a/content/en/docs/3.2/release-notes/tada.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/v2.0.4-k8s-1.22.png b/content/en/docs/3.2/release-notes/v2.0.4-k8s-1.22.png deleted file mode 100644 index ed9b0415..00000000 Binary files a/content/en/docs/3.2/release-notes/v2.0.4-k8s-1.22.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/v2.0.4-l7depth.png b/content/en/docs/3.2/release-notes/v2.0.4-l7depth.png deleted file mode 100644 index 9314324c..00000000 Binary files a/content/en/docs/3.2/release-notes/v2.0.4-l7depth.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/v2.0.4-mapping-dns-type.png b/content/en/docs/3.2/release-notes/v2.0.4-mapping-dns-type.png deleted file mode 100644 index 7770c77d..00000000 Binary files a/content/en/docs/3.2/release-notes/v2.0.4-mapping-dns-type.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/v2.0.4-v3alpha1.png b/content/en/docs/3.2/release-notes/v2.0.4-v3alpha1.png deleted file mode 100644 index 9c50b8fb..00000000 Binary files a/content/en/docs/3.2/release-notes/v2.0.4-v3alpha1.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/v2.0.4-version.png b/content/en/docs/3.2/release-notes/v2.0.4-version.png deleted file mode 100644 index 9481b7db..00000000 Binary files a/content/en/docs/3.2/release-notes/v2.0.4-version.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/v2.0.5-auth-circuit-breaker.png b/content/en/docs/3.2/release-notes/v2.0.5-auth-circuit-breaker.png deleted file mode 100644 index cac8cf7b..00000000 Binary files a/content/en/docs/3.2/release-notes/v2.0.5-auth-circuit-breaker.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/v2.0.5-mappingselector.png b/content/en/docs/3.2/release-notes/v2.0.5-mappingselector.png deleted file mode 100644 index 31942ede..00000000 Binary files a/content/en/docs/3.2/release-notes/v2.0.5-mappingselector.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/v2.1.0-canary.png b/content/en/docs/3.2/release-notes/v2.1.0-canary.png deleted file mode 100644 index 39d3bbbf..00000000 Binary files a/content/en/docs/3.2/release-notes/v2.1.0-canary.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/v2.1.0-gzip-enabled.png b/content/en/docs/3.2/release-notes/v2.1.0-gzip-enabled.png deleted file mode 100644 index 061fcbc9..00000000 Binary files a/content/en/docs/3.2/release-notes/v2.1.0-gzip-enabled.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/v2.1.0-smoother-migration.png b/content/en/docs/3.2/release-notes/v2.1.0-smoother-migration.png deleted file mode 100644 index ebd77497..00000000 Binary files a/content/en/docs/3.2/release-notes/v2.1.0-smoother-migration.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/v2.1.2-annotations.png b/content/en/docs/3.2/release-notes/v2.1.2-annotations.png deleted file mode 100644 index b5498c3c..00000000 Binary files a/content/en/docs/3.2/release-notes/v2.1.2-annotations.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/v2.1.2-host-mapping-matching.png b/content/en/docs/3.2/release-notes/v2.1.2-host-mapping-matching.png deleted file mode 100644 index 1cfba5ed..00000000 Binary files a/content/en/docs/3.2/release-notes/v2.1.2-host-mapping-matching.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/v2.1.2-mapping-cors.png b/content/en/docs/3.2/release-notes/v2.1.2-mapping-cors.png deleted file mode 100644 index f76ea01c..00000000 Binary files a/content/en/docs/3.2/release-notes/v2.1.2-mapping-cors.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/v2.1.2-mapping-less-weighted.png b/content/en/docs/3.2/release-notes/v2.1.2-mapping-less-weighted.png deleted file mode 100644 index 7e299062..00000000 Binary files a/content/en/docs/3.2/release-notes/v2.1.2-mapping-less-weighted.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/v2.1.2-mapping-no-rewrite.png b/content/en/docs/3.2/release-notes/v2.1.2-mapping-no-rewrite.png deleted file mode 100644 index 5d3d5a29..00000000 Binary files a/content/en/docs/3.2/release-notes/v2.1.2-mapping-no-rewrite.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/v2.2.0-cloud.png b/content/en/docs/3.2/release-notes/v2.2.0-cloud.png deleted file mode 100644 index 5923fcb4..00000000 Binary files a/content/en/docs/3.2/release-notes/v2.2.0-cloud.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/v2.2.0-percent-escape.png b/content/en/docs/3.2/release-notes/v2.2.0-percent-escape.png deleted file mode 100644 index df4d81b9..00000000 Binary files a/content/en/docs/3.2/release-notes/v2.2.0-percent-escape.png and /dev/null differ diff --git a/content/en/docs/3.2/release-notes/v2.2.0-tls-cert-validation.png b/content/en/docs/3.2/release-notes/v2.2.0-tls-cert-validation.png deleted file mode 100644 index f8635b5a..00000000 Binary files a/content/en/docs/3.2/release-notes/v2.2.0-tls-cert-validation.png and /dev/null differ diff --git a/content/en/docs/3.2/releaseNotes.yml b/content/en/docs/3.2/releaseNotes.yml deleted file mode 100644 index 1e334905..00000000 --- a/content/en/docs/3.2/releaseNotes.yml +++ /dev/null @@ -1,1310 +0,0 @@ -# -*- fill-column: 100 -*- - -# This file should be placed in the folder for the version of the -# product that's meant to be documented. A `/release-notes` page will -# be automatically generated and populated at build time. -# -# Note that an entry needs to be added to the `doc-links.yml` file in -# order to surface the release notes in the table of contents. -# -# The YAML in this file should contain: -# -# changelog: An (optional) URL to the CHANGELOG for the product. -# items: An array of releases with the following attributes: -# - version: The (optional) version number of the release, if applicable. -# - date: The date of the release in the format YYYY-MM-DD. -# - notes: An array of noteworthy changes included in the release, each having the following attributes: -# - type: The type of change, one of `bugfix`, `feature`, `security` or `change`. -# - title: A short title of the noteworthy change. -# - body: >- -# Two or three sentences describing the change and why it -# is noteworthy. This is HTML, not plain text or -# markdown. It is handy to use YAML's ">-" feature to -# allow line-wrapping. -# - image: >- -# The URL of an image that visually represents the -# noteworthy change. This path is relative to the -# `release-notes` directory; if this file is -# `FOO/releaseNotes.yml`, then the image paths are -# relative to `FOO/release-notes/`. -# - docs: The path to the documentation page where additional information can be found. -# - href: A path from the root to a resource on the getambassador website, takes precedence over a docs link. - -changelog: https://github.com/emissary-ingress/emissary/blob/$branch$/CHANGELOG.md -items: - - 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 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: 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.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/content/en/docs/3.2/topics/concepts/architecture.md b/content/en/docs/3.2/topics/concepts/architecture.md deleted file mode 100644 index fe9e0bd3..00000000 --- a/content/en/docs/3.2/topics/concepts/architecture.md +++ /dev/null @@ -1,27 +0,0 @@ -# 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). - -![Architecture](../../images/ambassador-arch.png) - -## 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/content/en/docs/3.2/topics/concepts/gitops-continuous-delivery.md b/content/en/docs/3.2/topics/concepts/gitops-continuous-delivery.md deleted file mode 100644 index 336a1c66..00000000 --- a/content/en/docs/3.2/topics/concepts/gitops-continuous-delivery.md +++ /dev/null @@ -1,66 +0,0 @@ -# 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/content/en/docs/3.2/topics/concepts/index.md b/content/en/docs/3.2/topics/concepts/index.md deleted file mode 100644 index 2d02a027..00000000 --- a/content/en/docs/3.2/topics/concepts/index.md +++ /dev/null @@ -1,10 +0,0 @@ -# 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/content/en/docs/3.2/topics/concepts/kubernetes-network-architecture.md b/content/en/docs/3.2/topics/concepts/kubernetes-network-architecture.md deleted file mode 100644 index 6650aa60..00000000 --- a/content/en/docs/3.2/topics/concepts/kubernetes-network-architecture.md +++ /dev/null @@ -1,52 +0,0 @@ -# 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: - -
- -![Kubernetes Network Architecture](../../../../../../images/documentation/kubernetes-network.inline.svg) - -
- -Each of the components in this topology is discussed in further detail below. - -### Load balancer - -The load balancer is deployed outside of the Kubernetes cluster. Typically, the load balancer also has one or more static IP addresses assigned to it. A DNS entry is then created to map a domain name (e.g., example.com) to the static IP address. - -Cloud infrastructure providers such as Amazon Web Services, Azure, Digital Ocean, and Google make it easy to create these load balancers directly from Kubernetes. This is done by creating a Kubernetes service of `type: LoadBalancer`. When this service is created, the cloud provider will use the metadata contained in the Kubernetes service definition to provision a load balancer. - -If the Kubernetes cluster is deployed in a private data center, an external load balancer is still generally used. Provisioning of this load balancer usually requires the involvement of the data center operations team. - -In both the private data center and cloud infrastructure case, the external load balancer should be configured to point to the edge proxy. - -### Edge Proxy / ingress controller - -The Edge Proxy is typically a Layer 7 proxy that is deployed directly in the cluster. The core function of the edge proxy is to accept incoming traffic from the external load balancer and route the traffic to Kubernetes services. The edge proxy should be configured using Kubernetes manifests. This enables a common management workflow for both the edge proxy and Kubernetes services. - -The most popular approach to configuring edge proxies is with the Kubernetes ingress resource. When an edge proxy can process ingress resources, it is called an ingress controller. Not all edge proxies are ingress controllers (because they can't process ingress resources), but all ingress controllers are edge proxies. - -The ingress resource is a Kubernetes standard. As such, it is a lowest common denominator resource. In practice, users find that the ingress resource is insufficient in scope to address the requirements for edge routing. Semantics such as TLS termination, redirecting to TLS, timeouts, rate limiting, and authentication are all beyond the scope of the ingress resource. - -$productName$ can function as an ingress controller (i.e., it reads ingress resources), although it also includes many other capabilities that are beyond the scope of the ingress specification. Most $productName$ users find that the various additional capabilities of $productName$ are essential, and end up using $productName$'s extensions to the ingress resource, instead of using ingress resources themselves. - -### Kubernetes services and Pods - -Each instance of your application is deployed in a Kubernetes pod. As the workload on your application increases or decreases, Kubernetes can automatically add or remove pods. A Kubernetes _service_ represents a group of pods that comprise the same version of a given application. Traffic can be routed to the pods via a Kubernetes service, or it can be routed directly to the pods. - -When traffic is routed to the pods via a Kubernetes service, Kubernetes uses a built-in mechanism called `kube-proxy` to load balance traffic between the pods. Due to its implementation, `kube-proxy` is a Layer 4 proxy, i.e., it load balances at a connection level. For particular types of traffic such as HTTP/2 and gRPC, this form of load balancing is particularly problematic as it can easily result in a very uneven load balancing configuration. - -Traffic can also be routed directly to pods, bypassing the Kubernetes service. Since pods are much more ephemeral than Kubernetes services, this approach requires an edge proxy that is optimized for this use case. In particular, the edge proxy needs to support real-time discovery of pods, and be able to dynamically update pod locations without downtime. - -$productName$ supports routing both to Kubernetes services and directly to pods. - -## Further reading - -* [Kubernetes Ingress 101](https://blog.getambassador.io/kubernetes-ingress-nodeport-load-balancers-and-ingress-controllers-6e29f1c44f2d) -* [Envoy Proxy Performance on Kubernetes](/resources/envoyproxy-performance-on-k8s/) diff --git a/content/en/docs/3.2/topics/concepts/microservices-api-gateways.md b/content/en/docs/3.2/topics/concepts/microservices-api-gateways.md deleted file mode 100644 index ba95b8fc..00000000 --- a/content/en/docs/3.2/topics/concepts/microservices-api-gateways.md +++ /dev/null @@ -1,60 +0,0 @@ -# Microservices API gateways - -A microservices API gateway is an API gateway designed to accelerate the development workflow of independent services teams. A microservices API gateway provides all the functionality for a team to independently publish, monitor, and update a microservice. - -This focus on accelerating the development workflow is distinct from the purpose of traditional API gateways, which focus on the challenges of managing APIs. Over the past decade, organizations have worked to expose internal systems through well-defined APIs. The challenge of safely exposing hundreds or thousands of APIs to end-users (both internal and external) led to the emergence of API gateways. Over time, API gateways have become centralized, mission critical pieces of infrastructure that control access to these APIs. - -In this article, we'll discuss how the difference in business objective (productivity vs management) results in a very different API gateway. - -## Microservices organization - -In a microservices organization, small teams of developers work independently from each other to rapidly deliver functionality to the customer. In order for each service team to work independently, with a productive workflow, a services team needs to be able to: - -1. Publish their service, so that others can use the service -2. Monitor their service, to see how well it's working -3. Test and update their service, so they can keep on improving the service - -The team needs to do all of this *without* requiring assistance from another operations or platform team--as soon as a services team requires another team, they're no longer working independently, and this can lead to bottlenecks. - -For service publication, a microservices API gateway provides a static address for consumers, and dynamically route requests to the appropriate service address. In addition, providing authentication and TLS termination for security are typical considerations in exposing a service to other consumers. - -Understanding the end-user experience of a service is crucial to improving the service. For example, a software update could inadvertently impact the latency of certain requests. A microservices API gateway is well situated to collect key observability metrics on end-user traffic as it routes traffic to the end service. - -A microservices API gateway also supports dynamically routing user requests to different service versions for canary testing. By routing a small fraction of end-user requests to a new version of a service, service teams can safely test the impact of new updates to a small subset of users. - -## Microservices API Gateways vs. enterprise API Gateways - -At first glance, the use case described above may be fulfilled with an enterprise-focused API gateway. While this may be true, the actual emphasis of enterprise API gateways and microservices API gateways are somewhat different: - -| Use case | Traditional Enterprise API gateway | Microservices API gateway | -|---------------|-------------------|------------------------------| -| Primary Purpose | Expose, compose, and manage internal business APIs | Expose and observe internal business services | -| Publishing Functionality | API management team or service team registers / updates gateway via admin API | Service team registers / updates gateway via declarative code as part of the deployment process | -| Monitoring | Admin and operations focused e.g. meter API calls per consumer, report errors (e.g. internal 5XX). | Developer focused e.g. latency, traffic, errors, saturation | -| Handling and Debugging Issues | L7 error-handling (e.g. custom error page or payload). Run gateway/API with additional logging. Troubleshoot issue in staging environment | Configure more detailed monitoring. Enable traffic shadowing and / or canarying | -| Testing | Operate multiple environments for QA, Staging, and Production. Automated integration testing, and gated API deployment. Use client-driven API versioning for compatibility and stability (e.g. semver) | Facilitate canary routing for dynamic testing (taking care with data mutation side effects). Use developer-driven service versioning for upgrade management | -| Local Development | Deploy gateway locally (via installation script, Vagrant or Docker), and attempt to mitigate infrastructure differences with production. Use language-specific gateway mocking and stubbing frameworks | Deploy gateway locally via service orchestration platform (e.g. Kubernetes) | - -## Self-service publishing - -A team needs to be able to publish a new service to customers without requiring an operations or API management team. This ability to self-service for deployment and publication enables the team to keep the feature release velocity high. While a traditional enterprise API gateway may provide a simple mechanism (e.g., REST API) for publishing a new service, in practice, the usage is often limited to the use of a dedicated team that is responsible for the gateway. The primary reason for limiting publication to a single team is to provide an additional (human) safety mechanism: an errant API call could have potentially disastrous effects on production. - -Microservices API gateways utilize mechanisms that enable service teams to easily *and* safely publish new services, with the inherent understanding that the producing team are responsible for their service, and will fix an issue if one occurs. A microservices gateway provides configurable monitoring for issue detection, and provides hooks for debugging, such as inspecting traffic or traffic shifting/duplication. - -## Monitoring and rate limiting - -A common business model for APIs is metering, where a consumer is charged different fees depending on API usage. Traditional enterprise API gateways excel in this use case: they provide functionality for monitoring per-client usage of an API, and the ability to limit usage when the client exceeds their quota. - -A microservice gateway also requires monitoring and rate limiting, but for different reasons. Monitoring user-visible metrics such as throughput, latency, and availability, are important to ensure that new updates don't impact the end-user. Robust end-user metrics are critical to allowing rapid, incremental updates. Rate limiting is used to improve the overall resilience of a service. When a service is not responding as expected, an API gateway can throttle incoming requests to allow a service to recover and prevent a cascade failure. - -## Testing and updates - -A microservices application has multiple services, each of which is being independently updated. Automated pre-production testing of a moving target is necessary but not sufficient for microservices. Canary testing, where a small percentage of production traffic is routed to a new service version, is an important tool to help test an update. By limiting a new service version to a small percentage of users, the impact of a service failure is limited. - -In a traditional enterprise API gateway, routing is used to isolate or compose/aggregate changing API versions. Automated pre-production testing and manual post-production verification and exploration are required. - -## Summary - -Traditional enterprise API gateways are designed to solve the challenges of API management. While they may appear to solve some of the challenges of adopting microservices, the reality is that a microservices workflow creates a different set of requirements. Integrating a microservices API gateway into your development workflow empowers service teams to self-publish, monitor, and update their service, quickly and safely. This will enable your organization to ship software more rapidly, and with more reliability than ever before. - -For further reading on how an API Gateway can accelerate continuous delivery, read [this blog post](https://blog.getambassador.io/continuous-delivery-how-can-an-api-gateway-help-or-hinder-1ff15224ec4d). diff --git a/content/en/docs/3.2/topics/concepts/progressive-delivery.md b/content/en/docs/3.2/topics/concepts/progressive-delivery.md deleted file mode 100644 index f2ade27f..00000000 --- a/content/en/docs/3.2/topics/concepts/progressive-delivery.md +++ /dev/null @@ -1,47 +0,0 @@ -# Progressive delivery - -Today's cloud-native applications may consist of hundreds of services, each of which are being updated at any time. Thus, many cloud-native organizations augment regression test strategies with testing in production using progressive delivery techniques. - -Progressive Delivery is an approach for releasing software to production users. In the progressive delivery model, software is released to ever growing subsets of production users. This approach reduces the blast radius in the event of a failure. - -## Why test in production? - -Modern cloud applications are continuously deployed, as different teams rapidly update their respective services. Deploying and testing updates in a pre-production staging environment introduces a bottleneck to the speed of iteration. More importantly, staging environments are not representative of what will be running in production when the deployment actually occurs given the velocity of service updates and changes in production. Testing in production addresses both of these challenges: developers evaluate their changes in the real-world environment, enabling rapid iteration. - -## Progressive delivery strategies - -There are a number of different strategies for progressive delivery. These include: - -* Feature flags, where specific features are made available to specific user groups -* Canary releases, where a (small) percentage of traffic is routed to a new version of a service before the service is full production -* Traffic shadowing, where real user traffic is copied, or shadowed, from production to the service under test - -Observability is a critical requirement for testing in production. Regardless of progressive delivery strategy, collecting key metrics around latency, traffic, errors, and saturation (the [“Four Golden Signals of Monitoring”](https://landing.google.com/sre/sre-book/chapters/monitoring-distributed-systems/#xref_monitoring_golden-signals)) provides valuable insight into the stability and performance of a new version of the service. Moreover, application developers can compare the metrics (e.g., latency) between the production version and an updated version. If the metrics are similar, then updates can proceed with much greater confidence. - -$productName$ supports a variety of strategies for progressive delivery. These strategies are discussed in further detail below. - -### Canary releases - -Canary releases shifts a small amount of real user traffic from production to the service under test. - -The user will see the direct response from the canary version of the service from any traffic that is shifted to the canary release, and they will not trigger or see the response from the current production released version of the service. The canary results can also be verified (both the downstream response and associated upstream side effects), but it is key to understand that any side effects will be persisted. - -In addition to allowing verification that the service is not crashing or otherwise behaving badly from an operational perspective when dealing with real user traffic and behavior, canary releasing allows user validation. For example, if a business KPI performs worse for all canaried requests, then this most likely indicates that the canaried service should not be fully released in its current form. - -Canary tests can be automated, and are typically run after testing in a pre-production environment has been completed. The canary release is only visible to a fraction of actual users, and any bugs or negative changes can be reversed quickly by either routing traffic away from the canary or by rolling-back the canary deployment. - -![Canary release process overview](../../images/canary-release-overview.png) - -Canary releases are not a panacea. In particular, many services may not receive sufficient traffic in order for canary releases to provide useful information in an actionable timeframe. - -### Traffic shadowing - -This approach “shadows” or mirrors a small amount of real user traffic from production to the service under test. - -Although the shadowed results can be verified (both the downstream response and associated upstream side effects) they are not returned to the user -- the user only sees the results from the currently released service. Typically any side effects are not persisted or are executed as a no-op and verified (much like setting up a mock, and verifying that a method/function was called with the correct parameters). - -This allows verification that the service is not crashing or otherwise behaving badly from an operational perspective when dealing with real user traffic and behavior (and the larger the percentage of traffic shadowed, the higher the probability of confidence). - -## Further reading - -* [Canary release pattern](https://blog.getambassador.io/cloud-native-patterns-canary-release-1cb8f82d371a) diff --git a/content/en/docs/3.2/topics/concepts/rate-limiting-at-the-edge.md b/content/en/docs/3.2/topics/concepts/rate-limiting-at-the-edge.md deleted file mode 100644 index 3ab9d657..00000000 --- a/content/en/docs/3.2/topics/concepts/rate-limiting-at-the-edge.md +++ /dev/null @@ -1,34 +0,0 @@ ---- - description: Rate limiting concepts at the edge is a technique used to prevent a sudden or sustained increase in user traffic fr… ---- -# Rate limiting concepts at the edge - -Rate limiting at the edge is a technique that is used to prevent a sudden or sustained increase in user traffic from breaking an API or underlying service. On the Internet, users can do whatever they want to your APIs, as you have no direct control over these end-users. Whether it’s intentional or not, these users can impact the availability, responsiveness, and scalability of your service. - -## Two approaches: Rate limiting and load shedding - -Rate limiting use cases that fall into this scenario range from implementing functional requirements related to a business scenario -- for example, where requests from paying customers is prioritized over requests from non-paying trial users -- to implementing cross-functional requirements, such as resilience from a malicious actor attempting to issue a denial-of-service (DoS) attack. - -A closely related technique to rate limiting is load shedding, and this can be used to selectively prioritize traffic (by dropping requests) based on the state of the entire system. For example, if a backend data store has become overloaded and slow to respond, it may be appropriate to drop (or “shed”) low priority requests or requests that are not time sensitive. - -## Use cases and scenarios - -The table below outlines several scenarios where rate limiting and load shedding can provide an effective solution to a range of functional and cross-functional requirements. The “Type of Rate Limiter” column provides a summary of the category of rate limiting that would be most appropriate for the scenario, and the “Specifics” column outlines what business or system properties would be involved in computing rate limiting decisions. - -| Scenario | Type of Rate Limiter |                            Specifics                        -| --- | --- | --- | -**Fairness.** One or more users are sending large volumes of requests, and thus impacting other users of the API | **User request rate limiting -** restricts each user to a predetermined number of requests per time unit.

**Concurrent user request limiting -** limits the number of concurrent user requests that can be inflight at any given point in time. |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
  • Geographic rate limiter
  • Time-based rate limiter
-**Prioritisation.** The business model depends on handling high priority requests over others | **User request rate limiting** |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device, free vs non-free user etc)
-**Resilience.** The API backend cannot scale rapidly enough to meet request demand due to a technical issue. | **Backend utilisation load shedder -** rate limit based upon utilisation of aggregate backend instances.

**Node/server utilisation load shedder -** rate limit based upon utilisation of individual or isolated groups of compute nodes/servers. |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
-**Security.** Prevent bad actors from using a DoS attack to overwhelm services, fuzzing, or brute force attacks |**User request rate limiting**

**Node/server utilisation load shedder** |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
  • Service identifier load shedder e.g. login service, audit service
-**Responsiveness.** As per the Reactive Manifesto, responsive systems focus on providing rapid and consistent response times, establishing reliable upper bounds so they deliver a consistent quality of service | **Concurrent user request limiting**

**Backend utilisation load shedder**

**Node/server utilisation load shedder** |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
  • Service identifier load shedder e.g. login service, audit service
- -## Avoiding contention with rate limiting configuration: Decoupling Dev and Ops - -One of the core features of $productName$ is the decentralization of configuration, allowing operations and development teams to independently control $productName$, as well as individual application development teams to minimize collaboration when configuring independently deployable services. This same approach applies to rate limiting configuration. - -## Benefits of applying a rate limiter to the edge - -Modern applications and APIs can experience floods of traffic over a short time period (e.g. from achieving a HackerNews front page link), and increasingly bad actors and cyber criminals are targeting public-facing services. - -By implementing rate limiting and load shedding capabilities at the edge, a large amount of scenarios that are bad for business can be mitigated. These capabilities also make the life of the operations and development team that much easier, as the need to constantly firefight ingress traffic is reduced. diff --git a/content/en/docs/3.2/topics/install/ambassador-oss-community.md b/content/en/docs/3.2/topics/install/ambassador-oss-community.md deleted file mode 100644 index b53d1407..00000000 --- a/content/en/docs/3.2/topics/install/ambassador-oss-community.md +++ /dev/null @@ -1,14 +0,0 @@ -# Integration in community projects - -import Table from "../../../../../src/components/CommunityTable"; - -**$AESproductName$ is now available and includes additional functionality beyond the current $OSSproductName$.** -These features include automatic HTTPS, OAuth/OpenID Connect authentication support, integrated rate -limiting, a developer portal, and [more](/edge-stack-faq/). - -## $OSSproductName$ integrations - -If you still want to use just $OSSproductName$, don't worry! $OSSproductName$ -is currently available out-of-the-box in some Kubernetes installers and local environments. - -
\ No newline at end of file diff --git a/content/en/docs/3.2/topics/install/bare-metal.md b/content/en/docs/3.2/topics/install/bare-metal.md deleted file mode 100644 index 84ac1c8d..00000000 --- a/content/en/docs/3.2/topics/install/bare-metal.md +++ /dev/null @@ -1,93 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Install with bare metal - -In cloud environments, provisioning a readily available network load balancer with $productName$ is the best option for handling ingress into your Kubernetes cluster. When running Kubernetes on a bare metal setup, where network load balancers are not available by default, we need to consider different options for exposing $productName$. - -## Exposing $productName$ via NodePort - -The simplest way to expose an application in Kubernetes is via a `NodePort` service. In this configuration, we create the $productName$ service] and identify `type: NodePort` instead of `LoadBalancer`. Kubernetes will then create a service and assign that service a port to be exposed externally and direct traffic to $productName$ via the defined `port`. - -```yaml ---- -apiVersion: v1 -kind: Service -metadata: - name: ambassador -spec: - type: NodePort - ports: - - name: http - port: 8088 - targetPort: 8080 - nodePort: 30036 # Optional: Define the port you would like exposed - protocol: TCP - selector: - service: ambassador -``` - -Using a `NodePort` leaves $productName$ isolated from the host network, allowing the Kubernetes service to handle routing to $productName$ pods. You can drop-in this YAML to replace the `LoadBalancer` service in the [YAML installation guide](../yaml-install) and use `http://:/` as the host for requests. - -## Exposing $productName$ via host network - -When running $productName$ on a bare metal install of Kubernetes, you have the option to configure $productName$ pods to use the network of the host they are running on. This method allows you to bind $productName$ directly to port 80 or 443 so you won't need to identify the port in requests. - -i.e `http://:/` becomes `http:///` - -This can be configured by setting `hostNetwork: true` in the $productName$ deployment. `dnsPolicy: ClusterFirstWithHostNet` will also need to set to tell $productName$ to use *KubeDNS* when attempting to resolve mappings. - -```diff ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: ambassador -spec: - replicas: 1 - selector: - matchLabels: - service: ambassador - template: - metadata: - annotations: - sidecar.istio.io/inject: "false" - labels: - service: ambassador - app.kubernetes.io/managed-by: getambassador.io - spec: -+ hostNetwork: true -+ dnsPolicy: ClusterFirstWithHostNet - serviceAccountName: ambassador - containers: - - name: ambassador - image: docker.io/datawire/ambassador:$version$ - resources: - limits: - cpu: 1 - memory: 400Mi - requests: - cpu: 200m - memory: 100Mi - env: - - name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace - livenessProbe: - httpGet: - path: /ambassador/v0/check_alive - port: 8877 - initialDelaySeconds: 30 - periodSeconds: 3 - readinessProbe: - httpGet: - path: /ambassador/v0/check_ready - port: 8877 - initialDelaySeconds: 30 - periodSeconds: 3 - restartPolicy: Always -``` - -This configuration does not require a defined $productName$ service, so you can remove that service if you have defined one. - -**Note:** Before configuring $productName$ with this method, consider some of the functionality that is lost by bypassing the Kubernetes service including only having one $productName$ able to bind to port 8080 or 8443 per node and losing any load balancing that is typically performed by Kubernetes services. diff --git a/content/en/docs/3.2/topics/install/convert-to-v3alpha1.md b/content/en/docs/3.2/topics/install/convert-to-v3alpha1.md deleted file mode 100644 index 2d8dfb79..00000000 --- a/content/en/docs/3.2/topics/install/convert-to-v3alpha1.md +++ /dev/null @@ -1,275 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Convert Configuration to `getambassador.io/v3alpha1` - -Once your $productName$ $version$ installation is running, it is **strongly recommended** that -you convert your existing configuration resources from `getambassador.io/v2` to -`getambassador.io/v3alpha1`. - - - While it is not necessary to convert all your resources to getambassador.io/v3alpha1 - immediately, you should ultimately update them all for full functionality with $productName$ - - -In general, the best way to convert any resource is to start with `kubectl get`: using -`kubectl get -o yaml` on any `getambassador.io/v2` resource will cause $productName$ to -translate it to a `getambassador.io/v3alpha1` resource. You can then verify that the -`getambassador.io/v3alpha1` resource looks correct and re-apply it, which will convert the -stored copy to `getambassador.io/v3alpha1`. - -As you do the conversion, here are the things to bear in mind: - -## 1. `ambassador_id` must be an array, not a simple string. - -`getambassador.io/v2` allowed `ambassador_id` to be either an array of strings, or a simple -string. In `getambassador.io/v3alpha1`, only the array form is supported: instead of -`ambassador_id: "foo"`, use `ambassador_id: [ "foo" ]`. This applies to all $productName$ -resources, and is supported by all versions of Ambassador 1.X. - -## 2. You must have a `Listener` for each port on which $productName$ should listen. - - - Learn more about Listener - - -`Listener` is **mandatory**. Defining your own `Listener`(s) allows you to carefully -tailor the set of ports you actually need to use, and exactly which `Host` resources -are matched with them (see below). - -## 3. `Listener`, `Host`, and `Mapping` must be explicit about how they associate. - -You need to have `Listener`s, `Host`s, and `Mapping`s correctly associated with each other for $productName$ 2.X configuration. - -### 3.1. `Listener` and `Host` are associated through `Listener.hostBinding` - - - Learn more about Listener
- Learn more about Host - - -In a `Listener`, the `hostBinding` controls whether a given `Host` is associated with that `Listener`, as discussed in the [`Listener`](../../running/listener) documentation. -**The recommended setting is using `hostBinding.selector`** to choose only `Host`s that have a defined -Kubernetes label: - -```yaml -hostBinding: - selector: - matchLabels: - my-listener: listener-8080 -``` - -The above example shows a `Listener` configured to associate only with `Host`s that have a `my-listener: listener-8080` label. - -For migration purposes, it is possible to have a `Listener` associate with all of the `Host`s. This is not recommended for production environments, however, as it can resulting confusing behavior with large numbers of `Host`s, and it -can also result in larger Envoy configurations that slow reconfiguration. - -```yaml -hostBinding: - namespace: - from: ALL -``` - -but **this is not recommended in production**. Allowing every `Host` to associate -with every `Listener` can result in confusing behavior with large numbers of `Host`s, and it -can also result in larger Envoy configurations that slow reconfiguration. - -### 3.2. `Host` and `Mapping` are associated through `Host.mappingSelector` - - -In $productName$ 1.X, `Mapping`s were nearly always associated with every `Host`. Since this -tends to result in larger Envoy configurations that slow down reconfiguration, $productName$ 2.X -inverts this behavior: **`Host` and `Mapping` will not associate without explicit selection**. - -To have a `Mapping` associate with a `Host`, at least one of the following must hold: - -- Recommended: The `Host` must define a `mappingSelector` that matches a `label` on the `Mapping`. -- Alternately, the `Mapping` must define `hostname` that matches the `hostname` of the `Host`. - (Note that the `hostname` of both `Host` and `AmbasssadorMapping` is a DNS glob.) - -If the `Host` defines a `mappingSelector` and the `Mapping` also defines a `hostname`, both must match. - -As a migration aid: - -- A `Mapping` with a `hostname` of `"*"` will associate with any `Host` that -has no `mappingSelector`, and -- A `v3alpha1` `Mapping` will honor `host` if `hostname` is not present. - - - Learn more about Host
- Learn more about Mapping - - - - A Mapping that specifies host_regex: true is associated with  - all Hosts. This is generally far less desirable than using hostname - with a DNS glob. - - - - Support for host and host_regex will be removed before - v3alpha1 is promoted to v3. - - -## 4. Use `Host` to terminate TLS - - - Learn more about Host
- Learn more about TLSContext - - -In $productName$ 1.X, simply creating a `TLSContext` is sufficient to terminate TLS, but in -2.X you _must_ use a `Host`. The minimal setup to terminate TLS is now something like this: - -```yaml ---- -apiVersion: v1 -kind: Secret -metadata: - name: my-secret -type: kubernetes.io/tls -data: - tls.crt: base64-PEM - tls.key: base64-PEM ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: my-host -spec: - hostname: host.example.com - tlsSecret: my-secret -``` - -In the example above, TLS is terminated for `host.example.com`. A `TLSContext` is still right way to share data -about TLS configuration across `Host`s: set both `tlsSecret` and `tlsContext` in the `Host`. - -## 5. `Mapping` should use `hostname` if possible - - - Learn more about Mapping - - -The `getambassador.io/v3alpha1` `Mapping` introduces the new `hostname` element, which is always -a DNS glob. Using `hostname` instead of `host` is **strongly recommended** unless you absolutely -require regular expression matching: - -- if `host` is being used for an exact match, simply rename `host` to `hostname`. -- if `host` is being used for a regex that effects a prefix or suffix match, rename it - to `hostname` and rewrite the regex into a DNS glob, e.g. `host: .*\.example\.com` would become - `hostname: *.example.com`. - -Additionally, when `hostname` is used, the `Mapping` will be associated with a `Host` only -if `hostname` matches the hostname of the `Host`. If the `Host`'s `selector` is also set, -both the `selector` and the hostname must line up. - - - An 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. - - -## 6. `Mapping` added headers must not be simple strings - - - Learn more about Mapping - - -The `getambassador.io/v2` `Mapping` supported strings and dictionaries for `add_request_headers` and -`add_response_headers`, for example: - -```yaml -add_request_headers: - X-Add-String: bar - X-Add-Dict: - value: bar -``` - -In `getambassador.io/v2`, both `X-Add-String` and `X-Add-Dict` will be added with the value `bar`. - -The string form - shown with `X-Add-String` - is not supported in `getambassador.io/v3alpha1`. Use the -dictionary form instead (which works in both `getambassador.io/v2` and `getambassador.io/v3alpha1`). - -## 7. `Mapping` `headers` and `query_parameters` must not be `true` - - - Learn more about Mapping - - -`headers` and `query_parameters` in a `Mapping` control header matches and query-parameter matches. In -`getambassador.io/v2`, they support both strings and dictionaries, and each has a `_regex` variant. -For example: - - ```yaml - headers: - x-exact-match: foo - x-existence-match: true - headers_regex: - x-regex-match: "fo.*o" - ``` - -In this example, the `Mapping` requires the `x-exact-match` header to have the value `foo`, the -`x-regex-match` whose value starts with `fo` and ends with `o`. However, `x-existence-match` requires -simply that the `x-existence-match` header exists. - -In `getambassador.io/v3alpha1`, the `true` value for an existence match is not supported. Instead, -use `headers_regex` for the same header with value of `.*`. This is fully supported in 1.k) - -`query_parameters` and `query_parameters_regex` work exactly like `headers` and `headers_reex`. - -## 8. `Mapping` `labels` must be converted to new syntax - - - Learn more about Mapping - - -In `getambassador.io/v2`, the `labels` element in a `Mapping` supported several different types of -data. In `getambassador.io/v3alpha1`, all labels must have the same type, so labels must be converted -to the new syntax: - -| `getambassador.io/v2` | `getambassador.io/v3alpha1` | -| -------------------------------- | ----------------------------------------------------------- | -| `source_cluster` | `{ source_cluster: { key: source_cluster } }` | -| `destination_cluster` | `{ destination_cluster: { key: destination_cluster }` } | -| `remote_address` | `{ remote_address: { key: remote_address } }` | -| `{ my_key: { header: my_hdr } }` | `{ generic_key: { value: my_val } }` | -| `{ my_val }` | `{ generic_key: { value: my_val } }` | -| `{ my_key: { header: my_hdr } }` | `{ request_headers: { key: my_key, header_name: my_hdr } }` | - -You can check the [Rate Limiting Labels documentation](../../using/rate-limits#attaching-labels-to-requests) -for more examples. - -## 9. `tls` cannot be `true` in `AuthService`, `Mapping`, `RateLimitService`, and `TCPMapping` - - - Learn more about AuthService
- Learn more about Mapping
- Learn more about RateLimitService
- Learn more about TCPMapping - - -The `tls` element in `AuthService`, `Mapping`, `RateLimitService`, and `TCPMapping` controls TLS -origination. In `getambassador.io/v2`, it may be a string naming a `TLSContext` to use to determine -which client certificate is sent, or the boolean value `true` to request TLS origination with no -cluent certificate being sent. - -In `getambassador.io/v3alpha1`, only the string form is supported. To originate TLS with no client -certificate (the semantic of `tls: true`), omit the `tls` element and prefix the `service` with -`https://`. Note that `TCPMapping` in `getambassador.io/v2` does not support the `https://prefix`. - -## 10. Some `Module` settings have moved or changed - - - Learn more about Listener - - -A few settings have moved from the `Module` in 2.0. Make sure you review the following settings -and move them to their new locations if you are using them in a `Module`: - -- Configuration for the `PROXY` protocol is part of the `Listener` resource in $productName$ 2.0, -so the `use_proxy_protocol` element of the `ambassador` `Module` is no longer supported. - -- `xff_num_trusted_hops` has been removed from the `Module`, and its functionality has been moved -to the `l7Depth` setting in the `Listener` resource. - -- It is no longer possible to configure TLS using the `tls` element of the `Module`. Its -functionality is fully covered by the `TLSContext` resource. diff --git a/content/en/docs/3.2/topics/install/docker.md b/content/en/docs/3.2/topics/install/docker.md deleted file mode 100644 index e430a55c..00000000 --- a/content/en/docs/3.2/topics/install/docker.md +++ /dev/null @@ -1,73 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Run the demo with Docker - -In this Docker quickstart guide, we'll get $productName$ running locally -with a demo configuration. In the next section, we'll then walk through how to -deploy $productName$ in Kubernetes with a custom configuration. - -## 1. Running the demo configuration - -By default, $productName$ uses a demo configuration to show some of its basic features. Get it running with Docker, and expose $productName$ on port 8080: - -``` -docker run -it -p 8080:8080 --name=$productDeploymentName$ --rm docker.io/emissaryingress/emissary:$version$ --demo -``` - -## 2. $productName$'s diagnostics - -$productName$ provides live diagnostics viewable with a web browser. While this would normally not be exposed to the public network, the Docker demo publishes the diagnostics service at the following URL: - -`http://localhost:8080/ambassador/v0/diag/` - -You'll have to authenticate to view this page: use the username `admin`, -password `admin` (obviously this would be a poor choice in the real world!). -We'll talk more about authentication shortly. - -To access the Diagnostics page with authentication, use `curl http://localhost:8080/ambassador/v0/diag/ -u admin:admin` - -Some of the most important information - your $productName$ version, how recently $productName$'s configuration was updated, and how recently Envoy last reported status to $productName$ - is right at the top. The diagnostics overview can show you what it sees in your configuration map, and which Envoy objects were created based on your configuration. - -## 3. The Quote service - -Since $productName$ is a comprehensive, self-service edge stack, its primary purpose is to provide access and control to microservices for the teams that manage them. The demo is preconfigured with a mapping that connects the `/qotm/` resource to the "Quote" service -- a demo service that supplies quotations. You can try it out by opening - -`http://localhost:8080/qotm/` - -in your browser, or from the command line as - -``` -curl -L 'http://localhost:8080/qotm/?json=true' -``` - -This request will route to the `qotm` service at `demo.getambassador.io`, and return a random quote. - -You can see details of the mapping by clicking the blue `http://localhost:8080/qotm/` link at the very bottom of the `Ambassador Route Table` in the diagnostics overview. - -## 4. Authentication - -On the diagnostic overview, you can also see that $productName$ is configured to do authentication -- in the middle of the overview page, you'll see the `Ambassador Services In Use` section, and you can click the `tcp://127.0.0.1:5050` link for details on the `AuthService` configuration. This demo auth service is running inside the Docker container with $productName$ and the Quote service, and $productName$ uses it to mediate access to everything behind $productName$. - -You saw above that access to the diagnostic overview required you to authenticate as an administrator. Getting a random quote does not require authentication, but to get a specific quote, you'll have to authenticate as a demo user. To see this in action, open - -`http://localhost:8080/qotm/quote/5` - -in your browser. From the command line, you can see that: - -``` -curl -Lv 'http://localhost:8080/qotm/quote/5?json=true' -``` - -will return a 401, but - -``` -curl -Lv -u username:password 'http://localhost:8080/qotm/quote/5?json=true' -``` - -will succeed. (Note that that's literally "username" and "password" -- the demo auth service is deliberately not very secure!) - -Note that it's up to the auth service to decide what needs authentication -- teaming $productName$ with an authentication service can be as flexible or strict as you need it to be. - -## Next steps - -We've just walked through some of the core features of $productName$ in a local configuration. To see $productName$ in action on Kubernetes, check out the [Installation Guide](../). diff --git a/content/en/docs/3.2/topics/install/helm.md b/content/en/docs/3.2/topics/install/helm.md deleted file mode 100644 index 4c8a9836..00000000 --- a/content/en/docs/3.2/topics/install/helm.md +++ /dev/null @@ -1,102 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Install with Helm - - - - To migrate from $productName$ 1.X to $productName$ 2.X, see the - [$productName$ migration matrix](../migration-matrix/). This guide - **will not work** for that, due to changes to the configuration - resources used for $productName$ 2.X. - - - -[Helm](https://helm.sh) is a package manager for Kubernetes that automates the release and management of software on Kubernetes. $productName$ can be installed via a Helm chart with a few simple steps, depending on if you are deploying for the first time, upgrading $productName$ from an existing installation, or migrating from $productName$. - -## Before you begin - -The $productName$ Helm chart is hosted by Datawire and published at `https://app.getambassador.io`. - -Start by adding this repo to your helm client with the following command: - -``` -helm repo add datawire https://app.getambassador.io -helm repo update -``` - -## Install with Helm - -When you run the Helm chart, it installs $productName$. - -1. Install the $productName$ CRDs. - - Before installing $productName$ $version$ itself, you must configure your - Kubernetes cluster to support the `getambassador.io/v3alpha1` and `getambassador.io/v2` - configuration resources. This is required. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. Install the $productName$ Chart with the following command: - - ``` - helm install -n $productNamespace$ --create-namespace \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - -3. Next Steps - - $productName$ shold now be successfully installed and running, but in order to get started deploying Services and test routing to them you need to configure a few more resources. - - - [The `Listener` Resource](../../running/listener/) is required to configure which ports the $productName$ pods listen on so that they can begin responding to requests. - - [The `Mapping` Resouce](../../using/intro-mappings/) is used to configure routing requests to services in your cluster. - - [The `Host` Resource](../../running/host-crd/) configures TLS termination for enablin HTTPS communication. - - Explore how $productName$ [configures communication with clients](../../../howtos/configure-communications) - - - We strongly recommend following along with our Quickstart Guide to get started by creating a Listener, deploying a simple service to test with, and setting up a Mapping to route requests from $productName$ to the demo service. - - - - $productName$ $version$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - -For more advanced configuration and details about helm values, -[please see the helm chart.](https://artifacthub.io/packages/helm/datawire/emissary-ingress/) - -## Upgrading an existing installation - -See the [migration matrix](../migration-matrix) for instructions about upgrading -$productName$. diff --git a/content/en/docs/3.2/topics/install/index.less b/content/en/docs/3.2/topics/install/index.less deleted file mode 100644 index bc649e7c..00000000 --- a/content/en/docs/3.2/topics/install/index.less +++ /dev/null @@ -1,57 +0,0 @@ -@media (max-width: 769px) { - #index-installContainer { - flex-direction: column; - } - .index-dropdown { - width: auto; - } - .index-dropBtn { - width: 100%; - } -} - -.index-dropBtn { - background-color: #8e77ff; - color: white; - padding: 10px; - font-size: 16px; - border: none; - margin-top: -20px; -} - -.index-dropdown { - position: relative; - display: inline-block; -} - -.index-dropdownContent { - display: none; - position: absolute; - background-color: #f1f1f1; - width: 100%; - box-shadow: 0px 8px 16px 0px rgba(0, 0, 0, 0.2); - z-index: 1; -} - -.index-dropdownContent a { - color: black; - padding: 12px 16px; - text-decoration: none; - display: block; -} - -.index-dropdownContent a:hover { - background-color: #ddd; -} - -.index-dropdown:hover .index-dropdownContent { - display: block; -} - -.index-dropdown:hover .index-dropBtn { - background-color: #5f3eff; -} - -#index-installContainer { - display: flex; -} diff --git a/content/en/docs/3.2/topics/install/index.md b/content/en/docs/3.2/topics/install/index.md deleted file mode 100644 index 40fa95fd..00000000 --- a/content/en/docs/3.2/topics/install/index.md +++ /dev/null @@ -1,47 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; -import './index.less' - -# Installing $productName$ - -## 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/content/en/docs/3.2/topics/install/migrate-to-2-alternate.md b/content/en/docs/3.2/topics/install/migrate-to-2-alternate.md deleted file mode 100644 index 89bf4e5c..00000000 --- a/content/en/docs/3.2/topics/install/migrate-to-2-alternate.md +++ /dev/null @@ -1,40 +0,0 @@ ---- - title: Upgrade $productName$ with a separate cluster - 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$ 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/content/en/docs/3.2/topics/install/migrate-to-3-alternate.md b/content/en/docs/3.2/topics/install/migrate-to-3-alternate.md deleted file mode 100644 index d0b791a1..00000000 --- a/content/en/docs/3.2/topics/install/migrate-to-3-alternate.md +++ /dev/null @@ -1,36 +0,0 @@ -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/content/en/docs/3.2/topics/install/migration-matrix.md b/content/en/docs/3.2/topics/install/migration-matrix.md deleted file mode 100644 index 46bbf747..00000000 --- a/content/en/docs/3.2/topics/install/migration-matrix.md +++ /dev/null @@ -1,44 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrading $productName$ - - - Read the instructions below before making any changes to your cluster! - - -There are currently multiple paths for upgrading $productName$, depending on what version you're currently -running, what you want to be running, and whether you installed $productName$ using [Helm](../helm) or -YAML. - -(To check out if you installed $productName$ using Helm, run `helm list --all` and see if -$productName$ is listed. If so, you installed using Helm.) - - - Read the instructions below before making any changes to your cluster! - - -## If you are currently running $AESproductName$ - -See the [instructions on updating $AESproductName$](/docs/edge-stack/$aesDocsVersion$/topics/install/migration-matrix/). - -## If you installed $OSSproductName$ using Helm - -| If you're running. | You can upgrade to | -|----------------------------------|----------------------------------------------------------------------------------------------------------------------------| -| $OSSproductName$ $version$ | [$AESproductName$ $aesVersion$](/docs/edge-stack/$aesDocsVersion$/topics/install/upgrade/helm/emissary-3.2/edge-stack-3.2) | -| $OSSproductName$ $versionTwoX$ | [$OSSproductName$ $version$](../upgrade/helm/emissary-2.4/emissary-3.2) | -| $OSSproductName$ 2.3.X | [$OSSproductName$ $versionTwoX$](../upgrade/helm/emissary-2.3/emissary-2.4) | -| $OSSproductName$ 2.0.5 | [$OSSproductName$ $versionTwoX$](../upgrade/helm/emissary-2.0/emissary-2.4) | -| $OSSproductName$ $versionOneX$ | [$OSSproductName$ $versionTwoX$](../upgrade/helm/emissary-1.14/emissary-2.4) | -| $OSSproductName$ prior to $versionOneX$ | [$OSSproductName$ $versionOneX$](../../../../1.14/topics/install/upgrading) | - -## If you installed $OSSproductName$ manually by applying YAML - -| If you're running. | You can upgrade to | -|----------------------------------|----------------------------------------------------------------------------------------------------------------------------| -| $OSSproductName$ $version$ | [$AESproductName$ $aesVersion$](/docs/edge-stack/$aesDocsVersion$/topics/install/upgrade/yaml/emissary-3.2/edge-stack-3.2) | -| $OSSproductName$ $versionTwoX$ | [$OSSproductName$ $version$](../upgrade/yaml/emissary-2.4/emissary-3.2) | -| $OSSproductName$ 2.3.X | [$OSSproductName$ $versionTwoX$](../upgrade/yaml/emissary-2.3/emissary-2.4) | -| $OSSproductName$ 2.0.5 | [$OSSproductName$ $versionTwoX$](../upgrade/yaml/emissary-2.0/emissary-2.4) | -| $OSSproductName$ $versionOneX$ | [$OSSproductName$ $versionTwoX$](../upgrade/yaml/emissary-1.14/emissary-2.4) | -| $OSSproductName$ prior to $versionOneX$ | [$OSSproductName$ $versionOneX$](../../../../1.14/topics/install/upgrading) | diff --git a/content/en/docs/3.2/topics/install/upgrade/helm/emissary-1.14/emissary-2.4.md b/content/en/docs/3.2/topics/install/upgrade/helm/emissary-1.14/emissary-2.4.md deleted file mode 100644 index b4d696b0..00000000 --- a/content/en/docs/3.2/topics/install/upgrade/helm/emissary-1.14/emissary-2.4.md +++ /dev/null @@ -1,312 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 1.14.X (Helm) - - - This guide covers migrating from $productName$ 1.14.X to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -We're pleased to introduce $productName$ $versionTwoX$! The 2.X family introduces a number of -changes to allow $productName$ to more gracefully handle larger installations (including -multitenant or multiorganizational installations), reduce memory footprint, and improve -performance. In keeping with [SemVer](https://semver.org), $productName$ 2.X introduces -some changes that aren't backward-compatible with 1.X. These changes are detailed in -[Major Changes in $productName$ 2.X](../../../../../../about/changes-2.x/). - -## Migration Overview - - - Read the migration instructions below before making any changes to your - cluster! - - -The recommended strategy for migration is to run $productName$ 1.14 and $productName$ -$versionTwoX$ side-by-side in the same cluster. This gives $productName$ $versionTwoX$ -and $productName$ 1.14 access to all the same configuration resources, with some -important caveats: - -1. **$productName$ 1.14 will not see any `getambassador.io/v3alpha1` resources.** - - This is intentional; it provides a way to apply configuration only to - $productName$ $versionTwoX$, while not interfering with the operation of your - $productName$ 1.14 installation. - -2. **If needed, you can use labels to further isolate configurations.** - - If you need to prevent your $productName$ $versionTwoX$ installation from - seeing a particular bit of $productName$ 1.14 configuration, you can apply - a Kubernetes label to the configuration resources that should be seen by - your $productName$ $versionTwoX$ installation, then set its - `AMBASSADOR_LABEL_SELECTOR` environment variable to restrict its 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$ $versionTwoX$, then set - `AMBASSADOR_LABEL_SELECTOR=version-two=true` in its Deployment. - -3. **Be careful about label selectors on Kubernetes Services!** - - If you have services in $productName$ 1.14 that use selectors that will match - Pods from $productName$ $versionTwoX$, traffic will be erroneously split between - $productName$ 1.14 and $productName$ $versionTwoX$. The labels used by $productName$ - $versionTwoX$ include: - - ```yaml - app.kubernetes.io/name: emissary-ingress - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/part-of: emissary-ingress - app.kubernetes.io/managed-by: getambassador.io - product: aes - profile: main - ``` - -4. **Be careful to only have one $productName$ Agent running at a time.** - - The $productName$ Agent is responsible for communications between - $productName$ and Ambassador Cloud. If multiple versions of the Agent are - running simultaneously, Ambassador Cloud could see conflicting information - about your cluster. - - The best way to avoid multiple agents when installing with Helm is to use - `--set agent.enabled=false` to tell Helm not to install a new Agent with - $productName$ $versionTwoX$. Once testing is done, you can switch Agents safely. - -You can also migrate by [installing $productName$ $versionTwoX$ in a separate cluster](../../../../migrate-to-2-alternate). -This permits absolute certainty that your $productName$ 1.14 configuration will not be -affected by changes meant for $productName$ $versionTwoX$, and it eliminates concerns about -ACME, but it is more effort. - -## Side-by-Side Migration Steps - -Migration is a seven-step process: - -1. **Make sure that older configuration resources are not present.** - - $productName$ 2.X does not support `getambassador.io/v0` or `getambassador.io/v1` - resources, and Kubernetes will not permit removing support for CRD versions that are - still in use for stored resources. To verify that no resources older than - `getambassador.io/v2` are active, run - - ``` - kubectl get crds -o 'go-template={{range .items}}{{.metadata.name}}={{.status.storedVersions}}{{"\n"}}{{end}}' | fgrep getambassador.io - ``` - - If `v1` is present in the output, **do not begin migration.** The old resources must be - converted to `getambassador.io/v2` and the `storedVersion` information in the cluster - must be updated. If necessary, contact Ambassador Labs on [Slack](http://a8r.io/slack) - for more information. - -2. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you must configure your - Kubernetes cluster to support its new `getambassador.io/v3alpha1` configuration - resources. Note that `getambassador.io/v2` resources are still supported, but **you - must install support for `getambassador.io/v3alpha1`** to run $productName$ $versionTwoX$, - even if you intend to continue using only `getambassador.io/v2` resources for some - time. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -3. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, you need to install $productName$ $versionTwoX$ itself - **in the same namespace as your existing $productName$ 1.14 installation**. It's important - to use the same namespace so that the two installations can see the same secrets, etc. - - Start by making sure that your `emissary` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Typically, $productName$ 1.14 was installed in the `ambassador` namespace. If you installed - $productName$ 1.14 in a different namespace, change the namespace in the commands below. - - - If you do not need to set `AMBASSADOR_LABEL_SELECTOR`: - - ```bash - helm install -n ambassador \ - --set agent.enabled=false \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - - - If you do need to set `AMBASSADOR_LABEL_SELECTOR`, use `--set`, for example: - - ```bash - helm install -n ambassador \ - --set agent.enabled=false \ - --set env.AMBASSADOR_LABEL_SELECTOR="version-two=true" \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 2.X. - Do not use the ambassador Helm chart. - - - - $productName$ $versionTwoX$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - -4. **Install `Listener`s and `Host`s as needed.** - - An important difference between $productName$ 1.14 and $productName$ $versionTwoX$ is the - new **mandatory** `Listener` CRD. Also, when running both installations side by side, - you will need to make sure that a `Host` is present for the new $productName$ $versionTwoX$ - Service. For example: - - ```bash - kubectl apply -f - < - Kubernetes will not allow you to have a 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.
-
- If you find that your $productName$ $versionTwoX$ installation and your $productName$ 1.14 - installation absolutely must have resources that are only seen by one version or the - other way, see overview section 2, "If needed, you can use labels to further isolate configurations". - - - **If you find that you need to roll back**, just reinstall your 1.14 CRDs and delete your - installation of $productName$ $versionTwoX$. - -6. **When ready, switch over to $productName$ $versionTwoX$.** - - You can run $productName$ 1.14 and $productName$ $versionTwoX$ side-by-side as long as you care - to. However, taking full advantage of $productName$ 2.X's capabilities **requires** - [updating your configuration to use `getambassador.io/v3alpha1` configuration resources](../../../../convert-to-v3alpha1), - since some useful features in $productName$ $versionTwoX$ are only available using - `getambassador.io/v3alpha1` resources. - - When you're ready to have $productName$ $versionTwoX$ handle traffic on its own, switch - your original $productName$ 1.14 Service to point to $productName$ $versionTwoX$. Use - `kubectl edit service ambassador` and change the `selectors` to: - - ``` - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/name: emissary-ingress - profile: main - ``` - - Repeat using `kubectl edit service ambassador-admin` for the `ambassador-admin` - Service. - -7. **Finally, install the $productName$ $versionTwoX$ Ambassador Agent.** - - First, scale the 1.14 agent to 0: - - ``` - kubectl scale -n ambassador deployment/ambassador-agent --replicas=0 - ``` - - Once that's done, install the new Agent. **Note that if you needed to set - `AMBASSADOR_LABEL_SELECTOR`, you must add that to this `helm upgrade` command.** - - ```bash - helm upgrade -n ambassador \ - --set agent.enabled=true \ - $productHelmName$ datawire/$productHelmName$ \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - -Congratulations! At this point, $productName$ $versionTwoX$ is fully running and it's safe to remove the `ambassador` and `ambassador-agent` Deployments: - -``` -kubectl delete deployment/ambassador deployment/ambassador-agent -``` - -Once $productName$ 1.14 is no longer running, you may [convert](../../../../convert-to-v3alpha1) -any remaining `getambassador.io/v2` resources to `getambassador.io/v3alpha1`. -You may also want to redirect DNS to the `edge-stack` Service and remove the -`ambassador` Service. diff --git a/content/en/docs/3.2/topics/install/upgrade/helm/emissary-2.0/emissary-2.4.md b/content/en/docs/3.2/topics/install/upgrade/helm/emissary-2.0/emissary-2.4.md deleted file mode 100644 index ecb4e8d4..00000000 --- a/content/en/docs/3.2/topics/install/upgrade/helm/emissary-2.0/emissary-2.4.md +++ /dev/null @@ -1,75 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.0.5 (Helm) - - - This guide covers migrating from $productName$ 2.0.5 to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster; Helm will not do this for you. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, use Helm to install $productName$ $versionTwoX$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 2.X. - Do not use the ambassador Helm chart. - diff --git a/content/en/docs/3.2/topics/install/upgrade/helm/emissary-2.3/emissary-2.4.md b/content/en/docs/3.2/topics/install/upgrade/helm/emissary-2.3/emissary-2.4.md deleted file mode 100644 index 84b02216..00000000 --- a/content/en/docs/3.2/topics/install/upgrade/helm/emissary-2.3/emissary-2.4.md +++ /dev/null @@ -1,75 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.3.X (Helm) - - - This guide covers migrating from $productName$ 2.3 to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster; Helm will not do this for you. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, use Helm to install $productName$ $versionTwoX$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 2.X. - Do not use the ambassador Helm chart. - diff --git a/content/en/docs/3.2/topics/install/upgrade/helm/emissary-2.4/emissary-3.2.md b/content/en/docs/3.2/topics/install/upgrade/helm/emissary-2.4/emissary-3.2.md deleted file mode 100644 index 17264c79..00000000 --- a/content/en/docs/3.2/topics/install/upgrade/helm/emissary-2.4/emissary-3.2.md +++ /dev/null @@ -1,141 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.4.Z (Helm) - - - This guide covers migrating from $productName$ 2.4.Z to $productName$ $version$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - - - Make sure that you have updated any 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$. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -$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. - -### Resources to check before migrating to $version$. - -$productName$ 3.X has been upgraded from Envoy 1.17.X to Envoy 1.22 which removed support for the Envoy V2 Transport Protocol. This means all `AuthService`, `RatelimitService`, and `LogServices` must be updated to use the V3 Protocol. Additionally support for some of the runtime bootstrap flags has been removed. - -You can refer to the [Major changes in $productName$ 3.x](../../../../../../about/changes-3.y/) guide for an overview of the changes. - -1. $productName$ 3.2 fixed a bug with `Host.spec.selector\mappingSelector` and `Listener.spec.selector` not being properly enforced. - In previous versions, if only a single label from the selector was present on the resource then they would be associated. Additionally, when associating `Hosts` with `Mappings`, if the `Mapping` configured a `hostname` that matched the `hostname` of the `Host` then they would be associated regardless of the configuration of the `selector\mappingSelector` on the `Host`. - - Before upgrading, review your Ambassador resources, and if you make use of the selectors, ensure that every other resource you want it to be associated with contains all the required labels. - - The environment variable `DISABLE_STRICT_LABEL_SELECTORS` can be set to `"true"` on the $productName$ deployment to revert to the - old incorrect behavior to help prevent any configuration issues after upgrading in the event that not all manifests making use of the selectors have been corrected yet. - - For more information on `DISABLE_STRICT_LABEL_SELECTORS` see the [Environment Variables page](../../../../../running/environment). - -2. Check Transport Protocol usage on all resources before migrating. - - The `AuthService`, `RatelimitService`, and `LogServices` 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. - - `protocol_version` should be updated to `v3` for all of the above resources while still running $productName$ $versionTwoX$. As of version `2.3.z`+, support for `protocol_version` `v2` and `v3` is supported in order to allow migration from `protocol_version` `v2` to `v3` before upgrading to $productName$ $version$ where support for `v2` is removed. - - Upgrading any application code for your own implementations of these services is very straightforward. - - The following imports simply need to be updated to switch from Envoy's Transport Protocol `v2` to `v3`, and then the configuration for these resources can be updated to add the `protocl_version: "v3"` when the updated service is deployed. - - `v2` Imports: - ``` - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" - ``` - - `v3` Imports: - ``` - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" - ``` - -3. Check removed runtime changes - - ``` - # 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, - - # Developers 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, - ``` - -4. **Install new CRDs.** - - After reviewing the changes in 3.x and confirming that you are ready to upgrade, the process is the same as upgrading minor versions - in previous version of $productName$ and does not require the complex migration steps that the migration from 1.x tto 2.x required. - - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -5. **Install $productName$ $version$.** - - After installing the new CRDs, use Helm to install $productName$ $version$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 3.Y. - diff --git a/content/en/docs/3.2/topics/install/upgrade/yaml/emissary-1.14/emissary-2.4.md b/content/en/docs/3.2/topics/install/upgrade/yaml/emissary-1.14/emissary-2.4.md deleted file mode 100644 index 8acf3a28..00000000 --- a/content/en/docs/3.2/topics/install/upgrade/yaml/emissary-1.14/emissary-2.4.md +++ /dev/null @@ -1,282 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 1.14.X (YAML) - - - This guide covers migrating from $productName$ 1.14.X to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -We're pleased to introduce $productName$ $versionTwoX$! The 2.X family introduces a number of -changes to allow $productName$ to more gracefully handle larger installations (including -multitenant or multiorganizational installations), reduce memory footprint, and improve -performance. In keeping with [SemVer](https://semver.org), $productName$ 2.X introduces -some changes that aren't backward-compatible with 1.X. These changes are detailed in -[Major Changes in $productName$ 2.X](../../../../../../about/changes-2.x/). - -## Migration Overview - - - Read the migration instructions below before making any changes to your - cluster! - - -The recommended strategy for migration is to run $productName$ 1.14 and $productName$ -$versionTwoX$ side-by-side in the same cluster. This gives $productName$ $versionTwoX$ -and $productName$ 1.14 access to all the same configuration resources, with some -important caveats: - -1. **$productName$ 1.14 will not see any `getambassador.io/v3alpha1` resources.** - - This is intentional; it provides a way to apply configuration only to - $productName$ $versionTwoX$, while not interfering with the operation of your - $productName$ 1.14 installation. - -2. **If needed, you can use labels to further isolate configurations.** - - If you need to prevent your $productName$ $versionTwoX$ installation from - seeing a particular bit of $productName$ 1.14 configuration, you can apply - a Kubernetes label to the configuration resources that should be seen by - your $productName$ $versionTwoX$ installation, then set its - `AMBASSADOR_LABEL_SELECTOR` environment variable to restrict its 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$ $versionTwoX$, then set - `AMBASSADOR_LABEL_SELECTOR=version-two=true` in its Deployment. - -3. **Be careful about label selectors on Kubernetes Services!** - - If you have services in $productName$ 1.14 that use selectors that will match - Pods from $productName$ $versionTwoX$, traffic will be erroneously split between - $productName$ 1.14 and $productName$ $versionTwoX$. The labels used by $productName$ - $versionTwoX$ include: - - ```yaml - app.kubernetes.io/name: emissary-ingress - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/part-of: emissary-ingress - app.kubernetes.io/managed-by: getambassador.io - product: aes - profile: main - ``` - -4. **Be careful to only have one $productName$ Agent running at a time.** - - The $productName$ Agent is responsible for communications between - $productName$ and Ambassador Cloud. If multiple versions of the Agent are - running simultaneously, Ambassador Cloud could see conflicting information - about your cluster. - - The migration YAML used below to install $productName$ $versionTwoX$ will not - install a duplicate agent. If you are building your own YAML, make sure not - to include a duplicate agent. - -You can also migrate by [installing $productName$ $versionTwoX$ in a separate cluster](../../../../migrate-to-2-alternate). -This permits absolute certainty that your $productName$ 1.14 configuration will not be -affected by changes meant for $productName$ $versionTwoX$, and it eliminates concerns about -ACME, but it is more effort. - -## Side-by-Side Migration Steps - -Migration is a seven-step process: - -1. **Make sure that older configuration resources are not present.** - - $productName$ 2.X does not support `getambassador.io/v0` or `getambassador.io/v1` - resources, and Kubernetes will not permit removing support for CRD versions that are - still in use for stored resources. To verify that no resources older than - `getambassador.io/v2` are active, run - - ``` - kubectl get crds -o 'go-template={{range .items}}{{.metadata.name}}={{.status.storedVersions}}{{"\n"}}{{end}}' | fgrep getambassador.io - ``` - - If `v1` is present in the output, **do not begin migration.** The old resources must be - converted to `getambassador.io/v2` and the `storedVersion` information in the cluster - must be updated. If necessary, contact Ambassador Labs on [Slack](http://a8r.io/slack) - for more information. - -2. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you must configure your - Kubernetes cluster to support its new `getambassador.io/v3alpha1` configuration - resources. Note that `getambassador.io/v2` resources are still supported, but **you - must install support for `getambassador.io/v3alpha1`** to run $productName$ $versionTwoX$, - even if you intend to continue using only `getambassador.io/v2` resources for some - time. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -3. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, you need to install $productName$ $versionTwoX$ itself - **in the same namespace as your existing $productName$ 1.14 installation**. It's important - to use the same namespace so that the two installations can see the same secrets, etc. - - We publish two manifests for different namespaces. Use only the one that - matches the namespace into which you installed $productName$ 1.14: - - - [`emissary-emissaryns.yaml`] for the `emissary` namespace; or - - [`emissary-defaultns.yaml`] for the `default` namespace. - - If you installed $productName$ 1.14 into some other namespace, you'll need to - download one of the files and edit it to match your namespace. - - [`emissary-emissaryns.yaml`]: https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-emissaryns.yaml - [`emissary-defaultns.yaml`]: https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-defaultns.yaml - - **If you need to set `AMBASSADOR_LABEL_SELECTOR`**, you'll need to download - your chosen file and and edit it to do so. - - Assuming that you're using the `default` namespace: - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-defaultns.yaml && \ - kubectl rollout status -n default deployment/edge-stack -w - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - -4. **Install `Listener`s and `Host`s as needed.** - - An important difference between $productName$ 1.14 and $productName$ $versionTwoX$ is the - new **mandatory** `Listener` CRD. Also, when running both installations side by side, - you will need to make sure that a `Host` is present for the new $productName$ $versionTwoX$ - Service. For example: - - ```bash - kubectl apply -f - < - Kubernetes will not allow you to have a 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.
-
- If you find that your $productName$ $versionTwoX$ installation and your $productName$ 1.14 - installation absolutely must have resources that are only seen by one version or the - other way, see overview section 2, "If needed, you can use labels to further isolate configurations". - - - **If you find that you need to roll back**, just reinstall your 1.14 CRDs and delete your - installation of $productName$ $versionTwoX$. - -6. **When ready, switch over to $productName$ $versionTwoX$.** - - You can run $productName$ 1.14 and $productName$ $versionTwoX$ side-by-side as long as you care - to. However, taking full advantage of $productName$ 2.X's capabilities **requires** - [updating your configuration to use `getambassador.io/v3alpha1` configuration resources](../../../../convert-to-v3alpha1), - since some useful features in $productName$ $versionTwoX$ are only available using - `getambassador.io/v3alpha1` resources. - - When you're ready to have $productName$ $versionTwoX$ handle traffic on its own, switch - your original $productName$ 1.14 Service to point to $productName$ $versionTwoX$. Use - `kubectl edit service ambassador` and change the `selectors` to: - - ``` - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/name: emissary-ingress - profile: main - ``` - - Repeat using `kubectl edit service ambassador-admin` for the `ambassador-admin` - Service. - - -Congratulations! At this point, $productName$ $versionTwoX$ is fully running and it's safe to remove the `ambassador` and `ambassador-agent` Deployments: - -``` -kubectl delete deployment/ambassador deployment/ambassador-agent -``` - -Once $productName$ 1.14 is no longer running, you may [convert](../../../../convert-to-v3alpha1) -any remaining `getambassador.io/v2` resources to `getambassador.io/v3alpha1`. -You may also want to redirect DNS to the `edge-stack` Service and remove the -`ambassador` Service. diff --git a/content/en/docs/3.2/topics/install/upgrade/yaml/emissary-2.0/emissary-2.4.md b/content/en/docs/3.2/topics/install/upgrade/yaml/emissary-2.0/emissary-2.4.md deleted file mode 100644 index 44bc5b5d..00000000 --- a/content/en/docs/3.2/topics/install/upgrade/yaml/emissary-2.0/emissary-2.4.md +++ /dev/null @@ -1,65 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.0.5 (YAML) - - - This guide covers migrating from $productName$ 2.0.5 to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, upgrade $productName$ $versionTwoX$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/3.2/topics/install/upgrade/yaml/emissary-2.3/emissary-2.4.md b/content/en/docs/3.2/topics/install/upgrade/yaml/emissary-2.3/emissary-2.4.md deleted file mode 100644 index a8c24a83..00000000 --- a/content/en/docs/3.2/topics/install/upgrade/yaml/emissary-2.3/emissary-2.4.md +++ /dev/null @@ -1,65 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.3.X (YAML) - - - This guide covers migrating from $productName$ 2.2.0 or 2.2.2 to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, upgrade $productName$ $versionTwoX$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/3.2/topics/install/upgrade/yaml/emissary-2.4/emissary-3.2.md b/content/en/docs/3.2/topics/install/upgrade/yaml/emissary-2.4/emissary-3.2.md deleted file mode 100644 index f9eb9884..00000000 --- a/content/en/docs/3.2/topics/install/upgrade/yaml/emissary-2.4/emissary-3.2.md +++ /dev/null @@ -1,132 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.4.Z (YAML) - - - This guide covers migrating from $productName$ 2.4.Z to $productName$ $version$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - - - Make sure that you have updated any 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$. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading -between versions is straightforward. - -$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. - -### Resources to check before migrating to $version$. - -$productName$ 3.X has been upgraded from Envoy 1.17.X to Envoy 1.22 which removed support for the Envoy V2 Transport Protocol. This means all `AuthService`, `RatelimitService`, and `LogServices` must be updated to use the V3 Protocol. Additionally support for some of the runtime bootstrap flags has been removed. - -You can refer to the [Major changes in $productName$ 3.x](../../../../../../about/changes-3.y/) guide for an overview of the changes. - -1. $productName$ 3.2 fixed a bug with `Host.spec.selector\mappingSelector` and `Listener.spec.selector` not being properly enforced. - In previous versions, if only a single label from the selector was present on the resource then they would be associated. Additionally, when associating `Hosts` with `Mappings`, if the `Mapping` configured a `hostname` that matched the `hostname` of the `Host` then they would be associated regardless of the configuration of the `selector\mappingSelector` on the `Host`. - - Before upgrading, review your Ambassador resources, and if you make use of the selectors, ensure that every other resource you want it to be associated with contains all the required labels. - - The environment variable `DISABLE_STRICT_LABEL_SELECTORS` can be set to `"true"` on the $productName$ deployment to revert to the - old incorrect behavior to help prevent any configuration issues after upgrading in the event that not all manifests making use of the selectors have been corrected yet. - - For more information on `DISABLE_STRICT_LABEL_SELECTORS` see the [Environment Variables page](../../../../../running/environment). - -2. Check Transport Protocol usage on all resources before migrating. - - The `AuthService`, `RatelimitService`, and `LogServices` 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. - - `protocol_version` should be updated to `v3` for all of the above resources while still running $productName$ $versionTwoX$. As of version `2.3.z`+, support for `protocol_version` `v2` and `v3` is supported in order to allow migration from `protocol_version` `v2` to `v3` before upgrading to $productName$ $version$ where support for `v2` is removed. - - Upgrading any application code for your own implementations of these services is very straightforward. - - The following imports simply need to be updated to switch from Envoy's Transport Protocol `v2` to `v3`, and then the configuration for these resources can be updated to add the `protocl_version: "v3"` when the updated service is deployed. - - `v2` Imports: - ``` - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" - ``` - - `v3` Imports: - ``` - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" - ``` - -3. Check removed runtime changes - - ``` - # 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, - - # Developers 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, - ``` - -4. **Install new CRDs.** - - After reviewing the changes in 3.x and confirming that you are ready to upgrade, the process is the same as upgrading minor versions - in previous version of $productName$ and does not require the complex migration steps that the migration from 1.x tto 2.x required. - - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -5. **Install $productName$ $version$.** - - After installing the new CRDs, upgrade $productName$ $version$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/3.2/topics/install/yaml-install.md b/content/en/docs/3.2/topics/install/yaml-install.md deleted file mode 100644 index b28e6265..00000000 --- a/content/en/docs/3.2/topics/install/yaml-install.md +++ /dev/null @@ -1,87 +0,0 @@ ---- - description: In this guide, we'll walk through the process of deploying $productName$ in Kubernetes for ingress routing. ---- - -import Alert from '@material-ui/lab/Alert'; - -# Install manually - - - - To migrate from $productName$ 1.X to $productName$ 2.X, see the - [$productName$ migration matrix](../migration-matrix/). This guide - **will not work** for that, due to changes to the configuration - resources used for $productName$ 2.X. - - - -In this guide, we'll walk you through installing $productName$ in your Kubernetes cluster. - -The manual install process does not allow for as much control over configuration -as the [Helm install method](../helm), so if you need more control over your $productName$ -installation, it is recommended that you use helm. - -## Before you begin - -$productName$ is designed to run in Kubernetes for production. The most essential requirements are: - -* Kubernetes 1.11 or later -* The `kubectl` command-line tool - -## Install with YAML - -$productName$ is typically deployed to Kubernetes from the command line. If you don't have Kubernetes, you should use our [Docker](../docker) image to deploy $productName$ locally. - -1. In your terminal, run the following command: - - ``` - kubectl create namespace $productNamespace$ || true - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml && \ - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-emissaryns.yaml && \ - kubectl -n $productNamespace$ wait --for condition=available --timeout=90s deploy $productDeploymentName$ - ``` - - - $productName$ $version$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. Determine the IP address or hostname of your cluster by running the following command: - - ``` - kubectl get -n $productNamespace$ service $productDeploymentName$ -o "go-template={{range .status.loadBalancer.ingress}}{{or .ip .hostname}}{{end}}" - ``` - - Your load balancer may take several minutes to provision your IP address. Repeat the provided command until you get an IP address. - -3. Next Steps - - $productName$ shold now be successfully installed and running, but in order to get started deploying Services and test routing to them you need to configure a few more resources. - - - [The `Listener` Resource](../../running/listener/) is required to configure which ports the $productName$ pods listen on so that they can begin responding to requests. - - [The `Mapping` Resouce](../../using/intro-mappings/) is used to configure routing requests to services in your cluster. - - [The `Host` Resource](../../running/host-crd/) configures TLS termination for enablin HTTPS communication. - - Explore how $productName$ [configures communication with clients](../../../howtos/configure-communications) - - - We strongly recommend following along with our Quickstart Guide to get started by creating a Listener, deploying a simple service to test with, and setting up a Mapping to route requests from $productName$ to the demo service. - - -## Upgrading an existing installation - -See the [migration matrix](../migration-matrix) for instructions about upgrading -$productName$. diff --git a/content/en/docs/3.2/topics/running/ambassador-deployment.md b/content/en/docs/3.2/topics/running/ambassador-deployment.md deleted file mode 100644 index d870f32c..00000000 --- a/content/en/docs/3.2/topics/running/ambassador-deployment.md +++ /dev/null @@ -1,21 +0,0 @@ -# Deployment architecture - -$productName$ can be deployed in a variety of configurations. The specific configuration depends on your data center. - -## Public cloud - -If you're using a public cloud provider such as Amazon, Azure, or Google, $productName$ can be deployed directly to a Kubernetes cluster running in the data center. Traffic is routed to $productName$ via a cloud-managed load balancer such as an Amazon Elastic Load Balancer or Google Cloud Load Balancer. Typically, this load balancer is transparently managed by Kubernetes in the form of the `LoadBalancer` service type. $productName$ then routes traffic to your services running in Kubernetes. - -## On-Premise data center - -In an on-premise data center, $productName$ is deployed on the Kubernetes cluster. Instead of exposing it via the `LoadBalancer` service type, $productName$ is exposed as a `NodePort`. Traffic is sent to a specific port on any of the nodes in the cluster, which route the traffic to $productName$, which then routes the traffic to your services running in Kubernetes. You'll also need to deploy a separate load balancer to route traffic from your core routers to $productName$. [MetalLB](https://metallb.universe.tf/) is an open-source external load balancer for Kubernetes designed for this problem. Other options are traditional TCP load balancers such as F5 or Citrix Netscaler. - -## Hybrid data center - -Many data centers include services that are running outside of Kubernetes on virtual machines. For $productName$ to route to services both inside and outside of Kubernetes, it needs the real-time network location of all services. This problem is known as "[service discovery](https://www.datawire.io/guide/traffic/service-discovery-microservices/)" and $productName$ supports using [Consul](https://www.consul.io). Services in your data center register themselves with Consul, and $productName$ uses Consul-supplied data to dynamically route requests to available services. - -## Hybrid on-premise data center - -The diagram below details a common network architecture for a hybrid on-premise data center. Traffic flows from core routers to MetalLB, which routes to $productName$ running in Kubernetes. $productName$ routes traffic to individual services running on both Kubernetes and VMs. Consul tracks the real-time network location of the services, which $productName$ uses to route to the given services. - -![Architecture](../../images/consul-ambassador.png) diff --git a/content/en/docs/3.2/topics/running/ambassador-with-aws.md b/content/en/docs/3.2/topics/running/ambassador-with-aws.md deleted file mode 100644 index b321543a..00000000 --- a/content/en/docs/3.2/topics/running/ambassador-with-aws.md +++ /dev/null @@ -1,364 +0,0 @@ -# $productName$ with AWS - -$productName$ is a platform agnostic Kubernetes API gateway. It will run in any distribution of Kubernetes whether it is managed by a cloud provider or on homegrown bare-metal servers. - -This document serves as a reference for different configuration options available when running Kubernetes in AWS. See [Installing $productName$](../../install) for the various installation methods available. - -## Recommended configuration - -There are lot of configuration options available to you when running $productName$ in AWS. While you should read this entire document to understand what is best for you, the following is the recommended configuration when running $productName$ in AWS: - -It is recommended to terminate TLS at $productName$ so you can take advantage of all the TLS configuration options available in $productName$ including setting the allowed TLS versions, setting `alpn_protocol` options, enforcing HTTP -> HTTPS redirection, and [automatic certificate management](../host-crd) in the $productName$. - -When terminating TLS at $productName$, you should deploy a L4 [Network Load Balancer (NLB)](#network-load-balancer-nlb) with the proxy protocol enabled to get the best performance out of your load balancer while still preserving the client IP address. - -The following `Service` should be configured to deploy an NLB with cross zone load balancing enabled (see [NLB notes](#network-load-balancer-nlb) for caveat on the cross-zone-load-balancing annotation). You will need to configure the proxy protocol in the NLB manually in the AWS Console. - -```yaml -apiVersion: v1 -kind: Service -metadata: - name: ambassador - namespace: ambassador - annotations: - service.beta.kubernetes.io/aws-load-balancer-type: "nlb" - service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: "true" -spec: - type: LoadBalancer - ports: - - name: HTTP - port: 80 - targetPort: 8080 - - name: HTTPS - port: 443 - targetPort: 8443 - selector: - service: ambassador -``` - - After deploying the `Service` above and manually enabling the proxy protocol you will need to deploy the following [Ambassador `Module`](../ambassador) to tell $productName$ to use the proxy protocol and then restart $productName$ for the configuration to take effect. - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - use_proxy_proto: true - ``` - - $productName$ will now expect traffic from the load balancer to be wrapped with the proxy protocol so it can read the client IP address. - -## AWS load balancer notes - -AWS provides three types of load balancers: - -### "Classic" Elastic Load Balancer (ELB) - -The ELB is the first generation AWS Elastic Load Balancer. It is the default type of load balancer ensured by a `type: LoadBalancer` `Service` and routes directly to individual EC2 instances. It can be configured to run at layer 4 or layer 7 of the OSI model. See [What is a Classic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/introduction.html) for more details. - -* Ensured by default for a `type: LoadBalancer` `Service` -* Layer 4: TCP, TCP/SSL - * Protocol support - * HTTP(S) - * Websockets - * HTTP/2 - * Connection based load balancing - * Cannot modify the request -* Layer 7: HTTP, HTTPS - * Protocol support - * HTTP(S) - * Request based load balancing - * Can modify the request (append to `X-Forwarded-*` headers) -* Can perform TLS termination - -**Notes:** -- While it has been superseded by the `Network Load Balancer` and `Application Load Balancer` the ELB offers the simplest way of provisioning an L4 or L7 load balancer in Kubernetes. -- All of the [load balancer annotations](#load-balancer-annotations) are respected by the ELB. -- If using the ELB for TLS termination, it is recommended to run in L7 mode so it can modify `X-Forwarded-Proto` correctly. - -### Network Load Balancer (NLB) - -The NLB is a second generation AWS Elastic Load Balancer. It can be ensure by a `type: LoadBalancer` `Service` using an annotation. It can only run at layer 4 of the OSI model and load balances based on connection allowing it to handle millions of requests per second. See [What is a Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/introduction.html) for more details. - -* Can be ensured by a `type: LoadBalancer` `Service` -* Layer 4: TCP, TCP/SSL - * Protocol support - * HTTP(S) - * Websockets - * HTTP/2 - * Connection based load balacing - * Cannot modify the request -* Can perform TLS termination - -**Notes:** -- The NLB is the most efficient load balancer capable of handling millions of requests per second. It is recommended for streaming connections since it will maintain the connection stream between the client and $productName$. -- Most of the [load balancer annotations](#load-balancer-annotations) are respected by the NLB. You will need to manually configure the proxy protocol and take an extra step to enable cross zone load balancing. -- Since it operates at L4 and cannot modify the request, you will need to tell $productName$ if it is terminating TLS or not (see [TLS termination](#tls-termination) notes below). - -### Application Load Balancer (ALB) - -The ALB is a second generation AWS Elastic Load Balancer. It cannot be ensured by a `type: LoadBalancer` `Service` and must be deployed and configured manually. It can only run at layer 7 of the OSI model and load balances based on request information allowing it to perform fine-grained routing to applications. See [What is a Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/introduction.html) for more details. - -* Cannot be configured by a `type: LoadBalancer` `Service` -* Layer 7: HTTP, HTTPS - * Protocol support - * HTTP(S) - * Request based load balancing - * Can modify the request (append to `X-Forwarded-*` headers) -* Can perform TLS termination - -**Notes:** - -- The ALB can perform routing based on the path, headers, host, etc.. Since $productName$ performs this kind of routing in your cluster, unless you are using the same load balancer to route to services outside of Kubernetes, the overhead of provisioning an ALB is often not worth the benefits. -- If you would like to use an ALB, you will need to expose $productName$ with a `type: NodePort` service and manually configure the ALB to forward to the correct ports. -- None of the [load balancer annotations](#load-balancer-annotations) are respected by the ALB. You will need to manually configure all options. -- The ALB will properly set the `X-Forward-Proto` header if terminating TLS. See (see [TLS termination](#tls-termination) notes below). - -## Load balancer annotations - -Kubernetes on AWS exposes a mechanism to request certain load balancer configurations by annotating the `type: LoadBalancer` `Service`. The most complete set and explanations of these annotations can be found in this [Kubernetes document](https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer). This document will go over the subset that is most relevant when deploying $productName$. - -- `service.beta.kubernetes.io/aws-load-balancer-ssl-cert`: - - Configures the load balancer to use a valid certificate ARN to terminate TLS at the Load Balancer. - - Traffic from the client into the load balancer is encrypted but, since TLS is being terminated at the load balancer, traffic from the load balancer to $productName$ will be cleartext. You will need to configure $productName$ differently depending on whether the load balancer is running in L4 or L7 (see [TLS termination](#tls-termination) notes below). - -- `service.beta.kubernetes.io/aws-load-balancer-ssl-ports`: - - Configures which port the load balancer will be listening for SSL traffic on. Defaults to `"*"`. - - If you want to enable cleartext redirection, make sure to set this to `"443"` so traffic on port 80 will come in over cleartext. - -- `service.beta.kubernetes.io/aws-load-balancer-backend-protocol`: - - Configures the ELB to operate in L4 or L7 mode. Can be set to `"tcp"`/`"ssl"` for an L4 listener or `"http"`/`"https"` for an L7 listener. Defaults to `"tcp"` or `"ssl"` if `aws-load-balancer-ssl-cert` is set. - -- `service.beta.kubernetes.io/aws-load-balancer-type: "nlb"`: - - When this annotation is set it will launch a [Network Load Balancer (NLB)](#network-load-balancer-nlb) instead of a classic ELB. - -- `service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled`: - - Configures the load balancer to load balance across zones. For high availability, it is typical to deploy nodes across availability zones so this should be set to `"true"`. - - **Note:** You cannot configure this annotation and `service.beta.kubernetes.io/aws-load-balancer-type: "nlb"` at the same time. You must first deploy the `Service` with an NLB and then update it with the cross zone load balancing configuration. - -- `service.beta.kubernetes.io/aws-load-balancer-proxy-protocol`: - - Configures the ELB to enable the proxy protocol. `"*"`, which enables the proxy protocol on all ELB backends, is the only acceptable value. - - The proxy protocol can be used to preserve the client IP address. - - If setting this value, you need to make sure $productName$ is configured to use the proxy protocol (see [preserving the client IP address](#preserving-the-client-ip-address) below). - - **Note:** This annotation will not be recognized if `aws-load-balancer-type: "nlb"` is configured. Proxy protocol must be manually enabled for NLBs. - -## TLS termination - -TLS termination is an important part of any modern web app. $productName$ exposes a lot of TLS termination configuration options that make it a powerful tool for managing encryption between your clients and microservices. Refer to the [TLS Termination](../tls) documentation for more information on how to configure TLS termination at $productName$. - -With AWS, the AWS Certificate Manager (ACM) makes it easy to configure TLS termination at an AWS load balancer using the annotations explained above. - -This means that, when running $productName$ in AWS, you have the choice between terminating TLS at the load balancer using a certificate from the ACM or at $productName$ using a certificate stored as a `Secret` in your cluster. - -The following documentation will cover the different options available to you and how to configure $productName$ and the load balancer to get the most of each. - -### TLS termination at $productName$ - -Terminating TLS at $productName$ will guarantee you to be able to use all of the TLS termination options that $productName$ exposes including enforcing the minimum TLS version, setting the `alpn_protocols`, and redirecting cleartext to HTTPS. - -If terminating TLS at $productName$, you can provision any AWS load balancer that you want with the following (default) port assignments: - -```yaml -spec: - ports: - - name: http - port: 80 - targetPort: 8080 - - name: https - port: 443 - targetPort: 8443 -``` - -While terminating TLS at $productName$ makes it easier to expose more advanced TLS configuration options, it does have the drawback of not being able to use the ACM to manage certificates. You will have to manage your TLS certificates yourself or use the [automatic certificate management](../host-crd) available in $productName$ to have $productName$ do it for you. - -### TLS termination at the load balancer - -If you choose to terminate TLS at your Amazon load balancer you will be able to use the ACM to manage TLS certificates. This option does add some complexity to your $productName$ configuration, depending on which load balancer you are using. - -Terminating TLS at the load balancer means that $productName$ will be receiving all traffic as un-encrypted cleartext traffic. Since $productName$ expects to be serving both encrypted and cleartext traffic by default, you will need to make the following configuration changes to $productName$ to support this: - -#### L4 load balancer (default ELB or NLB) - -* **Load Balancer Service Configuration:** - The following `Service` will deploy a L4 ELB with TLS termination configured at the load balancer: - ```yaml - apiVersion: v1 - kind: Service - metadata: - name: ambassador - namespace: ambassador - annotations: - service.beta.kubernetes.io/aws-load-balancer-ssl-cert: {{ACM_CERT_ARN}} - service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "443" - spec: - type: LoadBalancer - ports: - - name: HTTP - port: 80 - targetPort: 8080 - - name: HTTPS - port: 443 - targetPort: 8080 - selector: - service: ambassador - ``` - - Note that the `spec.ports` has been changed so both the HTTP and HTTPS ports forward to the cleartext port 8080 on $productName$. - -* **`Host`:** - - The `Host` configures how $productName$ handles encrypted and cleartext traffic. The following `Host` configuration will tell $productName$ to `Route` cleartext traffic that comes in from the load balancer: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Host - metadata: - name: ambassador - spec: - hostname: "*" - selector: - matchLabels: - hostname: wildcard - acmeProvider: - authority: none - requestPolicy: - insecure: - action: Route - ``` - -**Important:** - -Because L4 load balancers do not set `X-Forwarded` headers, $productName$ will not be able to distinguish between traffic that came in to the load balancer as encrypted or cleartext. Because of this, **HTTP -> HTTPS redirection is not possible when terminating TLS at a L4 load balancer**. - -#### L7 load balancer (ELB or ALB) - -* **Load Balancer Service Configuration (L7 ELB):** - - The following `Service` will deploy a L7 ELB with TLS termination configured at the load balancer: - ```yaml - apiVersion: v1 - kind: Service - metadata: - name: ambassador - namespace: ambassador - annotations: - service.beta.kubernetes.io/aws-load-balancer-ssl-cert: {{ACM_CERT_ARN}} - service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "443" - service.beta.kubernetes.io/aws-load-balancer-backend-protocol: "http" - spec: - type: LoadBalancer - ports: - - name: HTTP - port: 80 - targetPort: 8080 - - name: HTTPS - port: 443 - targetPort: 8080 - selector: - service: ambassador - ``` - - Note that the `spec.ports` has been changed so both the HTTP and HTTPS ports forward to the cleartext port 8080 on $productName$. - -* **`Host`:** - - The `Host` configures how $productName$ handles encrypted and cleartext traffic. The following `Host` configuration will tell $productName$ to `Redirect` cleartext traffic that comes in from the load balancer: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Host - metadata: - name: ambassador - spec: - hostname: "*" - selector: - matchLabels: - hostname: wildcard - acmeProvider: - authority: none - requestPolicy: - insecure: - action: Redirect - ``` - -* **Module:** - - Since a L7 load balancer will be able to append to `X-Forwarded` headers, we need to configure $productName$ to trust the value of these headers. The following `Module` will configure $productName$ to trust a single L7 proxy in front of $productName$: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - xff_num_trusted_hops: 1 - use_remote_address: false - ``` - -**Note:** - -$productName$ uses the value of `X-Forwarded-Proto` to know if the request originated as encrypted or cleartext. Unlike L4 load balancers, L7 load balancers will set this header so HTTP -> HTTPS redirection is possible when terminating TLS at a L7 load balancer. - -## Preserving the client IP address - -Many applications will want to know the IP address of the connecting client. In Kubernetes, this IP address is often obscured by the IP address of the `Node` that is forwarding the request to $productName$ so extra configuration must be done if you need to preserve the client IP address. - -In AWS, there are two options for preserving the client IP address. - -1. Use a L7 Load Balancer that sets `X-Forwarded-For` - - A L7 load balancer will populate the `X-Forwarded-For` header with the IP address of the downstream connecting client. If your clients are connecting directly to the load balancer, this will be the IP address of your client. - - When using L7 load balancers, you must configure $productName$ to trust the value of `X-Forwarded-For` and not append its own IP address to it by setting `xff_num_trusted_hops` and `use_remote_address: false` in the [Ambassador `Module`](../ambassador): - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - xff_num_trusted_hops: 1 - use_remote_address: false - ``` - - After configuring the above `Module`, you will need to restart $productName$ for the changes to take effect. - -2. Use the proxy protocol - - The [proxy protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) is a wrapper around an HTTP request that, like `X-Forwarded-For`, lists the IP address of the downstream connecting client but is able to be set by L4 load balancers as well. - - In AWS, you can configure ELBs to use the proxy protocol by setting the `service.beta.kubernetes.io/aws-load-balancer-proxy-protocol: "*"` annotation on the service. You must manually configure this on ALBs and NLBs. - - After configuring the load balancer to use the proxy protocol, you need to tell $productName$ to expect it on the request. - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - use_proxy_proto: true - ``` - - After configuring the above `Module`, you will need to restart $productName$ for the changes to take effect. diff --git a/content/en/docs/3.2/topics/running/ambassador-with-gke.md b/content/en/docs/3.2/topics/running/ambassador-with-gke.md deleted file mode 100644 index 2b90581d..00000000 --- a/content/en/docs/3.2/topics/running/ambassador-with-gke.md +++ /dev/null @@ -1,187 +0,0 @@ -# $productName$ with GKE - -Google offers a [L7 load balancer](https://cloud.google.com/kubernetes-engine/docs/concepts/ingress) to -leverage network services such as managed SSL certificates, SSL offloading or the Google content delivery network. -A L7 load balancer in front of $productName$ can be configured by hand or by using the Ingress-GCE resource. Using the -Ingress resource also allows you to create Google-managed SSL certificates through Kubernetes. - -With this setup, HTTPS will be terminated at the Google load balancer. The load balancer will be created and configured by -the Ingress-GCE resource. The load balancer consists of a set of -[forwarding rules](https://cloud.google.com/load-balancing/docs/forwarding-rule-concepts#https_lb) and a set of -[backend services](https://cloud.google.com/load-balancing/docs/backend-service). -In this setup, the ingress resource creates two forwarding rules, one for HTTP and one for HTTPS. The HTTPS -forwarding rule has the SSL certificates attached. Also, one backend service will be created to point to -a list of instance groups at a static port. This will be the NodePort of the $productName$ service. - -With this setup, the load balancer terminates HTTPS and then directs the traffic to the $productName$ service -via the `NodePort`. $productName$ is then doing all the routing to the other internal/external services. - -# Overview of steps - -1. Install and configure the ingress with the HTTP(S) load balancer -2. Install $productName$ -3. Configure and connect $productName$ to ingress -4. Create an SSL certificate and enable HTTPS -5. Create BackendConfig for health checks -6. Configure $productName$ to do HTTP -> HTTPS redirection - -`ambassador` will be running as a `NodePort` service. Health checks will be configured to go to a BackendConfig resource. - -## 0. $productName$ - -This guide will install $OSSproductName$. You can also install $AESproductName$. Please note: -- The ingress and the `ambassador` service need to run in the same namespace -- The `ambassador` service needs to be of type `NodePort` and not `LoadBalancer`. Also remove the line with `externalTrafficPolicy: Local` -- Ambassador-Admin needs to be of type `NodePort` instead of `ClusterIP` since it needs to be available for health checks - -## 1 . Install and configure ingress with the HTTP(S) load balancer - -Create a GKE cluster through the web console. Use the release channel. When the cluster -is up and running follow [this tutorial from Google](https://cloud.google.com/kubernetes-engine/docs/tutorials/http-balancer) to configure -an ingress and a L7 load balancer. After you have completed these steps you will have a running L7 load balancer -and one service. - -## 2. Install $productName$ - -Follow the first section of the [$OSSproductName$ installation guide](../../install/) to install $OSSproductName$. -Stop before defining the `ambassador` service. - -$productName$ needs to be deployed as `NodePort` instead of `LoadBalancer` to work with the L7 load balancer and the ingress. - -Save the YAML below in ambassador.yaml and apply with `kubectl apply -f ambassador.yaml` - -```yaml -apiVersion: v1 -kind: Service -metadata: - name: ambassador -spec: - type: NodePort - ports: - - port: 8080 - targetPort: 8080 - selector: - service: ambassador -``` - -You will now have an `ambassador` service running next to your ingress. - -## 3. Configure and connect `ambassador` to the ingress - -You need to change the ingress for it to send traffic to `ambassador`. Assuming you have followed the tutorial, you should -have a file named basic-ingress.yaml. Change it to point to `ambassador` instead of web: - -```yaml -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - name: basic-ingress -spec: - backend: - serviceName: ambassador - servicePort: 8080 -``` - -Now let's connect the other service from the tutorial to `ambassador` by specifying a Mapping: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: web - namespace: default -spec: - hostname: "*" - prefix: / - service: web:8080 -``` - -All traffic will now go to `ambassador` and from `ambassador` to the `web` service. You should be able to hit your load balancer and get the output. It may take some time until the load balancer infrastructure has rolled out all changes and you might see gateway errors during that time. -As a side note: right now all traffic will go to the `web` service, including the load balancer health check. - -## 4. Create an SSL certificate and enable HTTPS - -Read up on [managed certificates on GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/managed-certs). You need -a DNS name and point it to the external IP of the load balancer. - -certificate.yaml: -```yaml -apiVersion: networking.gke.io/v1beta1 -kind: ManagedCertificate -metadata: - name: www-example-com -spec: - domains: - - www.example.com -``` - -Modify the ingress from before: -```yaml -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - name: basic-ingress - annotations: - networking.gke.io/managed-certificates: www-example-com -spec: - backend: - serviceName: ambassador - servicePort: 8080 -``` - -Please wait (5-15 minutes) until the certificate is created and all edge servers have the certificates ready. -`kubectl describe ManagedCertificate` will show you the status or go to the web console to view the load balancer. - -You should now be able to access the web service via `https://www.example.com`. - -## 5. Configure BackendConfig for health checks - -Create and apply a BackendConfig resource with a [custom health check](https://cloud.google.com/kubernetes-engine/docs/how-to/ingress-features#direct_health) specified: - -```yaml -apiVersion: cloud.google.com/v1 -kind: BackendConfig -metadata: - name: ambassador-hc-config - namespace: ambassador -spec: - # https://cloud.google.com/kubernetes-engine/docs/how-to/ingress-features - timeoutSec: 30 - connectionDraining: - drainingTimeoutSec: 30 - logging: - enable: true - sampleRate: 1.0 - healthCheck: - checkIntervalSec: 10 - timeoutSec: 10 - port: 8877 - type: HTTP - requestPath: /ambassador/v0/check_alive -``` - -Then edit your previous `ambassador.yaml` file to add an annotation referencing the BackendConfig and apply the file: - -``` -apiVersion: v1 -kind: Service -metadata: - name: ambassador - annotations: - cloud.google.com/backend-config: '{"default": "ambassador-hc-config"}' -spec: - type: NodePort - ports: - - port: 8080 - targetPort: 8080 - selector: - service: ambassador -``` - -## 6. Configure $productName$ to do HTTP -> HTTPS redirection - -Configure $productName$ to [redirect traffic from HTTP to HTTPS](../tls/cleartext-redirection/#http-https-redirection). You will need to restart $productName$ to effect the changes with `kubectl rollout restart deployment ambassador`. - -The result should be that `http://www.example.com` will redirect to `https://www.example.com`. - -You can now add more services by specifying the hostname in the Mapping. diff --git a/content/en/docs/3.2/topics/running/ambassador.md b/content/en/docs/3.2/topics/running/ambassador.md deleted file mode 100644 index 3af41d93..00000000 --- a/content/en/docs/3.2/topics/running/ambassador.md +++ /dev/null @@ -1,558 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# The `Ambassador` `Module` Resource - -
-

Contents

- -* [Envoy](#envoy) -* [General](#general) -* [gRPC](#grpc) -* [Header behavior](#header-behavior) -* [Observability](#observability) -* [Protocols](#protocols) -* [Security](#security) -* [Service health / timeouts](#service-health--timeouts) -* [Traffic management](#traffic-management) - - -
- -If present, the `ambassador` `Module` defines system-wide configuration for $productName$. You won't need it unless you need to change one of the system-wide configuration settings below. - -To use the `ambassador` `Module` to configure $productName$, it MUST be named `ambassador`, otherwise it will be ignored. To create multiple `ambassador` `Module`s in the same Kubernetes namespace, you will need to apply them as annotations with separate `ambassador_id`s: you will not be able to use multiple CRDs. - -There are many items that can be configured on the `ambassador` `Module`. They are listed below with examples and grouped by category. - -## Envoy - -##### Content-Length headers - -* `allow_chunked_length: true` tells Envoy to allow requests or responses with both `Content-Length` and `Transfer-Encoding` headers set. The default is `false`. - -By default, messages with both `Content-Length` and `Content-Transfer-Encoding` are rejected. If `allow_chunked_length` is `true`, $productName$ will remove the `Content-Length` header and process the message. See the [Envoy documentation for more details](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto.html?highlight=allow_chunked_length#config-core-v3-http1protocoloptions). - -##### Envoy access logs - -* `envoy_log_path` defines the path of Envoy's access log. By default this is standard output. -* `envoy_log_type` defines the type of access log Envoy will use. Currently, only `json` or `text` are supported. -* `envoy_log_format` defines the Envoy access log line format. - -These logs can be formatted using [Envoy operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) to display specific information about an incoming request. The example below will show only the protocol and duration of a request: - -```yaml -envoy_log_path: /dev/fd/1 -envoy_log_type: json -envoy_log_format: - { - "protocol": "%PROTOCOL%", - "duration": "%DURATION%" - } -``` - -See the Envoy documentation for the [standard log format](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#default-format-string) and a [complete list of log format operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/access_log). - -##### Envoy validation timeout - -* `envoy_validation_timeout` defines the timeout, in seconds, for validating a new Envoy configuration. The default is 10. - -A value of 0 disables Envoy configuration validation. Most installations will not need to change this setting. - -For example: - -```yaml -envoy_validation_timeout: 30 -``` - -would allow 30 seconds to validate the generated Envoy configuration. - -##### Error response overrides - -* `error_response_overrides` permits changing the status code and body text for 4XX and 5XX response codes. The default is not to override any error responses. - -By default, $productName$ will pass through error responses without modification, and errors generated locally will use Envoy's default response body, if any. - -See [using error response overrides](../custom-error-responses) for usage details. For example, this configuration: - -```yaml -error_response_overrides: - - on_status_code: 404 - body: - text_format: "File not found" -``` - -would explicitly modify the body of 404s to say "File not found". - -##### Forwarding client cert details - -Two attributes allow providing information about the client's TLS certificate to upstream certificates: - -* `forward_client_cert_details: true` will tell Envoy to add the `X-Forwarded-Client-Cert` to upstream - requests. The default is `false`. -* `set_current_client_cert_details` will tell Envoy what information to include in the - `X-Forwarded-Client-Cert` header. The default is not to include the `X-Forwarded-Client-Cert` header at all. - -$productName$ will not forward information about a certificate that it cannot validate. - -See the Envoy documentation on [X-Forwarded-Client-Cert](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers.html?highlight=xfcc#x-forwarded-client-cert) and [SetCurrentClientCertDetails](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto.html#extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-setcurrentclientcertdetails) for more information. - -```yaml -forward_client_cert_details: true -set_current_client_cert_details: SANITIZE -``` - -##### Server name - -* `server_name` allows overriding the server name that Envoy sends with responses to clients. The default is `envoy`. - -##### Suppress Envoy headers - -* `suppress_envoy_headers: true` will prevent $productName$ from emitting certain additional - headers to HTTP requests and responses. The default is `false`. - -For the exact set of headers covered by this config, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter#config-http-filters-router-headers-set) - ---- -## General - -##### Ambassador ID - -* `ambassador_id` allows using multiple instances of $productName$ in the same cluster. The default is unset. - -We recommend _not_ setting `ambassador_id` if you are running only one instance of $productName$ in your cluster. For more information, see the [Running and Deployment documentation](../running/#ambassador_id). - -If used, the `ambassador_id` value must be an array, for example: - -```yaml -ambassador_id: [ "test_environment" ] -``` - -##### Defaults - -* `defaults` provides a dictionary of default values that will be applied to various $productName$ resources. The default is to have no defaults configured. - -See [Using `ambassador` `Module` Defaults](../../using/defaults) for more information. - ---- - -## gRPC - -##### Bridges - -* `enable_grpc_http11_bridge: true` will enable the gRPC-HTTP/1.1 bridge. The default is `false`. -* `enable_grpc_web: true` will enable the gRPC-Web bridge. The default is `false`. - -gRPC is a binary HTTP/2-based protocol. While this allows high performance, it can be problematic for clients that are unable to speak HTTP/2 (such as JavaScript in many browsers, or legacy clients in difficult-to-update environments). - -The gRPC-HTTP/1.1 bridge can translate HTTP/1.1 calls with `Content-Type: application/grpc` into gRPC calls: $productName$ will perform buffering and translation as necessary. For more details on the translation process, see the [Envoy gRPC HTTP/1.1 bridge documentation](https://www.envoyproxy.io/docs/envoy/v1.11.2/configuration/http_filters/grpc_http1_bridge_filter.html). - -Likewise, gRPC-Web is a JSON and HTTP-based protocol that allows browser-based clients to take advantage of gRPC protocols. The gRPC-Web specification requires a server-side proxy to translate between gRPC-Web requests and gRPC backend services, and $productName$ can fill this role when the gRPC-Web bridge is enabled. For more details on the translation process, see the [Envoy gRPC HTTP/1.1 bridge documentation](https://www.envoyproxy.io/docs/envoy/v1.11.2/configuration/http_filters/grpc_http1_bridge_filter.html); for more details on gRPC-Web itself, see the [gRPC-Web client GitHub repo](https://github.com/grpc/grpc-web). - -##### Statistics - -* `grpc_stats` allows enabling telemetry for gRPC calls using Envoy's [gRPC Statistics Filter](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/grpc_stats_filter). The default is disabled. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - grpc_stats: - upstream_stats: true - services: - - name: . - method_names: [] -``` - -Supported parameters: -* `all_methods` -* `services` -* `upstream_stats` - -Available metrics: -* `envoy_cluster_grpc__` -* `envoy_cluster_grpc__request_message_count` -* `envoy_cluster_grpc__response_message_count` -* `envoy_cluster_grpc__success` -* `envoy_cluster_grpc__total` -* `envoy_cluster_grpc_upstream_` - **only when `upstream_stats: true`** - -Please note that `` will only be present if `all_methods` is set or the service and the method are present under `services`. If `all_methods` is false or the method is not on the list, the available metrics will be in the format `envoy_cluster_grpc_`. - -* `all_methods`: If set to true, emit stats for all service/method names. -If set to false, emit stats for all service/message types to the same stats without including the service/method in the name. -**This option is only safe if all clients are trusted. If this option is enabled with untrusted clients, the clients could cause unbounded growth in the number -of stats in Envoy, using unbounded memory and potentially slowing down stats pipelines.** - -* `services`: If set, specifies an allow list of service/methods that will have individual stats emitted for them. Any call that does not match the allow list will be counted in a stat with no method specifier (generic metric). - - - If both all_methods and services are present, all_methods will be ignored. - - -* `upstream_stats`: If true, the filter will gather a histogram for the request time of the upstream. - ---- - -## Header behavior - -##### Header case - -* `proper_case: true` forces headers to have their "proper" case as shown in RFC7230. The default is `false`. -* `header_case_overrides` allows forcing certain headers to have specific casing. The default is to override no headers. - -proper_case and header_case_overrides are mutually exclusive. - -RFC7230 specifies that HTTP header names are case-insensitive, but always shows and refers to headers as starting with a capital letter, continuing in lowercase, then repeating the single capital letter after each non-alpha character. This has become an established convention when working with HTTP: - -- `Host`, not `host` or `HOST` -- `Content-Type`, not `content-type`, `Content-type`, or `cOnTeNt-TyPe` - -Internally, Envoy typically uses [all lowercase](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/header_casing) for header names. This is fully compliant with RFC7230, but some services and clients may require headers to follow the stricter casing rules implied by RFC7230 section headers: in that situation, setting `proper_case: true` will tell Envoy to force all headers to use the casing above. - -Alternately, it is also possible - although less common - for services or clients to require some other specific casing for specific headers. `header_case_overrides` specifies an array of header names: if a case-insensitive match for a header is found in the list, the matching header will be replaced with the one in the list. For example, the following configuration will force headers that match `X-MY-Header` and `X-EXPERIMENTAL` to use that exact casing, regardless of the original case used in flight: - -```yaml -header_case_overrides: -- X-MY-Header -- X-EXPERIMENTAL -``` - -If the upstream service responds with `x-my-header: 1`, $productName$ will return `X-MY-Header: 1` to the client. Similarly, if the client includes `x-ExperiMENTAL: yes` in its request, the request to the upstream service will include `X-EXPERIMENTAL: yes`. Other headers will not be altered; $productName$ will use its default lowercase header. - -Please see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto.html#config-core-v3-http1protocoloptions-headerkeyformat) for more information. Note that in general, we recommend updating clients and services rather than relying on `header_case_overrides`. - -##### Linkerd interoperability - -* `add_linkerd_headers: true` will force $productName$ to include the `l5d-dst-override` header for Linkerd. The default is `false`. - -When using older Linkerd installations, requests going to an upstream service may need to include the `l5d-dst-override` header to ensure that Linkerd will route them correctly. Setting `add_linkerd_headers` does this automatically. See the [Mapping](../../using/mappings#linkerd-interoperability-add_linkerd_headers) documentation for more details. - -##### Max request headers size - -* `max_request_headers_kb` sets the maximum allowed request header size in kilobytes. If not set, the default is 60 KB. - -See [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto.html) for more information. - -##### Preserve external request ID - -* `preserve_external_request_id: true` will preserve any `X-Request-Id` header presented by the client. The default is `false`, in which case Envoy will always generate a new `X-Request-Id` value. - -##### Strip matching host port - -* `strip_matching_host_port: true` will tell $productName$ to strip any port number from the host/authority header before processing and routing the request if that port number matches the port number of Envoy's listener. The default is `false`, which will preserve any port number. - -In the default installation of $productName$ the public port is 443, which then maps internally to 8443, so this only works in custom installations where the public Service port and Envoy listener port match. - -A common reason to try using this property is if you are using gRPC with TLS and your client library appends the port to the Host header (i.e. `myurl.com:443`). We have an alternative solution in our [gRPC guide](../../../howtos/grpc#working-with-host-headers-that-include-the-port) that uses a [Lua script](#lua-scripts) to remove all ports from every Host header for that use case. - ---- - -## Miscellaneous - - -##### Envoy's admin port - -* `admin_port` specifies the port where $productName$'s Envoy will listen for low-level admin requests. The default is 8001; it should almost never need changing. - -##### Lua scripts - -* `lua_scripts` allows defining a custom Lua script to run on every request. The default is to run no script. - -This is useful for simple use cases that mutate requests or responses, for example to add a custom header: - -```yaml -lua_scripts: | - function envoy_on_response(response_handle) - response_handle:headers():add("Lua-Scripts-Enabled", "Processed") - end -``` - -For more details on the Lua API, see the [Envoy Lua filter documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/lua_filter.html). - -Some caveats around the embedded scripts: - -* They run in-process, so any bugs in your Lua script can break every request. -* They're run on every request/response to every URL. -* They're inlined in the $productName$ YAML; as such, we do not recommend using Lua scripts for long, complex logic. - -If you need more flexible and configurable options, $AESproductName$ supports a [pluggable Filter system](/docs/edge-stack/latest/topics/using/filters/). - -##### Merge slashes - -* `merge_slashes: true` will cause $productName$ to merge adjacent slashes in incoming paths when doing route matching and request filtering. The default is `false`. - -For example, with `merge_slashes: true`, a request for `//foo///bar` would be matched to a `Mapping` with prefix `/foo/bar`. - -##### Modify Default Buffer Size - -By default, the Envoy that ships with $productName$ uses a defailt of 1MiB soft limit for an upstream service's read and write buffer limits. This setting allows you to configure that buffer limit. See the [Envoy docs](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto.html?highlight=per_connection_buffer_limit_bytes) for more information. - -```yaml -buffer_limit_bytes: 5242880 # Sets the default buffer limit to 5 MiB -``` - -##### Use $productName$ namespace for service resolution - -* `use_ambassador_namespace_for_service_resolution: true` tells $productName$ to assume that unqualified services are in the same namespace as $productName$. The default is `false`. - -By default, when $productName$ sees a service name without a namespace, it assumes that the namespace is the same as the resource referring to the service. For example, for this `Mapping`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-1 - namespace: foo -spec: - hostname: "*" - prefix: / - service: upstream -``` - -$productName$ would look for a Service named `upstream` in namespace `foo`. - -However, if `use_ambassador_namespace_for_service_resolution` is `true`, this `Mapping` would look for a Service named `foo` in the namespace in which $productName$ is installed instead. - ---- - -## Observability - -##### Diagnostics - -* `diagnostics` controls access to the diagnostics interface. - -By default, $productName$ creates a `Mapping` that allows access to the diagnostic interface at `/ambassador/v0/diag` from anywhere in the cluster. To disable the `Mapping` entirely, set `diagnostics.enabled` to `false`: - - -```yaml -diagnostics: - enabled: false -``` - -With diagnostics disabled, `/ambassador/v0/diag` will respond with 404; however, the service itself is still running, and `/ambassador/v0/diag/` is reachable from inside the $productName$ Pod at `https://localhost:8877`. You can use Kubernetes port forwarding to set up remote access to the diagnostics page temporarily: - -``` -kubectl port-forward -n ambassador deploy/ambassador 8877 -``` - -Alternately, to leave the `Mapping` intact but restrict access to only the local Pod, set `diagnostics.allow_non_local` to `false`: - -```yaml -diagnostics: - allow_non_local: true -``` - -See [Protecting Access to the Diagnostics Interface](../../../howtos/protecting-diag-access) for more information. - ---- -## Protocols - -##### Enable IPv4 and IPv6 - -* `enable_ipv4` determines whether IPv4 DNS lookups are enabled. The default is `true`. -* `enable_ipv6` determines whether IPv6 DNS lookups are enabled. The default is `false`. - -If both IPv4 and IPv6 are enabled, $productName$ will prefer IPv6. This can have strange effects if $productName$ receives `AAAA` records from a DNS lookup, but the underlying network of the pod doesn't actually support IPv6 traffic. For this reason, the default is IPv4 only. - -An [`Mapping`](../../using/mappings) can override both `enable_ipv4` and `enable_ipv6`, but if either is not stated explicitly in a `Mapping`, the values here are used. Most $productName$ installations will probably be able to avoid overriding these settings in Mappings. - -##### HTTP/1.0 support - -* `enable_http10: true` will enable handling incoming HTTP/1.0 and HTTP/0.9 requests. The default is `false`. - ---- -## Security - -##### Cross origin resource sharing (CORS) - -* `cors` sets the default CORS configuration for all mappings in the cluster. The default is that CORS is not configured. - -For example: - -```yaml -cors: - origins: http://foo.example,http://bar.example - methods: POST, GET, OPTIONS - ... -``` - -See the [CORS syntax](../../using/cors) for more information. - -##### IP allow and deny - -* `ip_allow` and `ip_deny` define HTTP source IP address ranges to allow or deny. The default is to allow all traffic. - -Only one of ip_allow and ip_deny may be specified. - -If `ip_allow` is specified, any traffic not matching a range to allow will be denied. If `ip_deny` is specified, any traffic not matching a range to deny will be allowed. A list of ranges to allow and a separate list to deny may not both be specified. - -Both take a list of IP address ranges with a keyword specifying how to interpret the address, for example: - -```yaml -ip_allow: -- peer: 127.0.0.1 -- remote: 99.99.0.0/16 -``` - -The keyword `peer` specifies that the match should happen using the IP address of the other end of the network connection carrying the request: `X-Forwarded-For` and the `PROXY` protocol are both ignored. Here, our example specifies that connections originating from the $productName$ pod itself should always be allowed. - -The keyword `remote` specifies that the match should happen using the IP address of the HTTP client, taking into account `X-Forwarded-For` and the `PROXY` protocol if they are allowed (if they are not allowed, or not present, the peer address will be used instead). This permits matches to behave correctly when, for example, $productName$ is behind a layer 7 load balancer. Here, our example specifies that HTTP clients from the IP address range `99.99.0.0` - `99.99.255.255` will be allowed. - -You may specify as many ranges for each kind of keyword as desired. - -##### Rejecting Client Requests With Escaped Slashes - -* `reject_requests_with_escaped_slashes: true` will tell $productName$ to reject requests containing escaped slashes. The default is `false`. - -When set to `true`, $productName$ will reject any client requests that contain escaped slashes (`%2F`, `%2f`, `%5C`, or `%5c`) in their URI path by returning HTTP 400. By default, $productName$ will forward these requests unmodified. - -In general, a request with an escaped slash will _not_ match a `Mapping` prefix with an unescaped slash. However, external authentication services and other upstream services may handle escaped slashes differently, which can lead to security issues if paths with escaped slashes are allowed. By setting `reject_requests_with_escaped_slashes: true`, this class of security concern can be largely avoided. - -##### Trust downstream client IP - -* `use_remote_address: false` tells $productName$ that it cannot trust the remote address of incoming connections, and must instead rely exclusively on the `X-Forwarded-For` header. The default is `true`. - -When `true` (the default), $productName$ will append its own IP address to the `X-Forwarded-For` header so that upstream services of $productName$ can get the full set of IP addresses that have propagated a request. You may also need to set `externalTrafficPolicy: Local` on your `LoadBalancer` to propagate the original source IP address. - -See the [Envoy documentation on the `X-Forwarded-For header` ](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers) and the [Kubernetes documentation on preserving the client source IP](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/#preserving-the-client-source-ip) for more details. - -##### `X-Forwarded-For` trusted hops - -* `xff_num_trusted_hops` sets the default value for [the `l7Depth` setting of a `Listener`](../listener/#securitymodel). The default is 0. - -See the [`Listener` documentation](../listener/#securitymodel) for more details. - ---- - -## Service health / timeouts - -##### Incoming connection idle timeout - -* `listener_idle_timeout_ms` sets the idle timeout for incoming connections. The default is no timeout, meaning that incoming connections may remain idle forever. - -If set, this specifies the length of time (in milliseconds) that an incoming connection is allowed to be idle before being dropped. This can useful if you have proxies and/or firewalls in front of $productName$ and need to control how $productName$ initiates closing an idle TCP connection. - -Please see the [Envoy documentation on HTTP protocol options](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#config-core-v3-httpprotocoloptions) for more information. - -##### Keepalive - -* `keepalive` sets the global TCP keepalive settings. - -$productName$ will use these settings for all `AmbasasdorMapping`s unless overridden in a `Mapping`'s configuration. Without `keepalive`, $productName$ follows the operating system defaults. - -For example, the following configuration: - -```yaml -keepalive: - time: 2 - interval: 2 - probes: 100 -``` - -would enable keepalives every two seconds (`interval`), starting after two seconds of idleness (`time`), with the connection being dropped if 100 keepalives are sent with no response (`probes`). For more information, see the [Envoy keepalive documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/address.proto.html#config-core-v3-tcpkeepalive). - -##### Upstream idle timeout - -* `cluster_idle_timeout_ms` sets the default idle timeout for upstream connections (by default, one hour). - -If set, this specifies the timeout (in milliseconds) after which an idle connection upstream is closed. The idle timeout can be completely disabled by setting `cluster_idle_timeout_ms: 0`, which risks idle upstream connections never getting closed. - -If not set, the default idle timeout is one hour. - -You can override this setting with [`idle_timeout_ms` on a `Mapping`](../../using/timeouts/). - -##### Upstream max lifetime - -* `cluster_max_connection_lifetime_ms` sets the default maximum lifetime of an upstream connection. - -If set, this specifies the maximum amount of time (in milliseconds) after which an upstream connection is drained and closed, regardless of whether it is idle or not. Connection recreation incurs additional overhead when processing requests. The overhead tends to be nominal for plaintext (HTTP) connections within the same cluster, but may be more significant for secure HTTPS connections or upstreams with high latency. For this reason, it is generally recommended to set this value to at least 10000 ms to minimize the amortized cost of connection recreation while providing a reasonable bound for connection lifetime. - -If not set (or set to zero), then upstream connections may remain open for arbitrarily long. - -You can override this setting with [`cluster_max_connection_lifetime_ms` on a `Mapping`](../../using/timeouts/). - -##### Request timeout - -* `cluster_request_timeout_ms` sets the default end-to-end timeout for a single request. - -If set, this specifies the default end-to-end timeout for every request. - -If not set, the default is three seconds. - -You can override this setting with [`timeout_ms` on a `Mapping`](../../using/timeouts/). - -##### Readiness and liveness probes - -* `readiness_probe` sets whether `/ambassador/v0/check_ready` is automatically mapped -* `liveness_probe` sets whether `/ambassador/v0/check_alive` is automatically mapped - -By default, $productName$ creates `Mapping`s that support readiness and liveness checks at `/ambassador/v0/check_ready` and `/ambassador/v0/check_alive`. To disable the readiness `Mapping` entirely, set `readiness_probe.enabled` to `false`: - - -```yaml -readiness_probe: - enabled: false -``` - -Likewise, to disable the liveness `Mapping` entirely, set `liveness_probe.enabled` to `false`: - - -```yaml -liveness_probe: - enabled: false -``` - -A disabled probe endpoint will respond with 404; however, the service is still running, and will be accessible on localhost port 8877 from inside the $productName$ Pod. - -You can change these to route requests to some other service. For example, to have the readiness probe map to the `quote` application's health check: - -```yaml -readiness_probe: - enabled: true - service: quote - rewrite: /backend/health -``` - -The liveness and readiness probes both support `prefix` and `rewrite`, with the same meanings as for [Mappings](../../using/mappings). - -##### Retry policy - -This lets you add resilience to your services in case of request failures by performing automatic retries. - -```yaml -retry_policy: - retry_on: "5xx" -``` - ---- - -## Traffic management - -##### Circuit breaking - -* `circuit_breakers` sets the global circuit breaking configuration defaults - -You can override the circuit breaker settings for individual `Mapping`s. By default, $productName$ does not configure any circuit breakers. For more information, see the [circuit breaking reference](../../using/circuit-breakers). - -##### Default label domain and labels - -* `default_labels` sets default domains and labels to apply to every request. - -For more on how to use the default labels, , see the [Rate Limit reference](../../using/rate-limits/#attaching-labels-to-requests). - -##### Default load balancer - -* `load_balancer` sets the default load balancing type and policy - -For example, to set the default load balancer to `least_request`: - -```yaml -load_balancer: - policy: least_request -``` - -If not set, the default is to use round-robin load balancing. For more information, see the [load balancer reference](../load-balancer). diff --git a/content/en/docs/3.2/topics/running/custom-error-responses.md b/content/en/docs/3.2/topics/running/custom-error-responses.md deleted file mode 100644 index b0ad9877..00000000 --- a/content/en/docs/3.2/topics/running/custom-error-responses.md +++ /dev/null @@ -1,217 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Custom error responses - -Custom error responses set overrides for HTTP response statuses generated either -by $productName$ or upstream services. - -They can be configured either on the $productName$ -[`Module`](../ambassador) -or on an [`Mapping`](../../using/intro-mappings/), the schema is identical. See -below for more information on [rule precedence](#rule-precedence). - -- `on_status_code`: HTTP status code to match for this rewrite - rule. Only 4xx and 5xx classes are supported. -- `body`: Describes the response body contents and format. - + `content_type`: A string that sets the content type of the - response. - + `text_format`: A string whose value will be used as the new - response body. `Content-Type` will default to `text/plain` if - unspecified. - + `json_format`: A config object whose keys and values will be - serialized as JSON and used as the new response body. - + `text_format_source`: Describes a file to be used as the - response. If used, `filename` must be set and the file must exist - on the $productName$ pod. - * `filename`: A file path on the $productName$ pod that will be used - as the new response body. - -Only one of `text_format`, `json_format`, or `text_format_source` may be provided. - -Custom response bodies are subject to Envoy's AccessLog substitution syntax -and variables, see [Envoy's documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#config-access-log-format-strings) for more information. - -Note that the AccessLog substitutions use `%` as a delimiter (for example, -`%RESPONSE_CODE%`). To include a literal `%` in a custom response body, use `%%`. -For example, - -``` -%%RESPONSE_CODE%% %RESPONSE_CODE% -``` - -would render as - -``` -%RESPONSE_CODE% 401 -``` - -for a request that resulted in a response code of 401. - - - If the % 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. - - -## Simple response bodies - -Simple responses can be be added quickly for convenience. They are inserted into -the manifest as either text or JSON: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador - namespace: ambassador -spec: - config: - error_response_overrides: - - on_status_code: 404 - body: - text_format: "File not found" - - on_status_code: 500 - body: - json_format: - error: "Application error" - status: "%RESPONSE_CODE%" - cluster: "%UPSTREAM_CLUSTER%" -``` -## File response bodies - -For more complex response bodies a file can be returned as the response. -This could be used for a customer friendly HTML document for example. Use -`text_format_source` with a `filename` set as a path on the $productName$ pod. -`content_type` should be used set the specific file type, such as `text/html`. - -First configure the $productName$ module: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador - namespace: ambassador -spec: - config: - error_response_overrides: - - on_status_code: 404 - body: - content_type: "text/html" - text_format_source: - filename: '/ambassador/ambassador-errorpages/404.html' -``` - -Then create the config map containing the HTML file: - -```yaml ---- -apiVersion: v1 -kind: ConfigMap -metadata: - name: ambassador-errorpages - namespace: ambassador -data: - 404.html: | - -

File not found

-

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/content/en/docs/3.2/topics/running/debugging.md b/content/en/docs/3.2/topics/running/debugging.md deleted file mode 100644 index bd376483..00000000 --- a/content/en/docs/3.2/topics/running/debugging.md +++ /dev/null @@ -1,192 +0,0 @@ -# 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. - - - Enabling debug-level logging can produce a lot of log output — enough to - potentially impact the performance of $productName$. We don't recommend running with debug - logging enabled as a matter of course; it's usually better to enable it only when needed, - then reset logging to normal once you're finished debugging. - - -### $productName$ debug logging - -Much of $productName$'s logging is concerned with the business of noticing changes to -Kubernetes resources that specify the $productName$ configuration, and generating new -Envoy configuration in response to those changes. Enabling debug logging for this part -of the system is under the control of two environment variables: - -- Set `AES_LOG_LEVEL=debug` to debug the early boot sequence and $productName$'s interactions - with the Kubernetes cluster (finding changed resources, etc.). -- Set `AMBASSADOR_DEBUG=diagd` to debug the process of generating an Envoy configuration from - the input resources. - -### $productName$ Envoy logging - -Envoy logging is concerned with the actions Envoy is taking for incoming requests. -Typically, Envoy will only output access logs, and certain errors, but enabling Envoy -debug logging will show very verbose information about the actions Envoy is actually -taking. It can be useful for understanding why connections are being closed, or whether -an error status is coming from Envoy or from the upstream service. - -It is possible to enable Envoy logging at boot, but for the most part, it's safer to -enable it at runtime, right before sending a request that is known to have problems. -To enable Envoy debug logging, use `kubectl exec` to get a shell on the $productName$ -pod, then: - - ``` - curl -XPOST http://localhost:8001/logging?level=trace && \ - sleep 10 && \ - curl -XPOST http://localhost:8001/logging?level=warning - ``` - -This will turn on Envoy debug logging for ten seconds, then turn it off again. - -### Viewing logs - -To view the logs from $productName$: - -1. Use the following command to target an individual $productName$ Pod: `kubectl get pods -n $productNamespace$` - - The terminal will print something similar to the following: - - ``` - $ kubectl get pods -n $productNamespace$ - NAME READY STATUS RESTARTS AGE - $productDeploymentName$-85c4cf67b-4pfj2 1/1 Running 0 3m - ``` - -2. Then, run the following: `kubectl logs -n $productNamespace$ <$productDeploymentName$-pod-name>` - -The terminal will print something similar to the following: - - ``` - $ kubectl logs -n $productNamespace$ $productDeploymentName$-85c4cf67b-4pfj2 - 2018-10-10 12:26:50 kubewatch 0.40.0 INFO: generating config with gencount 1 (0 changes) - /usr/lib/python3.6/site-packages/pkg_resources/__init__.py:1235: UserWarning: /ambassador is writable by group/others and vulnerable to attack when used with get_resource_filename. Consider a more secure location (set with .set_extraction_path or the PYTHON_EGG_CACHE environment variable). - warnings.warn(msg, UserWarning) - 2018-10-10 12:26:51 kubewatch 0.40.0 INFO: Scout reports {"latest_version": "0.40.0", "application": "ambassador", "notices": [], "cached": false, "timestamp": 1539606411.061929} - - 2018-10-10 12:26:54 diagd 0.40.0 [P15TMainThread] INFO: thread count 3, listening on 0.0.0.0:8877 - [2018-10-10 12:26:54 +0000] [15] [INFO] Starting gunicorn 19.8.1 - [2018-10-10 12:26:54 +0000] [15] [INFO] Listening at: http://0.0.0.0:8877 (15) - [2018-10-10 12:26:54 +0000] [15] [INFO] Using worker: threads - [2018-10-10 12:26:54 +0000] [42] [INFO] Booting worker with pid: 42 - 2018-10-10 12:26:54 diagd 0.40.0 [P42TMainThread] INFO: Starting periodic updates - [2018-10-10 12:27:01.977][21][info][main] source/server/drain_manager_impl.cc:63] shutting down parent after drain - ``` - -Note that many deployments will have multiple logs, and the logs are independent for each Pod. - -## Examine Pod and container contents - -You can examine the contents of the $productName$ Pod for issues, such as if volume mounts are correct and TLS certificates are present in the required directory, to determine if the Pod has the latest $productName$ configuration, or if the generated Envoy configuration is correct or as expected. In these instructions, we will look for problems related to the Envoy configuration. - -1. To look into an $productName$ Pod, get a shell on the Pod using `kubectl exec`. For example, - - ``` - kubectl exec -it -n $productNamespace$ <$productDeploymentName$-pod-name> -- bash - ``` - -2. Determine the latest configuration. If you haven't overridden the configuration directory, the latest configuration will be in `/ambassador/snapshots`. If you have overridden it, $productName$ saves configurations in `$AMBASSADOR_CONFIG_BASE_DIR/snapshots`. - - In the snapshots directory: - - * `snapshot.yaml` contains the full input configuration that $productName$ has found; - * `aconf.json` contains the $productName$ configuration extracted from the snapshot; - * `ir.json` contains the IR constructed from the $productName$ configuration; and - * `econf.json` contains the Envoy configuration generated from the IR. - - In the snapshots directory, the current configuration will be stored in files with no digit suffix, and older configurations have increasing numbers. For example, `ir.json` is current, `ir-1.json` is the next oldest, then `ir-2.json`, etc. - -3. If something is wrong with `snapshot` or `aconf`, there is an issue with your configuration. If something is wrong with `ir` or `econf`, you should [open an issue on Github](https://github.com/emissary-ingress/emissary/issues/new/choose). - -4. The actual input provided to Envoy is split into `$AMBASSADOR_CONFIG_BASE_DIR/bootstrap-ads.json` and `$AMBASSADOR_CONFIG_BASE_DIR/envoy/envoy.json`. - - - The `bootstrap-ads.json` file contains details about Envoy statistics, logging, authentication, etc. - - The `envoy.json` file contains information about request routing. - - You may generally find it simplest to just look at the `econf.json` files in the `snapshot` - directory, which includes both kinds of configuration. diff --git a/content/en/docs/3.2/topics/running/diagnostics.md b/content/en/docs/3.2/topics/running/diagnostics.md deleted file mode 100644 index 20506304..00000000 --- a/content/en/docs/3.2/topics/running/diagnostics.md +++ /dev/null @@ -1,54 +0,0 @@ -# Diagnostics - -With $productName$ Diagnostics and Ambassador Cloud, you get a summary of the current status and Mappings of your cluster and it's services, which gets displayed -in [Diagnostics Overview](https://www.getambassador.io/docs/cloud/latest/diagnostics-ui/view-diagnostics/). - -## Troubleshooting - -### Can't access $productName$ Diagnostics Overview? - -Create an Ambassador `Module` if one does not already exist, and add the following config to enable diagnostics data. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - diagnostics: - enabled: true -``` -Next, ensure that the 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/content/en/docs/3.2/topics/running/environment.md b/content/en/docs/3.2/topics/running/environment.md deleted file mode 100644 index 807a6ba1..00000000 --- a/content/en/docs/3.2/topics/running/environment.md +++ /dev/null @@ -1,340 +0,0 @@ -# $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_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_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_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_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/content/en/docs/3.2/topics/running/gzip.md b/content/en/docs/3.2/topics/running/gzip.md deleted file mode 100644 index e3005c83..00000000 --- a/content/en/docs/3.2/topics/running/gzip.md +++ /dev/null @@ -1,55 +0,0 @@ -# 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/content/en/docs/3.2/topics/running/host-crd.md b/content/en/docs/3.2/topics/running/host-crd.md deleted file mode 100644 index cd187ebe..00000000 --- a/content/en/docs/3.2/topics/running/host-crd.md +++ /dev/null @@ -1,279 +0,0 @@ -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` - - - Remember that Listener resources are required for a functioning - $productName$ installation!
- Learn more about Listener. - - - - Remember than $productName$ does not make sure that a wildcard Host exists! If the - wildcard behavior is needed, a Host with a hostname of "*" - must be defined by the user. - - -A minimal `Host` resource, assuming no TLS configuration, would be: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: minimal-host -spec: - hostname: host.example.com -``` - -This `Host` tells $productName$ to expect to be reached at `host.example.com`, -with no TLS termination, and only associating with `Mapping`s that also set a -`hostname` that matches `host.example.com`. - -Remember that a 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/content/en/docs/3.2/topics/running/http3.md b/content/en/docs/3.2/topics/running/http3.md deleted file mode 100644 index 9aeb6cac..00000000 --- a/content/en/docs/3.2/topics/running/http3.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -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`. - - -The protocolStack elements need to be entered in the specific order of TLS, HTTP, UDP. - - -The `Listener` configured for HTTP/3 can be bound to the same address and port (`0.0.0.0:8443`) as the `Listener` that supports HTTP/2 and HTTP/1.1. This is not required, but it allows $productName$ to inject the default `alt-svc: h3=":443"; ma=86400, h3-29=":443"; ma=86400` header into the responses returned over the TCP connection with no additional configuration needed. **Most clients such as browsers require the `alt-svc` header to upgrade to HTTP/3**. - - -The current default of 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. - - -```yaml -# This is a standard Listener that leverages TCP to serve HTTP/2 and HTTP/1.1 traffic. -# It is bound to the same address and port (0.0.0.0:8443) as the UDP listener. -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: $productDeploymentName$-https-listener - namespace: $productNamespace$ -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: - namespace: - from: ALL ---- -# This is a Listener that leverages UDP and HTTP to serve HTTP/3 traffic. -# NOTE: Raw UDP traffic is not supported. UDP and HTTP must be used together. -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: $productDeploymentName$-https-listener-udp - namespace: $productNamespace$ -spec: - port: 8443 - # Order is important here. HTTP is required. - protocolStack: - - TLS - - HTTP - - UDP - securityModel: XFP - hostBinding: - namespace: - from: ALL -``` - -### Configuring the Host resource - -Because the QUIC network requires TLS, the certificate needs to be valid so the client can upgrade a connection to HTTP/3. See the [Host documentation](./host-crd.md) for more information on how to configure TLS for a `Host`. - -### Certificate verification - -Clients can only upgrade to an HTTP/3 connection with a valid certificate. If the client won’t upgrade to HTTP/3, verify that you have a valid TLS certificate and that your client can speak **TLS v1.3**. Your `Host` resource should be configured similar to the following: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: my-domain-host -spec: - hostname: your-hostname - # acme isn't required but just shown as an example of how to manage a valid TLS cert - acmeProvider: - email: your-email@example.com - authority: https://acme-v02.api.letsencrypt.org/directory - tls: - # QUIC requires TLS v1.3 version. Verify your client supports it. - min_tls_version: v1.3 - # Either protocol can be upgraded, but http/2 is recommended. - alpn_protocols: h2,http/1.1 -``` - -### External load balancers - -The two most common service types to expose traffic outside of a Kubernetes cluster are: - -- `LoadBalancer`: A load balancer controller generates and manages the cloud provider-specific external load balancer. -- `NodePort`: The platform administrator has to manually set up things like the external load balancer, firewall rules, and health checks. - -#### LoadBalancer setup - -The ideal setup would be to configure a single service of type `LoadBalancer`, but this comes with some current restrictions: -- You need version 1.24 or later of Kubernetes with the [`MixedProtocolLBService` feature enabled](https://kubernetes.io/docs/concepts/services-networking/service/#load-balancers-with-mixed-protocol-types). -- Your cloud service provider needs to support the creation of an external load balancer with mixed protocol types (TCP/UDP), port reuse, and port forwarding. Support for Kubernetes feature flags may vary between cloud service providers. Refer to your provider’s documentation to see if they support this scenario. - -An example `LoadBalancer` configuration that fits the criteria listed above: - -```yaml - -# note: extra fields such as labels and selectors removed for clarity -apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$ - namespace: $productNamespace$ -spec: - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - - name: http3 - port: 443 - targetPort: 8443 - protocol: UDP - type: LoadBalancer -``` - -## Cloud service provider setup - -Once you've completed the steps above, you need to configure HTTP/3 support through your cloud service provider. The configuration processes for each provider can be found here: - -- HTTP/3 setup for [Amazon Elastic Kubernetes Service (EKS)](../../../howtos/http3-eks) -- HTTP/3 setup for [Azure Kubernetes Service (AKS)](../../../howtos/http3-aks) -- HTTP/3 setup for [Google Kubernetes Engine (GKE)](../../../howtos/http3-gke) diff --git a/content/en/docs/3.2/topics/running/index.md b/content/en/docs/3.2/topics/running/index.md deleted file mode 100644 index c196e969..00000000 --- a/content/en/docs/3.2/topics/running/index.md +++ /dev/null @@ -1,16 +0,0 @@ -# Running $productName$ in production - -This section of the documentation is designed for operators and site reliability engineers who are managing the deployment of $productName$. Learn more below: - -* *Global Configuration:* The [Ambassador module](ambassador) is used to set system-wide configuration. -* *Exposing $productName$ to the Internet:* The [`Listener` CRD](listener) defines which ports are exposed, including their protocols and security models. The [`Host` CRD](host-crd) defines how $productName$ manages TLS, domains, and such. -* *Load Balancing:* $productName$ supports a number of different [load balancing strategies](load-balancer) as well as different ways to configure [service discovery](resolvers) -* [Gzip Compression](gzip) -* *Deploying $productName$:* On [Amazon Web Services](ambassador-with-aws) | [Google Cloud](ambassador-with-gke) | [general security and operational notes](running), including running multiple $productNamePlural$ on a cluster -* *TLS/SSL:* [Simultaneously Routing HTTP and HTTPS](tls/cleartext-redirection#cleartext-routing) | [HTTP -> HTTPS Redirection](tls/cleartext-redirection#http-https-redirection) | [Mutual TLS](tls/mtls) | [TLS origination](tls/origination) -* *Statistics and Monitoring:* [Integrating with Prometheus, DataDog, and other monitoring systems](statistics) -* *Extending $productName$* $productName$ can be extended with custom plug-ins that connect via HTTP/gRPC interfaces. [Custom Authentication](services/auth-service) | [The External Auth protocol](services/ext_authz) | [Custom Logging](services/log-service) | [Rate Limiting](services/rate-limit-service) | [Distributed Tracing](services/tracing-service) -* *Troubleshooting:* [Diagnostics](diagnostics) | [Debugging](debugging) -* *Scaling $productName$:* [Scaling $productName$](scaling) -* *Ingress:* $productName$ can function as an [Ingress Controller](ingress-controller) -* *Error Response Overrides:* $productName$ can override 4xx and 5xx responses with [custom response bodies](custom-error-responses) diff --git a/content/en/docs/3.2/topics/running/ingress-controller.md b/content/en/docs/3.2/topics/running/ingress-controller.md deleted file mode 100644 index 9b7afb82..00000000 --- a/content/en/docs/3.2/topics/running/ingress-controller.md +++ /dev/null @@ -1,325 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Ingress controller - -
-

Contents

- -- [When and how to use the Ingress resource](#when-and-how-to-use-the-ingress-resource) -- [What is required to use the Ingress resource?](#what-is-required-to-use-the-ingress-resource) -- [When to use an Ingress instead of annotations or CRDs](#when-to-use-an-ingress-instead-of-annotations-or-crds) -- [Ingress support](#ingress-support) -- [Examples of Ingress configs vs Mapping configs](#examples-of-ingress-configs-vs-mapping-configs) -- [Ingress routes and mappings](#ingress-routes-and-mappings) -- [The Minimal Ingress](#the-minimal-ingress) -- [Name based virtual hosting with an Ambassador ID](#name-based-virtual-hosting-with-an-ambassador-id) -- [TLS Termination](#tls-termination) - -
- -An Ingress resource is a popular way to expose Kubernetes services to the Internet. In order to use Ingress resources, you need to install an [ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/). $productName$ can function as a fully-fledged Ingress controller, making it easy to work with other Ingress-oriented tools within the Kubernetes ecosystem. - -## When and how to use the Ingress resource - -If you're new to $productName$ and to Kubernetes, we'd recommend you start with our [quickstart](../../../tutorials/getting-started/) instead of this Ingress guide. If you're a power user and need to integrate with other software that leverages the Ingress resource, read on. The Ingress specification is very basic and does not support many of the features of $productName$, so you'll be using both the Ingress resource and $productName$'s Mapping resource to manage your Kubernetes services. - -### What is required to use the Ingress resource? - -- Know what version of Kubernetes you are using. - - - In Kubernetes 1.13 and below, the Ingress was only included in the `extensions` API. - - - Starting in Kubernetes 1.14, the Ingress was added to the new `networking.k8s.io` API. - - - Kubernetes 1.18 introduced the IngressClass resource to the existing `networking.k8s.io/v1beta1` API. - - If you are using 1.14 and above, it is recommended to use 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. - - -- You will need RBAC permissions to create Ingress resources in either - the `extensions` `apiGroup` (present in all supported versions of - Kubernetes) or the `networking.k8s.io` `apiGroup` (introduced in - Kubernetes 1.14). - -- $productName$ will need RBAC permissions to get, list, watch, and update Ingress resources. - - You can see this in the [`aes-crds.yaml`](https://app.getambassador.io/yaml/ambassador-docs/latest/aes.yaml) - file, but this is the critical rule to add to $productName$'s `Role` or `ClusterRole`: - - ```yaml - - apiGroups: ['extensions', 'networking.k8s.io'] - resources: ['ingresses', 'ingressclasses'] - verbs: ['get', 'list', 'watch'] - - apiGroups: ['extensions', 'networking.k8s.io'] - resources: ['ingresses/status'] - verbs: ['update'] - ``` - - - This is included by default in all $productName$ installations. - - -- You must create your Ingress resource with the correct `ingress.class`. - - $productName$ will automatically read Ingress resources with the annotation - `kubernetes.io/ingress.class: ambassador`. - -- You may need to set your Ingress resource's `ambassador-id`. - - If you are [using `amabssador-id` on your Module](../running/#ambassador_id), you'll need to add the `getambassador.io/ambassador-id` - annotation to your Ingress. See the [examples below](#name-based-virtual-hosting-with-an-ambassador-id). - -- You must create a Service resource with the correct `app.kubernetes.io/component` label. - - $productName$ will automatically load balance Ingress resources using the endpoint exposed - from the Service with the annotation `app.kubernetes.io/component: ambassador-service`. - - ```yaml - --- - kind: Service - apiVersion: v1 - metadata: - name: ingress-ambassador - labels: - app.kubernetes.io/component: ambassador-service - spec: - externalTrafficPolicy: Local - type: LoadBalancer - selector: - service: ambassador - ports: - - name: http - port: 80 - targetPort: http - - name: https - port: 443 - targetPort: https - ``` - -### When to use an Ingress instead of annotations or CRDs - -We recommend that $productName$ be configured using CRDs. The Ingress resource is available to users who need it for integration with other ecosystem tools, or who feel that it more closely matches their workflows. However, it is important to recognize that the Ingress resource is rather more limited than the $productName$ Mapping is (for example, the Ingress spec has no support for rewriting or for TLS origination). **When in doubt, use CRDs.** - -## Ingress support - -$productName$ supports basic core functionality of the Ingress resource, as defined by the [Ingress resource](https://kubernetes.io/docs/concepts/services-networking/ingress/) itself: - -- Basic routing is supported, including the `route` specification and the default backend functionality. It's particularly easy to use a minimal Ingress to the $productName$ diagnostic UI. -- [TLS termination](../tls/) is supported. You can use multiple Ingress resources for SNI. -- Using the Ingress resource in concert with $productName$ CRDs or annotations is supported. This includes $productName$ annotations on the Ingress resource itself. - -$productName$ does **not** extend the basic Ingress specification with the following exceptions: - -- The `getambassador.io/ambassador-id` annotation allows you to set [the Ambassador ID](../running/#ambassador_id) for the Ingress itself. - -- The `getambassador.io/config` annotation can be provided on the Ingress resource, just as on a Service. - -Note that if you need to set `getambassador.io/ambassador-id` on the Ingress, you will also need to set `ambassador-id` on resources within the annotation. - -## Examples of Ingress configs vs Mapping configs - -### Ingress routes and Mappings - -$productName$ actually creates Mapping objects from the Ingress route rules. These Mapping objects interact with Mappings defined in CRDs **exactly** as they would if the Ingress route rules had been specified with CRDs originally. - -For example, this Ingress resource routes traffic to `/foo/` to `service1`: - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: test-ingress -spec: - rules: - - http: - paths: - - path: /foo/ - backend: - serviceName: service1 - servicePort: 80 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: test-ingress-0-0 -spec: - hostname: '*' - prefix: /foo/ - service: service1:80 -``` - -This YAML will set up $productName$ to do canary routing where 50% of the traffic will go to `service1` and 50% will go to `service2`. - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: test-ingress -spec: - rules: - - http: - paths: - - path: /foo/ - backend: - serviceName: service1 - servicePort: 80 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: my-mapping -spec: - hostname: '*' - prefix: /foo/ - service: service2 -``` - -### The minimal Ingress - -An Ingress resource must provide at least some routes or a [default backend](https://kubernetes.io/docs/concepts/services-networking/ingress/#default-backend). The default backend provides for a simple way to direct all traffic to some upstream service: - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: test-ingress -spec: - backend: - serviceName: exampleservice - servicePort: 8080 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: test-ingress -spec: - hostname: '*' - prefix: / - service: exampleservice:8080 -``` - -### Name based virtual hosting with an Ambassador ID - -This Ingress resource will result in all requests to `foo.bar.com` going to `service1`, and requests to `bar.foo.com` going to `service2`: - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - getambassador.io/ambassador-id: externalid - name: name-virtual-host-ingress -spec: - rules: - - host: foo.bar.com - http: - paths: - - backend: - serviceName: service1 - servicePort: 80 - - host: bar.foo.com - http: - paths: - - backend: - serviceName: service2 - servicePort: 80 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: host-foo-mapping -spec: - ambassador_id: ['externalid'] - prefix: / - host: foo.bar.com - service: service1 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: host-bar-mapping -spec: - ambassador_id: ['externalid'] - prefix: / - host: bar.foo.com - service: service2 -``` - -Read more on the [Kubernetes documentation on name based virtual routing](https://kubernetes.io/docs/concepts/services-networking/ingress/#name-based-virtual-hosting). - -### TLS termination - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: tls-example-ingress -spec: - tls: - - hosts: - - sslexample.foo.com - secretName: testsecret-tls - rules: - - host: sslexample.foo.com - http: - paths: - - path: / - backend: - serviceName: service1 - servicePort: 80 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: sslexample-termination-context -spec: - hosts: - - sslexample.foo.com - secret: testsecret-tls ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: sslexample-mapping -spec: - host: sslexample.foo.com - prefix: / - service: service1 -``` - -Note that this shows TLS termination, not origination: the Ingress spec does not support origination. Read more on the [Kubernetes docs on TLS termination](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls). diff --git a/content/en/docs/3.2/topics/running/listener.md b/content/en/docs/3.2/topics/running/listener.md deleted file mode 100644 index 152e1b74..00000000 --- a/content/en/docs/3.2/topics/running/listener.md +++ /dev/null @@ -1,218 +0,0 @@ -# The `Listener` CRD - -The `Listener` CRD defines where, and how, $productName$ should listen for requests from the network, and which `Host` definitions should be used to process those requests. For further examples of how to use `Listener`, see [Configuring $productName$ Communications](../../../howtos/configure-communications). - -**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. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 # int32, port number on which to listen - protocol: HTTPS # HTTP, HTTPS, HTTPPROXY, HTTPSPROXY, TCP - securityModel: XFP # XFP (for X-Forwarded-Proto), SECURE, INSECURE - statsPrefix: example-listener # default depends on protocol; see below - l7Depth: 0 # int32 - hostBinding: - namespace: - from: SELF # SELF, ALL - selector: ... # Kubernetes label selector -``` - -| Element | Type | Definition | -| :------ | :--- | :--------- | -| `port` | `int32` | The network port on which $productName$ should listen. *Required.* | -| `protocol` | `enum`; see below | A high-level protocol type, like "HTTPS". *Exactly one of `protocol` and `protocolStack` must be supplied.* | -| `protocolStack` | array of `enum`; see below | A sequence of low-level protocols to layer together. *Exactly one of `protocol` and `protocolStack` must be supplied.* | -| `securityModel` | `enum`; see below | How does $productName$ decide whether requests here are secure? *Required.* | -| `statsPrefix` | `string`; see below | Under what name do statistics for this `Listener` appear? *Optional; default depends on protocol.* | -| `l7Depth` | `int32` | How many layer 7 load balancers are between the edge of the network and $productName$? *Optional; default is 0.*| -| `hostBinding` | `struct`, see below | Mechanism for determining which `Host`s will be associated with this `Listener`. *Required* | - -### `protocol` and `protocolStack` - -`protocol` is the **recommended** way to tell $productName$ that a `Listener` expects connections using a well-known protocol. When using `protocol`, `protocolStack` may not also be supplied. - -Valid `protocol` values are: - -| `protocol` | Description | -| :--------- | :---------- | -| `HTTP` | Cleartext-only HTTP. HTTPS is not allowed. | -| `HTTPS` | Either HTTPS or HTTP -- Envoy's TLS support can tell whether or not TLS is in use, and it will set `X-Forwarded-Proto` correctly for later decision-making. | -| `HTTPPROXY` | Cleartext-only HTTP, using the HAProxy `PROXY` protocol. | -| `HTTPSPROXY` | Either HTTPS or HTTP, using the HAProxy `PROXY` protocol. | -| `TCP` | TCP sessions without HTTP at all. You will need to use `TCPMapping`s to route requests for this `Listener`. | -| `TLS` | TLS sessions without HTTP at all. You will need to use `TCPMapping`s to route requests for this `Listener`. | - -### `securityModel` - -`securityModel` defines how the `Listener` will decide whether a request is secure or insecure: - -| `securityModel` | Description | -| :--------- | :---------- | -| `XFP` | Requests are secure if, and only if, `X-Forwarded-Proto` indicates HTTPS. This is common; see below. | -| `SECURE` | Requests are always secure. You might set this if your load balancer always terminates TLS for you, and you can trust the clients. | -| `INSECURE` | Requests are always insecure. You might set this for an HTTP-only `Listener`, or a `Listener` for clients that are expected to be hostile. | - -The `X-Forwarded-Proto` header mentioned above is meant to reflect the protocol the _original client_ -used to contact $productName$. When no layer 7 proxies are in use, Envoy will make certain that the -`X-Forwarded-Proto` header matches the wire protocol of the connection the client made to Envoy, -which allows $productName$ to trust `X-Forwarded-Proto` for routing decisions such as deciding to -redirect requests made using HTTP over to HTTPS for greater security. When using $productName$ as an -edge proxy or a typical API gateway, this is a desirable configuration; setting `securityModel` to -`XFP` makes this easy. - -When layer proxies _are_ in use, the `XFP` setting is often still desirable; however, you will also -need to set `l7Depth` to allow it to function. See below. - -`SECURE` and `INSECURE` are helpful for cases where something downstream of $productName$ should be -allowing only one kind of request to reach $productName$. For example, a `Listener` behind a load -balancer that terminates TLS and checks client certificates might use -`SecurityModel: SECURE`, then use `Host`s to reject insecure requests if one somehow -arrives. - -### `l7Depth` - -When layer 7 (L7) proxies are in use, the connection to $productName$ comes from the L7 proxy itself -rather than from the client. Examining the protocol and IP address of that connection is useless, and -instead you need to configure the L7 proxy to pass extra information about the client to $productName$ -using the `X-Forwarded-Proto` and `X-Forwarded-For` headers. - -However, if $productName$ always trusted `X-Forwarded-Proto` and `X-Forwarded-For`, any client could -use them to lie about itself to $productName$. As a security mechanism, therefore, you must _also_ -set `l7Depth` in the `Listener` to the number of trusted L7 proxies in front of $productName$. If -`l7Depth` is not set in the `Listener`, the `xff_num_trusted_hops` value from the `ambassador` `Module` -will be used. If neither is set, the default `l7Depth` is 0. - -When `l7Depth` is 0, any incoming `X-Forwarded-Proto` is stripped: Envoy always provides an -`X-Forwarded-Proto` matching the wire protocol of the incoming connection, so that `X-Forwarded-Proto` -can be trusted. When `l7Depth` is non-zero, `X-Forwarded-Proto` is accepted from the L7 proxy, and -trusted. The actual wire protocol in use from the L7 proxy to $productName$ is ignored. - -`l7Depth` also affects $productName$'s view of the client's source IP address, which is used as the -`remote_address` field when rate limiting, and for the `X-Envoy-External-Address` header: - -- When `l7Depth` is 0, $productName$ uses the IP address of the incoming connection. -- When `l7Depth` is some value N that is non-zero, the behavior is determined by the value of - `use_remote_address` in the `ambassador` `Module`: - - - When `use_remote_address` is true (the default) then the trusted client address will be the Nth - address from the right end of the `X-Forwarded-For` header. (If the XFF contains fewer than N - addresses, Envoy falls back to using the immediate downstream connection’s source address as a - trusted client address.) - - - When `use_remote_address` is false, the trusted client address is the (N+1)th address from the - right end of XFF. (If the XFF contains fewer than N+1 addresses, Envoy falls back to using the - immediate downstream connection’s source address as a trusted client address.) - - For more detailed examples of this interaction, refer to [Envoy's documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers.html#x-forwarded-for). - - -### `hostBinding` - -`hostBinding` specifies how this `Listener` should determine which `Host`s are associated with it: - -- `namespace.from` allows filtering `Host`s by the namespace of the `Host`: - - `namespace.from: SELF` accepts only `Host`s in the same namespace as the `Listener`. - - `namespace.from: ALL` accepts `Host`s in any namespace. -- `selector` accepts only `Host`s that has labels matching the selector. - -`hostBinding` is mandatory, and at least one of `namespace.from` and `selector` must be set. If both are set, both must match for a `Host` to be accepted. - -### `statsPrefix` - -$productName$ produces detailed [statistics](../statistics) which can be monitored in a variety of ways. Statistics have hierarchical names, and the `Listener` will cause a set of statistics to be logged under the name specified by `statsPrefix`. - -The default `statsPrefix` depends on the protocol for this `Listener`: - -- If the `Listener` speaks HTTPS, the default is `ingress-https`. -- Otherwise, if the `Listener` speaks HTTP, the default is `ingress-http`. -- Otherwise, if the `Listener` speaks TLS, the default is `ingress-tls-$port`. -- Otherwise, the default is `ingress-$port`. - -Note that it doesn't matter whether you use `protocol` or `protocolStack`: what matters is what protocol is actually configured. Also note that the default doesn't take the HAProxy `PROXY` protocol into account. - -Some examples: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 - protocol: HTTPS - ... -``` - -will use a `statsPrefix` of `ingress-https`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 - protocol: TCP - ... -``` - -will use `statsPrefix` of `ingress-8080`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 - protocol: HTTPSPROXY - statsPrefix: proxy-8080 - ... -``` - -would also use `ingress-https`, but it explicitly overrides `statsPrefix` to `proxy-8080`. - -For complete information on which statistics will appear for the `Listener`, see [the Envoy listener statistics documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/listeners/stats.html). Some important statistics include - -| Statistic name | Type | Description | -| :-----------------------------------------------| :-------- | :-------------------------------- | -| `listener.$statsPrefix.downstream_cx_total` | Counter | Total connections | -| `listener.$statsPrefix.downstream_cx_active` | Gauge | Total active connections | -| `listener.$statsPrefix.downstream_cx_length_ms` | Histogram | Connection length in milliseconds | - -### `protocolStack` - -**`protocolStack` is not recommended if you can instead use `protocol`.** - -Where `protocol` allows configuring the `Listener` to use well-known protocol stacks, `protocolStack` allows configuring exactly which protocols will be layered together. If `protocol` allows what you need, it is safer to use `Protocol` than to risk having the stack broken with an incorrect `protocolStack`. - -The possible stack elements are: - -| `ProtocolStack` Element | Description | -| :---------------------- | :---------- | -| `HTTP` | Cleartext-only HTTP; must be layered with `TLS` for HTTPS | -| `PROXY` | The HAProxy `PROXY` protocol | -| `TLS` | TLS | -| `TCP` | Raw TCP | - -`protocolStack` supplies a list of these elements to describe the protocol stack. **Order matters.** Some examples: - -| `protocolStack` | Description | -| :-------------- | :---------- | -| [ `HTTP`, `TCP` ] | Cleartext-only HTTP, exactly equivalent to `protocol: HTTP`. | -| [ `TLS`, `HTTP`, `TCP` ] | HTTPS or HTTP, exactly equivalent to `protocol: HTTPS`. | -| [ `PROXY`, `TLS`, `TCP` ] | The `PROXY` protocol, wrapping `TLS` _afterward_, wrapping raw TCP. This isn't equivalent to any `protocol` setting, and may be nonsensical. | - -## Examples - -For further examples of how to use `Listener`, see [Configuring $productName$ to Communicate](../../../howtos/configure-communications). diff --git a/content/en/docs/3.2/topics/running/load-balancer.md b/content/en/docs/3.2/topics/running/load-balancer.md deleted file mode 100644 index 987a910b..00000000 --- a/content/en/docs/3.2/topics/running/load-balancer.md +++ /dev/null @@ -1,209 +0,0 @@ -# Load balancing - -Load balancing configuration can be set for all $productName$ mappings in the [`ambassador` `Module`](../ambassador), or set per [`Mapping`](../../using/mappings). If nothing is set, simple round robin balancing is used via Kubernetes services. - -To use advanced load balancing, you must first configure a [resolver](../resolvers) that supports advanced load balancing (e.g., the Kubernetes Endpoint Resolver or Consul Resolver). Once a resolver is configured, you can use the `load_balancer` attribute. The following fields are supported: - -```yaml -load_balancer: - policy: -``` - -Supported load balancer policies: - -- `round_robin` -- `least_request` -- `ring_hash` -- `maglev` - -For more information on the different policies and the implications, see [load balancing strategies in Kubernetes](https://blog.getambassador.io/load-balancing-strategies-in-kubernetes-l4-round-robin-l7-round-robin-ring-hash-and-more-6a5b81595d6c). - -## Round robin -When `policy` is set to `round_robin`, $productName$ discovers healthy endpoints for the given mapping, and load balances the incoming L7 requests with round robin scheduling. To specify this: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - resolver: my-resolver - load_balancer: - policy: round_robin -``` - -or, per mapping: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - resolver: my-resolver - hostname: '*' - load_balancer: - policy: round_robin -``` - -Note that load balancing may not appear to be "even" due to Envoy's threading model. For more details, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/faq/load_balancing/concurrency_lb). - -## Least request - -When `policy` is set to `least_request`, $productName$ discovers healthy endpoints for the given mapping, and load balances the incoming L7 requests to the endpoint with the fewest active requests. To specify this: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - resolver: my-resolver - load_balancer: - policy: least_request -``` - -or, per mapping: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend/ -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: least_request -``` - -## Sticky sessions / session affinity - -Configuring sticky sessions makes $productName$ route requests to a specific pod providing your service in a given session. One pod serves all requests from a given session, eliminating the need for session data to be transferred between pods. $productName$ lets you configure session affinity based on the following parameters in an incoming request: - -- Cookie -- Header -- Source IP - -**NOTE:** $productName$ supports sticky sessions using two load balancing policies, `ring_hash` and `maglev`. - -### Cookie - -```yaml -load_balancer: - policy: ring_hash - cookie: - name: - ttl: - path: -``` - -If the cookie you wish to set affinity on is already present in incoming requests, then you only need the `cookie.name` field. However, if you want $productName$ to generate and set a cookie in response to the first request, then you need to specify a value for the `cookie.ttl` field which generates a cookie with the given expiration time. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - hostname: '*' - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - cookie: - name: sticky-cookie - ttl: 60s -``` - -### Header - -```yaml -load_balancer: - policy: ring_hash - header:
-``` - -$productName$ allows header based session affinity if the given header is present on incoming requests. - -Example: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - header: STICKY_HEADER -``` - -#### Source IP - -```yaml -load_balancer: - policy: ring_hash - source_ip: -``` - -$productName$ allows session affinity based on the source IP of incoming requests. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - source_ip: true -``` - -Load balancing can be configured both globally, and overridden on a per mapping basis. The following example configures the default load balancing policy to be round robin, while using header-based session affinity for requests to the `/backend/` endpoint of the quote application: - -Load balancing can be configured both globally, and overridden on a per mapping basis. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - resolver: my-resolver - load_balancer: - policy: round_robin -``` - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - header: STICKY_HEADER -``` diff --git a/content/en/docs/3.2/topics/running/resolvers.md b/content/en/docs/3.2/topics/running/resolvers.md deleted file mode 100644 index 1ace9a86..00000000 --- a/content/en/docs/3.2/topics/running/resolvers.md +++ /dev/null @@ -1,128 +0,0 @@ -# Service discovery and resolvers - -Service discovery is how cloud applications and their microservices are located on the network. In a cloud environment, services are ephemeral, existing only as long as they are needed and in use, so a real-time service discovery mechanism is required. $productName$ uses information from service discovery to determine where to route incoming requests. - -## $productName$ support for service discovery - -$productName$ supports different mechanisms for service discovery. These mechanisms are: - -* Kubernetes service-level discovery (default). -* Kubernetes endpoint-level discovery. -* Consul endpoint-level discovery. - -### Kubernetes service-level discovery - -By default, $productName$ uses Kubernetes DNS and service-level discovery. In a `Mapping` resource, specifying `service: foo` will prompt $productName$ to look up the DNS address of the `foo` Kubernetes service. Traffic will be routed to the `foo` service. Kubernetes will then load balance that traffic between multiple pods. For more details on Kubernetes networking and how this works, see our blog post on [Session affinity, load balancing controls, gRPC-Web, and $productName$](https://blog.getambassador.io/session-affinity-load-balancing-controls-grpc-web-and-ambassador-0-52-2b916b396d0c). - -### Kubernetes endpoint-level discovery - -$productName$ can also watch Kubernetes endpoints. This bypasses the Kubernetes service routing layer and enables the use of advanced load balancing controls such as session affinity and maglev. For more details, see the [load balancing reference](../load-balancer). - -### Consul endpoint-level discovery - -$productName$ natively integrates with [Consul](https://www.consul.io) for endpoint-level service discovery. In this mode, $productName$ obtains endpoint information from Consul. One of the primary use cases for this architecture is in hybrid cloud environments that run a mixture of Kubernetes services as well as VMs, as Consul can serve as the single global registry for all services. - -## The Resolver resource - -The `Resolver` resource is used to configure the discovery service strategy for $productName$. - -### The Kubernetes service resolver - -The Kubernetes Service Resolver configures $productName$ to use Kubernetes services. If no resolver is specified, this behavior is the default. When this resolver is used, the `service.namespace` value from a `Mapping` is handed to the Kubernetes cluster's DNS resolver to determine where requests are sent. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: KubernetesServiceResolver -metadata: - name: kubernetes-service -``` - -### The Kubernetes endpoint resolver - -The Kubernetes Endpoint Resolver configures $productName$ to resolve Kubernetes endpoints. This enables the use of more a [advanced load balancing configuration](../load-balancer). When this resolver is used, the endpoints for the `service` defined in a `Mapping` are resolved and used to determine where requests are sent. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: KubernetesEndpointResolver -metadata: - name: endpoint -``` - -### The Consul resolver - -The Consul Resolver configures $productName$ to use Consul for service discovery. When this resolver is used, the `service` defined in a `Mapping` is passed to Consul, along with the datacenter specified, to determine where requests are sent. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: ConsulResolver -metadata: - name: consul-dc1 -spec: - address: consul-server.default.svc.cluster.local:8500 - datacenter: dc1 -``` -- `address`: The fully-qualified domain name or IP address of your Consul server. This field also supports environment variable substitution. -- `datacenter`: The Consul data center where your services are registered - -You may want to use an environment variable if you're running a Consul agent on each node in your cluster. In this setup, you could do the following: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: ConsulResolver -metadata: - name: consul-dc1 -spec: - address: "${HOST_IP}" - datacenter: dc1 -``` - -and then add the `HOST_IP` environment variable to your Kubernetes deployment: - -```yaml -containers: - - name: example - image: docker.io/datawire/ambassador:$version$ - env: - - name: HOST_IP - valueFrom: - fieldRef: - fieldPath: status.hostIP -``` - -## Using resolvers - -Once a resolver is defined, you can use them in a given `Mapping`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: "*" - prefix: /backend/ - service: quote - resolver: endpoint - load_balancer: - policy: round_robin ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: bar -spec: - hostname: "*" - prefix: /bar/ - service: https://bar:9000 - tls: client-context - resolver: consul-dc1 - load_balancer: - policy: round_robin -``` - -The YAML configuration above will configure $productName$ to use Kubernetes Service Discovery to route to the Consul Service Discovery to route to the `bar` service on requests with `prefix: /bar/`. diff --git a/content/en/docs/3.2/topics/running/running.md b/content/en/docs/3.2/topics/running/running.md deleted file mode 100644 index a28b0cb5..00000000 --- a/content/en/docs/3.2/topics/running/running.md +++ /dev/null @@ -1,338 +0,0 @@ -# Running and deployment - -This section is intended for operators running $productName$, and covers various aspects of deploying and configuring the $productName$ in production. - -## $productName$ and Kubernetes - -$productName$ relies on Kubernetes for reliability, availability, and scalability. This means that features such as Kubernetes readiness and liveness probes, rolling updates, and the Horizontal Pod Autoscaling should be utilized to manage $productName$. - -## Default configuration - -The default configuration of $productName$ includes default [resource limits](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-requests-and-limits-of-pod-and-container), as well as [readiness and liveness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/). These values should be adjusted for your specific environment. - -## Running as non-root - -Starting with $productName$ 0.35, we support running $productName$ as non-root. This is the recommended configuration, and will be the default configuration in future releases. We recommend you configure $productName$ to run as non-root as follows: - -* Have Kubernetes run $productName$ as non-root. This may happen by default (e.g., OpenShift) or you can set a `securityContext` in your Deployment as shown below in this abbreviated example: - -```yaml ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: ambassador -spec: - replicas: 1 - selector: - matchLabels: - service: ambassador - template: - metadata: - labels: - service: ambassador - spec: - containers: - image: docker.io/datawire/aes:$version$ - name: ambassador - restartPolicy: Always - securityContext: - runAsUser: 8888 - serviceAccountName: ambassador -``` - -* Set the `service_port` element in the `ambassador Module` to 8080 (cleartext) or 8443 (TLS). This is the port that $productName$ will use to listen to incoming traffic. Note that any port number above 1024 will work; $productName$ will use 8080/8443 as its defaults in the future. - -* Make sure that incoming traffic to $productName$ is configured to route to the `service_port`. If you're using the default $productName$ configuration, this means configuring the `targetPort` to point to the `service_port` above. - -* If you are using `redirect_cleartext_from`, change the value of this field to point to your cleartext port (e.g., 8080) and set `service_port` to be your TLS port (e.g., 8443). - -## Changing the configuration directory - -While running, $productName$ needs to use a directory within its container for generated configuration data. Normally this is `/ambassador`, but in some situations - especially if running as non-root - it may be necessary to change to a different directory. To do so, set the environment variable `AMBASSADOR_CONFIG_BASE_DIR` to the full pathname of the directory to use, as shown below in this abbreviated example: - -```yaml -env: -- name: AMBASSADOR_CONFIG_BASE_DIR - value: /tmp/ambassador-config -``` - -With `AMBASSADOR_CONFIG_BASE_DIR` set as above, $productName$ will create and use the directory `/tmp/ambassador-config` for its generated data. (Note that, while the directory will be created if it does not exist, attempts to turn an existing file into a directory will fail.) - -## Running as DaemonSet - -$productName$ can be deployed as a DaemonSet to have one pod per node in a Kubernetes cluster. This setup is especially helpful when you have a Kubernetes cluster running on a private cloud. - -* In an ideal example scenario, you are running containers on Kubernetes alongside with your non-containerized applications running exposed via VIP using BIG-IP or similar products. In such cases, east-west traffic is routed based on iRules to certain a set of application pools consisting of application or web servers. In this setup, alongside traditional application servers, two or more $productName$ pods can also be part of the application pools. In case of failure there is at least one $productName$ pod available to BIG-IP that can take care of routing traffic to the Kubernetes cluster. - -* In manifest files `kind: Deployment` needs to be updated to `kind: DaemonSet` and `replicas` should be removed in `spec` section. - -## Namespaces - -$productName$ supports multiple namespaces within Kubernetes. To make this work correctly, you need to set the `AMBASSADOR_NAMESPACE` environment variable in $productName$'s container. By far the easiest way to do this is using Kubernetes' downward API (this is included in the YAML files from `getambassador.io`): - -```yaml -env: -- name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace -``` - -Given that `AMBASSADOR_NAMESPACE` is set, $productName$ [`Mappings`](../../using/mappings) can operate within the same namespace, or across namespaces. **Note well** that `Mappings` will have to explicitly include the namespace with the service to cross namespaces; see the [`Mapping`](../../using/mappings) documentation for more information. - -If you want $productName$ to only work within a single namespace, set `AMBASSADOR_SINGLE_NAMESPACE` as an environment variable. - -```yaml -env: -- name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace -- name: AMBASSADOR_SINGLE_NAMESPACE - value: "true" -``` - -With $productName$, if you set `AMBASSADOR_NAMESPACE` or `AMBASSADOR_SINGLE_NAMESPACE`, set it in the deployment container. - -If you want to set a certificate for your `TLScontext` from another namespace, you can use the following: - -```yaml -env: -- name: AMBASSADOR_SINGLE_NAMESPACE - value: "YES" -- name: AMBASSADOR_CERTS_SINGLE_NAMESPACE - value: "YES" -- name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - apiVersion: v1 - fieldPath: metadata.namespace -``` - -## `AMBASSADOR_ID` - -$productName$ supports running multiple $productNamePlural$ in the same cluster, without restricting a given $productName$ to a single namespace. This is done with the `AMBASSADOR_ID` setting. In the `ambassador Module`, set the `ambassador_id`, e.g., - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - ambassador_id: [ "ambassador-1" ] - config: - ... -``` - -Then, assign each $productName$ pod a unique `AMBASSADOR_ID` with the environment variable as part of your deployment: - -```yaml -env: -- name: AMBASSADOR_ID - value: ambassador-1 -``` - -With $productName$, if you set `AMBASSADOR_ID`, you will need to set it in the deployment container. - -$productName$ will then only use YAML objects that include an appropriate `ambassador_id` attribute. For example, if $productName$ is given the ID `ambassador-1` as above, only the first two YAML objects below will be used: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-used -spec: - ambassador_id: [ "ambassador-1" ] - prefix: /demo1/ - service: demo1 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-used-2 -spec: - ambassador_id: [ "ambassador-1", "ambassador-2" ] - prefix: /demo2/ - service: demo2 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-skipped -spec: - prefix: /demo3/ - service: demo3 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-skipped-2 -spec: - ambassador_id: [ "ambassador-2" ] - prefix: /demo4/ - service: demo4 -``` - -`ambassador_id` is always a list, and may (as shown in `mapping-used-2` above) include multiple IDs to allow a given object in the configuration for multiple $productName$ instances. In this case, `mapping-used-2` will be included in the configuration for `ambassador-1` and also for `ambassador-2`. - -**Note well that _any_ $productName$ configuration resource can have an `ambassador_id` included** so, for example, it is _fully supported_ to use `ambassador_id` to qualify the `ambassador Module`, `TLSContext`, and `AuthService` objects. You will need to set `ambassador_id` in all resources you want to use for $productName$. - -If no `AMBASSADOR_ID` is assigned to an $productName$, it will use the ID `default`. If no `ambassador_id` is present in a YAML object, it will also use the ID `default`. - -## `AMBASSADOR_ENVOY_BASE_ID` - -$productName$ supports running side-by-side with other envoy-based projects in a single pod. An example of this is running with an `istio` sidecar. This is done with the `AMBASSADOR_ENVOY_BASE_ID` environment variable as part of your deployment: - -```yaml -env: -- name: AMBASSADOR_ENVOY_BASE_ID - value: 1 -``` - -If no `AMBASSADOR_ENVOY_BASE_ID` is provided then it will use the ID `0`. For more information on the Envoy base-id option please see the [Envoy command line documentation](https://www.envoyproxy.io/docs/envoy/latest/operations/cli.html?highlight=base%20id#cmdoption-base-id). - -## `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. - -## `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. - -## `AMBASSADOR_LEGACY_MODE` - -Setting `AMBASSADOR_LEGACY_MODE` to `true` will result in $productName$ disabling certain features -and reverting to older codepaths which may be better preserve certain older behaviors. Legacy mode -currently has the following effects: - -- $productName$ will switch back to the $productName$ 1.6 input-resource validator (which can significantly -increase configuration latency for $productName$ installations with many resources). -- $productName$ will use the shell boot sequence that was the default up through 1.9.1, rather than the Golang boot sequence that became the default in 1.10.0. -- `AMBASSADOR_FAST_RECONFIGURE` (see below) is not supported in legacy mode. - -## `AMBASSADOR_FAST_RECONFIGURE` - -Setting `AMBASSADOR_FAST_RECONFIGURE` to "true" enables incremental reconfiguration. When enabled, $productName$ will track deltas from one configuration to the next and recalculate only what is necessary to follow the change. When disabled (the default), $productName$ will recompute the entire configuration at every change. - -**`AMBASSADOR_FAST_RECONFIGURE` is not supported when `AMBASSADOR_LEGACY_MODE` is active.** - -## Configuration from the filesystem - -If desired, $productName$ can be configured from YAML files in the directory `$AMBASSADOR_CONFIG_BASE_DIR/ambassador-config` (by default, `/ambassador/ambassador-config`, which is empty in the images built by Datawire). You could volume mount an external configuration directory here, for example, or use a custom Dockerfile to build configuration directly into a Docker image. - -Note well that while $productName$ will read its initial configuration from this directory, configuration loaded from Kubernetes annotations will _replace_ this initial configuration. If this is not what you want, you will need to set the environment variable `AMBASSADOR_NO_KUBEWATCH` so that $productName$ will not try to update its configuration from Kubernetes resources. - -Also note that the YAML files in the configuration directory must contain the $productName$ resources, not Kubernetes resources with annotations. - -## Log levels and debugging - -The $OSSproductName$ and $AESproductName$ support more verbose debugging levels. If using $OSSproductName$, the [diagnostics](../diagnostics) service has a button to enable debug logging. Be aware that if you're running $productName$ on multiple pods, the debug log levels are not enabled for all pods -- they are configured on a per-pod basis. - -If using $AESproductName$, you can 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 format - -By default, $productName$ writes its own logs in a plain text format. To produce logs as JSON instead, set the `AMBASSADOR_JSON_LOGGING` environment variable: - -```yaml -env: -- name: AMBASSADOR_JSON_LOGGING - value: "true" -``` - -## Port assignments - -$productName$ uses some TCP ports in the range 8000-8499 internally, as well as port 8877. Third-party software integrating with $productName$ should not use ports in this range on the $productName$ pod. - -## $productName$ update checks (Scout) - -$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 $productName$ will run regardless of the status of Scout (i.e., our uptime has zero impact on your uptime.) - -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. - -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. - -Unless disabled, $productName$ will also report the following anonymized information back to Datawire: - -| Attribute | Type | Description | -| :------------------------ | :---- | :------------------------ | -| `cluster_count` | int | total count of clusters in use | -| `cluster_grpc_count` | int | count of clusters using GRPC upstream | -| `cluster_http_count` | int | count of clusters using HTTP or HTTPS upstream | -| `cluster_routing_envoy_rh_count` | int | count of clusters routing using Envoy `ring_hash` | -| `cluster_routing_envoy_maglev_count` | int | count of clusters routing using Envoy `maglev` | -| `cluster_routing_envoy_lr_count` | int | count of clusters routing using Envoy `least_request` | -| `cluster_routing_envoy_rr_count` | int | count of clusters routing using Envoy `round_robin` | -| `cluster_routing_kube_count` | int | count of clusters routing using Kubernetes | -| `cluster_tls_count` | int | count of clusters originating TLS | -| `custom_ambassador_id` | bool | has the `ambassador_id` been changed from 'default'? | -| `custom_listener_port` | bool | has the listener port been changed from 80/443? | -| `diagnostics` | bool | is the diagnostics service enabled? | -| `endpoint_grpc_count` | int | count of endpoints to which $productName$ will originate GRPC | -| `endpoint_http_count` | int | count of endpoints to which $productName$ will originate HTTP or HTTPS | -| `endpoint_routing` | bool | is endpoint routing enabled? | -| `endpoint_routing_envoy_rh_count` | int | count of endpoints being routed using Envoy `ring_hash` | -| `endpoint_routing_envoy_maglev_count` | int | count of endpoints being routed using Envoy `maglev` | -| `endpoint_routing_envoy_lr_count` | int | count of endpoints being routed using Envoy `least_request` | -| `endpoint_routing_envoy_rr_count` | int | count of endpoints being routed using Envoy `round_robin` | -| `endpoint_routing_kube_count` | int | count of endpoints being routed using Kubernetes | -| `endpoint_tls_count` | int | count of endpoints to which $productName$ will originate TLS | -| `extauth` | bool | is extauth enabled? | -| `extauth_allow_body` | bool | will $productName$ send the body to extauth? | -| `extauth_host_count` | int | count of extauth hosts in use | -| `extauth_proto` | str | extauth protocol in use ('http', 'grpc', or `null` if not active) | -| `group_canary_count` | int | count of Mapping groups that include more than one Mapping | -| `group_count` | int | total count of Mapping groups in use (length of the route table) | -| `group_header_match_count` | int | count of groups using header matching (including `host` and `method`) | -| `group_host_redirect_count` | int | count of groups using host_redirect | -| `group_host_rewrite_count` | int | count of groups using host_rewrite | -| `group_http_count` | int | count of HTTP Mapping groups | -| `group_precedence_count` | int | count of groups that explicitly set the precedence of the group | -| `group_regex_header_count` | int | count of groups using regex header matching | -| `group_regex_prefix_count` | int | count of groups using regex prefix matching | -| `group_resolver_consul` | int | count of groups using the Consul resolver | -| `group_resolver_kube_endpoint` | int | count of groups using the Kubernetes endpoint resolver | -| `group_resolver_kube_service` | int | count of groups using the Kubernetes service resolver | -| `group_shadow_count` | int | count of groups using shadows | -| `group_shadow_weighted_count` | int | count of groups using shadows but not shadowing all traffic | -| `group_tcp_count` | int | count of TCP Mapping groups | -| `host_count` | int | count of Host resources in use | -| `k8s_ingress_class_count` | int | count of IngressClass resources in use | -| `k8s_ingress_count` | int | count of Ingress resources in use | -| `listener_count` | int | count of active listeners (1 unless `redirect_cleartext_from` or TCP Mappings are in use) | -| `liveness_probe` | bool | are liveness probes enabled? | -| `managed_by` | string | tool that manages the $productName$ deployment, if any (e.g. helm, edgectl, etc.) | -| `mapping_count` | int | count of Mapping resources in use | -| `ratelimit` | bool | is rate limiting in use? | -| `ratelimit_custom_domain` | bool | has the rate limiting domain been changed from 'ambassador'? | -| `ratelimit_data_plane_proto` | bool | is rate limiting using the data plane proto? | -| `readiness_probe` | bool | are readiness probes enabled? | -| `request_4xx_count` | int | lower bound for how many requests have gotten a 4xx response | -| `request_5xx_count` | int | lower bound for how many requests have gotten a 5xx response | -| `request_bad_count` | int | lower bound for how many requests have failed (either 4xx or 5xx) | -| `request_elapsed` | float | seconds over which the request_ counts are valid | -| `request_hr_elapsed` | string | human-readable version of `request_elapsed` (e.g. "3 hours 35 minutes 20 seconds" | -| `request_ok_count` | int | lower bound for how many requests have succeeded (not a 4xx or 5xx) | -| `request_total_count` | int | lower bound for how many requests were handled in total | -| `statsd` | bool | is StatsD enabled? | -| `server_name` | bool | is the `server_name` response header overridden? | -| `service_resource_total` | int | total count of service resources loaded from all discovery sources | -| `tls_origination_count` | int | count of TLS origination contexts | -| `tls_termination_count` | int | count of TLS termination contexts | -| `tls_using_contexts` | bool | are new TLSContext resources in use? ? | -| `tls_using_module` | bool |is the old TLS module in use | -| `tracing` | bool | is tracing in use? | -| `tracing_driver` | str | tracing driver in use ('zipkin', 'lightstep', 'datadog', or `null` if not active) | -| `use_proxy_proto` | bool | is the `PROXY` protocol in use? | -| `use_remote_address` | bool | is $productName$ honoring remote addresses? | -| `x_forwarded_proto_redirect` | bool | is $productName$ redirecting based on `X-Forwarded-Proto`? | -| `xff_num_trusted_hops` | int | what is the count of trusted hops for `X-Forwarded-For`? | - -The `request_*` counts are always incremental: they contain only information about the last `request_elapsed` seconds. Additionally, they only provide a lower bound -- notably, if an $productName$ pod crashes or exits, no effort is made to ship out a final update, so it's very easy for counts to never be reported. - -To completely disable feature reporting, set the environment variable `AMBASSADOR_DISABLE_FEATURES` to any non-empty value. diff --git a/content/en/docs/3.2/topics/running/scaling.md b/content/en/docs/3.2/topics/running/scaling.md deleted file mode 100644 index 22fa743e..00000000 --- a/content/en/docs/3.2/topics/running/scaling.md +++ /dev/null @@ -1,194 +0,0 @@ -# Performance and scaling $productName$ - -Scaling any cloud native application is inherently domain specific, however the content here -reflects common issues, tips, and tricks that come up frequently. - -## Performance dimensions - -The performance of $productName$'s control plane can be characterized along a number of -different dimensions: - - - The number of `TLSContext` resources. - - The number of `Host` resources. - - The number of `Mapping` resources per `Host` resource. - - The number of `Mapping` resources that will span all `Host` resources (either because they're using `host_regex`, or because they're using `hostname: "*"`). - -If your application involves a larger than average number of any of the above resources, you may -find yourself in need of some of the content in this section. - -## Mysterious pod restarts (aka pushing the edge of the envelope) - -Whether your application is growing organically or whether you are deliberately scale testing, it's -helpful to recognize how $productName$ behaves as it reaches the edge of its performance -envelope along any of these dimensions. - -As $productName$ approaches the edge of its performance envelope, it will often manifest as -mysterious pod restarts triggered by Kubernetes. This does not always mean there is a problem, it -could just mean you need to tune some of the resource limits set in your deployment. When it comes -to scaling, Kubernetes will generally kill an $productName$ pod for one of two reasons: exceeding -memory limits or failed liveness/readiness probes. See the [Memory Limits](#memory-limits), -[Liveness Probes](#liveness-probes), and [Readiness Probes](#readiness-probes) -sections for more on how to cope with these situations. - -## Memory limits - -$productName$ can grow in memory usage and be killed by Kubernetes if it exceeds the limits -defined in its pod spec. When this happens it is confusing and difficult to catch because the only -indication that this has occurred is the pod transitioning momentarily into the `OOMKilled` -state. The only way to actually observe this is if you are lucky enough to be running the following -command (or have similar monitoring configured) when $productName$ gets `OOMKilled`: - -``` - kubectl get pods -n ambassador -w -``` - -In order to take the luck out of the equation, $productName$ will periodically log its -memory usage so you can see in the logs if memory limits might be a problem and require adjustment: - -``` -2020/11/26 22:35:20 Memory Usage 0.56Gi (28%) - PID 1, 0.22Gi: busyambassador entrypoint - PID 14, 0.04Gi: /usr/bin/python /usr/bin/diagd /ambassador/snapshots /ambassador/bootstrap-ads.json /ambassador/envoy/envoy.json --notices /ambassador/notices.json --port 8004 --kick kill -HUP 1 - PID 16, 0.12Gi: /ambassador/sidecars/amb-sidecar - PID 37, 0.07Gi: /usr/bin/python /usr/bin/diagd /ambassador/snapshots /ambassador/bootstrap-ads.json /ambassador/envoy/envoy.json --notices /ambassador/notices.json --port 8004 --kick kill -HUP 1 - PID 48, 0.08Gi: envoy -c /ambassador/bootstrap-ads.json --base-id 0 --drain-time-s 600 -l error -``` - -In general you should try to keep $productName$'s memory usage below 50% of the pod's limit. This may -seem like a generous safety margin, but when reconfiguration occurs, $productName$ requires additional -memory to avoid disrupting active connections. At each reconfiguration, $productName$ keeps around the -old version for the duration of the configured drain time. See -[AMBASSADOR_DRAIN_TIME](#ambassador_drain_time) for more details on how to tune this -behavior. - -$productName$'s exact memory usage depends on (among other things) how many `Host` and -`Mapping` resources are defined in your cluster. If this number has grown over time, you may need to -increase the memory limit defined in your deployment. - -## Liveness probes - -$productName$ defines the `/ambassador/v0/check_alive` endpoint on port `8877` for use with Kubernetes -liveness probes. See the Kubernetes documentation for more details on [HTTP liveness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-a-liveness-http-request). - -Kubernetes will restart the $productName$ pod if it fails to get a 200 result from the endpoint. If -this happens it won't necessarily show up in an easily recognizable way in the pod logs. You can -look for Kubernetes events to see if this is happening. Use `kubectl describe pod -n ambassador` or -`kubectl get events -n ambassador` or equivalent. - -The purpose of liveness probes is to rescue an $productName$ instance that is wedged, however if -liveness probes are too sensitive they can take out $productName$ instances that are functioning -normally. This is more prone to happen as the number of $productName$ inputs increase. The -`timeoutSeconds` and `failureThreshold` fields of the $productName$ deployment's liveness Probe -determines how tolerant Kubernetes is with its probes. If you observe pod restarts along with -`Unhealthy` events, try tuning these fields upwards from their default values. See the Kubernetes documentation for more details on [tuning probes](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#probe-v1-core). - -Note that whatever changes you make to $productName$'s liveness probes should most likely be made to -its readiness probes also. - -## Readiness probes - -$productName$ defines the `/ambassador/v0/check_ready` endpoint on port `8877` for use with Kubernetes -readiness probes. See the Kubernetes documentation for more details on [readiness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-readiness-probes). - -Kubernetes uses readiness checks to prevent traffic from going to pods that are not ready to handle -requests. The only time $productName$ cannot usefully handle requests is during initial startup when it -has not yet loaded all the routing information from Kubernetes and/or consul. During this bootstrap -period there is no guarantee $productName$ would know where to send a given request. The `check_ready` -endpoint will only return 200 when all routing information has been loaded. After the initial -bootstrap period it behaves identically to the `check_alive` endpoint. - -Generally $productName$'s readiness probes should be configured with the same settings as its liveness -probes. - -## `AMBASSADOR_FAST_RECONFIGURE` and `AMBASSADOR_LEGACY_MODE` flags - -`AMBASSADOR_FAST_RECONFIGURE` is a feature flag that enables a higher performance implementation of -the code $productName$ uses to validate and generate envoy configuration. It will eventually be enabled -by default, but if you are experiencing performance problems you should try setting -`AMBASSADOR_FAST_RECONFIGURE` to `true` to see if this helps. - -`AMBASSADOR_LEGACY_MODE` is **not** recommended when performance is critical. - -## `AMBASSADOR_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. - -## Unconstrained Mappings with many hosts - -When working with a large number of `Host` resources, it's important to understand the impact of -unconstrained `Mapping`s. An unconstrained `Mapping` is one that is not restricted to a specific -`Host`. Such a `Mapping` will create a route for all of your `Host`s. If this is what you want then -it is the appropriate thing to do, however if you do not intend to do this, then you can end up with -many more routes than you had intended and this can adversely impact performance. - -## Inspecting $productName$ performance - -$productName$ internally tracks a number of key performance indicators. You can inspect these via the -debug endpoint at `localhost:8877/debug`. Note that the `AMBASSADOR_FAST_RECONFIGURE` flag needs to -be set to `"true"` for this endpoint to be present: - -``` -$ kubectl exec -n ambassador -it ${POD} curl localhost:8877/debug -{ - "timers": { - # These two timers track how long it takes to respond to liveness and readiness probes. - "check_alive": "7, 45.411495ms/61.85999ms/81.358927ms", - "check_ready": "7, 49.951304ms/61.976205ms/86.279038ms", - - # These two timers track how long we spend updating our in-memory snapshot when our Kubernetes - # watches tell us something has changed. - "consulUpdate": "0, 0s/0s/0s", - "katesUpdate": "3382, 28.662µs/102.784µs/95.220222ms", - - # These timers tell us how long we spend notifying the sidecars if changed input. This - # includes how long the sidecars take to process that input. - "notifyWebhook:diagd": "2, 1.206967947s/1.3298432s/1.452718454s", - "notifyWebhooks": "2, 1.207007216s/1.329901037s/1.452794859s", - - # This timer tells us how long we spend parsing annotations. - "parseAnnotations": "2, 21.944µs/22.541µs/23.138µs", - - # This timer tells us how long we spend reconciling changes to consul inputs. - "reconcileConsul": "2, 50.104µs/55.499µs/60.894µs", - - # This timer tells us how long we spend reconciling secrets related changes to $productName$ - # inputs. - "reconcileSecrets": "2, 18.704µs/20.786µs/22.868µs" - }, - "values": { - "envoyReconfigs": { - "times": [ - "2020-11-06T13:13:24.218707995-05:00", - "2020-11-06T13:13:27.185754494-05:00", - "2020-11-06T13:13:28.612279777-05:00" - ], - "staleCount": 2, - "staleMax": 0, - "synced": true - }, - "memory": "39.73Gi of Unlimited (0%)" - } -} -``` - -## Running profiles - -$productName$ exposes endpoints at `localhost:8877/debug/pprof` to run Golang profiles to aid in live debugging. The endpoints are equivalent to those found in the [http/pprof](https://pkg.go.dev/net/http/pprof) package. `/debug/pprof/` returns an HTML page listing the available profiles. - -The following are the different types of profiles you can run: - -| Profile | Function | -| :------- | :-------- | -| /debug/pprof/allocs | Returns a sampling of all past memory allocations. | -| /debug/pprof/block | Returns stack traces of goroutines that led to blocking on sychronization primitives. | -| /debug/pprof/cmdline | Returns the command line that was invoked by the current program. | -| /debug/pprof/goroutine | Returns stack traces of all current goroutines. | -| /debug/pprof/heap | Returns a sampling of memory allocations of live objects. | -| /debug/pprof/mutex | Returns stack traces of goroutines holding contended mutexes. | -| /debug/pprof/profile | Returns pprof-formatted cpu profile. You can specify the duration using the seconds `GET` parameter. The default duration is 30 seconds. | -| /debug/pprof/symbol | Returns the program counters listed in the request. | -| /debug/pprof/threadcreate | Returns stack traces that led to creation of new OS threads. | -| /debug/pprof/trace | Returns the execution trace in binary form. You can specify the duration using the seconds `GET` parameter. The default duration is 1 second. | diff --git a/content/en/docs/3.2/topics/running/services/auth-service.md b/content/en/docs/3.2/topics/running/services/auth-service.md deleted file mode 100644 index cb598161..00000000 --- a/content/en/docs/3.2/topics/running/services/auth-service.md +++ /dev/null @@ -1,150 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Authentication service - -$productName$ provides a highly flexible mechanism for authentication, -via the `AuthService` resource. An `AuthService` configures -$productName$ to use an external service to check authentication and -authorization for incoming requests. Each incoming request is -authenticated before routing to its destination. - -All requests are validated by the `AuthService` (unless the `Mapping` -applied to the request sets `bypass_auth`). It is not possible to -combine multiple `AuthServices`. While it is possible to create -multiple `AuthService` resources, $productName$ load-balances between -them in a round-robin fashion. This is useful for canarying an -`AuthService` change, but is not useful for deploying multiple -distinct `AuthServices`. In order to combine multiple external -services (either having multiple services apply to the same request, -or selecting between different services for the different requests), -instead of using an `AuthService`, use an [$AESproductName$ `External` -`Filter`](/docs/edge-stack/latest/topics/using/filters/). - - - -Because of the limitations described above, **$AESproductName$ does -not support `AuthService` resources, and you should instead use an -[`External` -`Filter`](/docs/edge-stack/latest/topics/using/filters/external),** -which is mostly a drop-in replacement for an `AuthService`. The -`External` `Filter` relies on the $AESproductName$ `AuthService`. -Make sure the $AESproductName$ `AuthService` is deployed before -configuring `External` `Filters`. - - - -The currently supported version of the `AuthService` resource is -`getambassador.io/v3alpha1`. Earlier versions are deprecated. - -## Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: AuthService -metadata: - name: authentication -spec: - ambassador_id: [ "ambassador-1" ] - auth_service: "example-auth.authentication:3000" - tls: true - proto: http - timeout_ms: 5000 - include_body: - max_bytes: 4096 - allow_partial: true - status_on_error: - code: 403 - failure_mode_allow: false - - # proto: grpc only, default is v2. If upgrading from 2.x then you must set this to v3. - protocol_version: v3 - - # proto: http only - path_prefix: "/path" - allowed_request_headers: - - "x-example-header" - allowed_authorization_headers: - - "x-qotm-session" - add_auth_headers: - x-added-auth: auth-added - add_linkerd_headers: false -``` - -## Fields - -`auth_service` is the only required field, all others are optional. - -| Attribute | Default value | Description | -| ---------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `ambassador_id` | `[ "default" ]` | Which [Ambassador ID](../../running/#ambassador_id) the `AuthService` should apply to. | -| `auth_service` | (none; a value is required) | Identifies the external auth service to talk to. The format of this field is `scheme://host:port` where `scheme://` and `:port` are optional. The scheme-part, if present, must be either `http://` or `https://`; if the scheme-part is not present, it behaves as if `http://` is given. The scheme-part controls whether TLS or plaintext is used and influences the default value of the port-part. The host-part must be the [namespace-qualified DNS name](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#namespaces-of-services) of the service you want to use for authentication. | -| `tls` | `""` | This field is populated with the name of the defined TLSContext, which determines the TLS certificate presented to external auth services. | -| `proto` | `http` | Specifies which variant of the [`ext_authz` protocol](../ext_authz/) to use when communicating with the external auth service. Valid options are `http` or `grpc`. | -| `timeout_ms` | `5000` | The total maximum duration in milliseconds for the request to the external auth service, before triggering `status_on_error` or `failure_mode_allow`. | -| `include_body` | `null` | Controls how much to buffer the request body to pass to the external auth service, for use cases such as computing an HMAC or request signature. If `include_body` is `null` or unset, then the request body is not buffered at all, and an empty body is passed to the external auth service. If `include_body` is not `null`, the `max_bytes` and `allow_partial` subfields are required. | -| `include_body.max_bytes` | (none; a value is required if `include_body` is not `null`) | Controls the amount of body data that is passed to the external auth service. | -| `include_body.allow_partial` | (none; a value is required if `include_body` is not `null`) | Controls what happens to requests with bodies larger than `max_bytes`. If `allow_partial` is `true`, the first `max_bytes` of the body are sent to the external auth service. If `false`, the message is rejected with HTTP 413 ("Payload Too Large"). | -| `status_on_error.code` | `403` | Controls the status code returned when unable to communicate with external auth service. This is ignored if `failure_mode_allow: true`. | -| `failure_mode_allow` | `false` | Controls whether to allow or reject requests when there is an error communicating with the external auth service; a value of `true` allows the request through to the upstream backend service, a value of `false` returns a `status_on_error.code` response to the client. | -| `stats_name` | the `auth_service` value with non-alphanumeric characters replaced with underscores | See [Overriding Statistics Names](../../statistics/#overriding-statistics-names). | -| `circuit_breakers` | the value set in the [`ambassador` `Module`](../../../using/defaults) | See [Circuit Breakers](../../../using/circuit-breakers/). | - -The following field is only used if `proto` is set to `grpc`. It is -ignored if `proto` is `http`. - -| Attribute | Default value | Description | -| ------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `protocol_version` | `v3` | Allowed values are `v3` and `v2`(defualt). `protocol_version` was used in previous versions of $productName$ to control the protocol used by the gRPC service. $productName$ 3.x is running an updated version of Envoy that has dropped support for the `v2` protocol, so starting in 3.x, if `protocol_version` is not specified, 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. | - -The following fields are only used if `proto` is set to `http`. They -are ignored if `proto` is `grpc`. - -| Attribute | Default value | Description | -| ------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `path_prefix` | `""` | Prepends a string to the request path of the request when sending it to the external auth service. By default this is empty, and nothing is prepended. For example, if the client makes a request to `/foo`, and `path_prefix: /bar`, then the path in the request made to the external auth service will be `/foo/bar`. | -| `allowed_request_headers` | `[]` | Lists the headers (case-insensitive) that are copied from the incoming request to the request made to the external auth service. In addition to the headers listed in this field, the following headers are always included: `Authorization`, `Cookie`, `From`, `Proxy-Authorization`, `User-Agent`, `X-Forwarded-For`, `X-Forwarded-Host`, and `X-Forwarded-Proto`. | -| `allowed_authorization_headers` | `[]` | Lists the headers (case-insensitive) that are copied from the response from the external auth service to the request sent to the upstream backend service (if the external auth service indicates that the request to the upstream backend service should be allowed). In addition to the headers listed in this field, the following headers are always included: `Authorization`, `Location`, `Proxy-Authenticate`, `Set-cookie`, `WWW-Authenticate` | -| `add_auth_headers` | `{}` | A dictionary of `header: value` pairs that are added to the request made to the external auth service. | -| `add_linkerd_headers` | Defaults to the value set in the [`ambassador` `Module`](../../ambassador) | When true, in the request to the external auth service, adds an `l5d-dst-override` HTTP header that is set to the hostname and port number of the external auth service. | - -## Canarying multiple `AuthServices` - -You may create multiple `AuthService` manifests to round-robin -authentication requests among multiple services. **All services must -use the same `path_prefix` and header definitions.** If you try to -have different values, you'll see an error in the [diagnostics -service](../../ambassador/#diagnostics), telling you which value is -being used. - -## Configuring public `Mappings` - -An `AuthService` can be disabled for a `Mapping` by setting -`bypass_auth` to `true`. This will tell $productName$ to allow all -requests for that `Mapping` through without interacting with the -external auth service. - - - -## Transport Protocol Migration - - -> **Note:** The following information is only applicable to `AuthServices` using `proto: grpc` -As of $productName$ version 2.3, the `v2` transport protocol is deprecated and any AuthServices making use -of it should migrate to `v3` before support for `v2` is removed in a future release. - -The following imports simply need to be updated to migrate an AuthService - -`v2` Imports: -``` - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" -``` - -`v3` Imports: -``` - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" -``` diff --git a/content/en/docs/3.2/topics/running/services/ext_authz.md b/content/en/docs/3.2/topics/running/services/ext_authz.md deleted file mode 100644 index d850ba4b..00000000 --- a/content/en/docs/3.2/topics/running/services/ext_authz.md +++ /dev/null @@ -1,83 +0,0 @@ -# ExtAuth protocol - -By design, the ExtAuth protocol used by [the AuthService](../auth-service) and by [External Filters](/docs/edge-stack/latest/topics/using/filters/external) is highly flexible. The authentication service is the first external service invoked on an incoming request (e.g., it runs before the rate limit filter). Because the logic of authentication is encapsulated in an external service, you can use this to support a wide variety of use cases. For example: - -* Supporting traditional SSO authentication protocols, e.g., OAuth, OpenID Connect, etc. -* Supporting HTTP basic authentication ([see a sample implementation](https://github.com/datawire/ambassador-auth-httpbasic)). -* Only authenticating requests that are under a rate limit and rejecting authentication requests above the rate limit. -* Authenticating specific services (URLs), and not others. - -For each request, the ExtAuth service may either: - 1. return a direct HTTP *response*, intended to be sent back to the requesting HTTP client (normally *denying* the request from being forwarded to the upstream backend service) or - 2. return a modification to make to the HTTP *request* before sending it to the upstream backend service (normally *allowing* the request to be forwarded to the upstream backend service with modifications). - -The ExtAuth service receives information about every request through $productName$ and must indicate whether the request is to be allowed or not. If not, the ExtAuth service provides the HTTP response which is to be handed back to the client. A potential control flow for Authentication is shown in the image below. - -Giving the ExtAuth service the ability to control the response allows many different types of auth mechanisms, for example: - -- The ExtAuth service can simply return an error page with an HTTP 401 response. -- The ExtAuth service can choose to include a `WWW-Authenticate` header in the 401 response, to ask the client to perform HTTP Basic Auth. -- The ExtAuth service can issue a 301 `Redirect` to divert the client into an OAuth or OIDC authentication sequence. The control flow of this is shown below. ![Authentication flow](../../../images/auth-flow.png) - -There are two variants of the ExtAuth: gRPC and plain HTTP. - -### The gRPC protocol - -When `proto: grpc` is set, the ExtAuth service must implement the `Authorization` gRPC interface, defined in [Envoy's `external_auth.proto`](https://github.com/emissary-ingress/emissary/blob/master/api/envoy/service/auth/v3/external_auth.proto). - -### The HTTP protocol - -External services for `proto: http` are often easier to implement, but have several limitations compared to `proto: grpc`. - - The list of headers that the ExtAuth service is interested in reading must be known ahead of time, in order to set `allow_request_headers`. Inspecting headers that are not known ahead of time requires instead using `proto: grpc`. - - The list of headers that the ExtAuth service would like to set or modify must be known ahead of time, in order to set `allow_authorization_headers`. Setting headers that are not known ahead of time requires instead using `proto: grpc`. - - When returning a direct HTTP response, the HTTP status code cannot be 200 or in the 5XX range. Intercepting with a 200 or 5XX response requires instead using `proto: grpc`. - -#### The request From $productName$ to the ExtAuth service - -For every incoming request, a similar request is made to the ExtAuth service that mimics the: - - HTTP request method - - HTTP request path, potentially modified by `path_prefix` - - HTTP request headers that are either named in `allowed_request_headers` or in the fixed list of headers that are always included - - first `include_body.max_bytes` of the HTTP request body. - -The `Content-Length` HTTP header is set to the number of bytes in the body of the request sent to the ExtAuth service (`0` if `include_body` is not set). - -**ALL** request methods will be proxied, which implies that the ExtAuth service must be able to handle any request that any client could make. - -Take this incoming request for example: - -``` -PUT /path/to/service HTTP/1.1 -Host: myservice.example.com:8080 -User-Agent: curl/7.54.0 -Accept: */* -Content-Type: application/json -Content-Length: 27 - -{ "greeting": "hello world!", "spiders": "OMG no" } -``` - -The request $productName$ will make of the auth service is: - -``` -PUT /path/to/service HTTP/1.1 -Host: extauth.example.com:8080 -User-Agent: curl/7.54.0 -Accept: */* -Content-Type: application/json -Content-Length: 0 -``` - -#### The response returned from the ExtAuth service to $productName$ - - - If the HTTP response returned from the ExtAuth service to $productName$ has an HTTP status code of 200, then the request is allowed through to the upstream backend service. **Only** 200 indicates this; other 2XX status codes will prevent the request from being allowed through. - - The 200 response should not contain anything in the body, but may contain arbitrary headers. Any header present in the ExtAuth service' response that is also either listed in the `allow_authorization_headers` attribute of the AuthService resource or in the fixed list of headers that are always included will be copied from the ExtAuth service's response into the request going to the upstream backend service. This allows the ExtAuth service to inject tokens or other information into the request, or to modify headers coming from the client. - - The big limitation here is that the list of headers to be set must be known ahead of time, in order to set `allow_request_headers`. Setting headers that are not known ahead of time requires instead using `proto: grpc`. - - - If $productName$ cannot reach the ExtAuth service at all, if the ExtAuth service does not return a valid HTTP response, or if the HTTP response has an HTTP status code in the 5XX range, then the communication with the ExtAuth service is considered to have failed, and the `status_on_error` or `failure_mode_allow` behavior is triggered. - - - Any HTTP status code other than 200 or 5XX from the ExtAuth service tells $productName$ to **not** allow the request to continue to the upstream backend service, but that the ExtAuth service is instead intercepting the request. The entire HTTP response from the ExtAuth service--including the status code, the headers, and the body--is handed back to the client verbatim. This gives the ExtAuth service **complete** control over the entire response presented to the client. - - The big limitation here is that you cannot directly return a 200 or 5XX response. Intercepting with a 200 of 5XX response requires instead using `proto: grpc`. diff --git a/content/en/docs/3.2/topics/running/services/index.md b/content/en/docs/3.2/topics/running/services/index.md deleted file mode 100644 index 1646aa5a..00000000 --- a/content/en/docs/3.2/topics/running/services/index.md +++ /dev/null @@ -1,11 +0,0 @@ -# Available plugins - -You may need an API Gateway to enforce policies specific to your organization. $productName$ supports custom policies through external service plugins. The policy logic specific to your organization is implemented in the external service, and $productName$ is configured to send RPC requests to your service. - -Currently, $productName$ supports plugins for authentication, -access logging, rate limiting, and tracing. - -* [AuthService](auth-service) Plugin -* [LogService](log-service) Plugin -* [RateLimitService](rate-limit-service) Plugin -* [TracingService](tracing-service) Plugin diff --git a/content/en/docs/3.2/topics/running/services/log-service.md b/content/en/docs/3.2/topics/running/services/log-service.md deleted file mode 100644 index b3e90c7c..00000000 --- a/content/en/docs/3.2/topics/running/services/log-service.md +++ /dev/null @@ -1,116 +0,0 @@ -# Log service - -By default, $productName$ puts the access logs on stdout; such -that the can be read using `kubectl logs`. The format of those logs, -and the local destination of them, can be configured using the -[`envoy_log_` settings in the `ambassador -Module`](../../ambassador). However, the -options there only allow for logging local to $productName$'s Pod. By -configuring a `LogService`, you can configure $productName$ to -report its access logs to a remote service, in addition to the usual -`ambassador Module` configured logging. - -The remote access log service (or ALS) must implement the -`AccessLogService` gRPC interface, defined in [Envoy's `als.proto`][als.proto]. - -[als.proto]: https://github.com/emissary-ingress/emissary/blob/master/api/envoy/service/accesslog/v3/als.proto - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: LogService -metadata: - name: example-log-service -spec: - # Common to all $productName$ resources - ambassador_id: []string # optional; default is ["default"] - - # LogService specific - service: "string" # required - driver: "enum-string:[tcp, http]" # required - driver_config: # required - additional_log_headers: # optional; default is [] (only for `driver: http`) - - header_name: string # required - during_request: boolean # optional; default is true - during_response: boolean # optional; default is true - during_trailer: boolean # optional; default is true - flush_interval_time: int-seconds # optional; default is 1 - flush_interval_byte_size: integer # optional; default is 16384 - grpc: boolean # optional; default is false - protocol_version: enum # optional; default is v2 -``` - - - `service` is where to route the access log gRPC requests to - - - `driver` identifies which type of accesses to log; HTTP requests (`"http"`) or - TLS connections (`"tcp"`). - - - `driver_config` stores the configuration that is specific to the `driver`: - - * `driver: tcp` has no additional configuration; the config must - be set as `driver_config: {}`. - - * `driver: http` - - - `additional_log_headers` identifies HTTP headers to include in - the access log, and when in the logged-request's lifecycle to - include them. - - - `flush_interval_time` is the maximum number of seconds to buffer - accesses for before sending them to the ALS. The logs will be - flushed to the ALS every time this duration is reached, or when the - buffered data reaches `flush_interval_byte_size`, whichever comes - first. See the [Envoy documentation on - `buffer_flush_interval`][buffer_flush_interval] for more - information. - - - `flush_interval_byte_size` is a soft size limit for the access log - buffer. The logs will be flushed to the ALS every time the - buffered data reaches this size, or whenever `flush_interval_time` - elapses, whichever comes first. See the [Envoy documentation on - `buffer_size_bytes`][buffer_size_bytes] for more information. - - - `grpc` must be `true`. - -[buffer_flush_interval]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/access_loggers/grpc/v3/als.proto.html#extensions-access-loggers-grpc-v3-commongrpcaccesslogconfig -[buffer_size_bytes]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/access_loggers/grpc/v3/als.proto.html#extensions-access-loggers-grpc-v3-commongrpcaccesslogconfig - - - `protocol_version` was used in previous versions of $productName$ to control the gRPC service name used to communicate with the `LogService`. $productName$ 3.x is running an updated version of Envoy that has dropped support for the `v2` protocol, so starting in 3.x, if `protocol_version` is not specified, 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. - -## Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: LogService -metadata: - name: als -spec: - service: "als.default:3000" - driver: http - driver_config: {} # NB: driver_config must be set, even if it's empty - grpc: true # NB: grpc must be true and it will use the V3 transport protocol -``` - -## Transport Protocol Migration - - -> **Note:** The following information is only applicable to `AuthServices` using `proto: grpc` -As of $productName$ version 2.3, the `v2` transport protocol is deprecated and any AuthServices making use -of it should migrate to `v3` before support for `v2` is removed in a future release. - -The following imports simply need to be updated to migrate an AuthService - -`v2` Imports: -``` - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" -``` - -`v3` Imports: -``` - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" -``` diff --git a/content/en/docs/3.2/topics/running/services/rate-limit-service.md b/content/en/docs/3.2/topics/running/services/rate-limit-service.md deleted file mode 100644 index 39c2b0ce..00000000 --- a/content/en/docs/3.2/topics/running/services/rate-limit-service.md +++ /dev/null @@ -1,118 +0,0 @@ -# Rate limit service - -Rate limiting is a powerful technique to improve the [availability and -resilience of your -services](https://blog.getambassador.io/rate-limiting-a-useful-tool-with-distributed-systems-6be2b1a4f5f4). -In $productName$, each request can have one or more _labels_. These labels are -exposed to a third-party service via a gRPC API. The third-party service can -then rate limit requests based on the request labels. - -**Note that `RateLimitService` is only applicable to $OSSproductName$, -and not $AESproductName$, as $AESproductName$ includes a -built-in rate limit service.** - -## Request labels - -See [Attaching labels to -requests](../../../using/rate-limits#attaching-labels-to-requests) -for how to configure the labels that are attached to a request. - -## Domains - -In $productName$, each engineer (or team) can be assigned its own _domain_. A -domain is a separate namespace for labels. By creating individual domains, each -team can assign their own labels to a given request, and independently set the -rate limits based on their own labels. - -See [Attaching labels to -requests](../../../using/rate-limits/#attaching-labels-to-requests) -for how to labels under different domains. - -## External rate limit service - -In order for $productName$ to rate limit, you need to implement a -gRPC `RateLimitService`, as defined in [Envoy's `v3/rls.proto`] -interface. If you do not have the time or resources to implement your own rate -limit service, $AESproductName$ integrates a high-performance rate -limiting service. - -[envoy's `v3/rls.proto`]: https://github.com/emissary-ingress/emissary/tree/master/api/envoy/service/ratelimit/v3/rls.proto - -$productName$ generates a gRPC request to the external rate limit -service and provides a list of labels on which the rate limit service can base -its decision to accept or reject the request: - -``` -[ - {"source_cluster", ""}, - {"destination_cluster", ""}, - {"remote_address", ""}, - {"generic_key", ""}, - {"", ""} -] -``` - -If $productName$ cannot contact the rate limit service, it will -allow the request to be processed as if there were no rate limit service -configuration. - -It is the external rate limit service's responsibility to determine whether rate -limiting should take place, depending on custom business logic. The rate limit -service must simply respond to the request with an `OK` or `OVER_LIMIT` code: - -- If Envoy receives an `OK` response from the rate limit service, then $productName$ allows the client request to resume being processed by - the normal flow. -- If Envoy receives an `OVER_LIMIT` response, then $productName$ - will return an HTTP 429 response to the client and will end the transaction - flow, preventing the request from reaching the backing service. - -The headers injected by the [AuthService](../auth-service) can also be passed to -the rate limit service since the `AuthService` is invoked before the -`RateLimitService`. - -## Configuring the rate limit service - -A `RateLimitService` manifest configures $productName$ to use an -external service to check and enforce rate limits for incoming requests: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: RateLimitService -metadata: - name: ratelimit -spec: - service: 'example-rate-limit.default:5000' - protocol_version: # default is v2, if upgrading from 2.x then you must set this to v3. - failure_mode_deny: false # when set to true envoy will return 500 error when unable to communicate with RateLimitService -``` - -- `service` gives the URL of the rate limit service. If using a Kubernetes service, this should be the [namespace-qualified DNS name](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#namespaces-of-services) of that service. -- `protocol_version` Allowed values are `v3` and `v2`(default). `protocol_version` was used in previous versions of $productName$ to control the protocol used by the gRPC service to communicate with the `RateLimitService`. $productName$ 3.x is running an updated version of Envoy that has dropped support for the `v2` protocol, so starting in 3.x, if `protocol_version` is not specified, 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. -- `failure_mode_deny` By default, Envoy will fail open when unable to communicate with the service due to it becoming unvailable or due to timeouts. When this happens the upstream service that is being protected by a rate limit may be overloaded due to this behavior. When set to `true` Envoy will be configured to return a `500` status code when it is unable to communicate with the RateLimit service and will fail closed by rejecting request to the upstream service. - -You may only use a single `RateLimitService` manifest. - -## Rate limit service and TLS - -You can tell $productName$ to use TLS to talk to your service by -using a `RateLimitService` with an `https://` prefix. However, you may also -provide a `tls` attribute: if `tls` is present and `true`, $productName$ will originate TLS even if the `service` does not have the `https://` -prefix. - -If `tls` is present with a value that is not `true`, the value is assumed to be the name of a defined TLS context, which will determine the certificate presented to the upstream service. - -## Example - -The [$OSSproductName$ Rate Limiting -Tutorial](../../../../howtos/rate-limiting-tutorial) has a simple rate limiting -example. For a more advanced example, read the [advanced rate limiting -tutorial](../../../../../2.0/howtos/advanced-rate-limiting), which uses the rate limit -service that is integrated with $AESproductName$. - -## Further reading - -- [Rate limiting: a useful tool with distributed systems](https://blog.getambassador.io/rate-limiting-a-useful-tool-with-distributed-systems-6be2b1a4f5f4) -- [Rate limiting for API Gateways](https://blog.getambassador.io/rate-limiting-for-api-gateways-892310a2da02) -- [Implementing a Java Rate Limiting Service for $productName$](https://blog.getambassador.io/implementing-a-java-rate-limiting-service-for-the-ambassador-api-gateway-e09d542455da) -- [Designing a Rate Limit Service for $productName$](https://blog.getambassador.io/designing-a-rate-limiting-service-for-ambassador-f460e9fabedb) diff --git a/content/en/docs/3.2/topics/running/services/tracing-service.md b/content/en/docs/3.2/topics/running/services/tracing-service.md deleted file mode 100644 index 69f4551d..00000000 --- a/content/en/docs/3.2/topics/running/services/tracing-service.md +++ /dev/null @@ -1,119 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Tracing service - -Applications that consist of multiple services can be difficult to debug, as a single request can span multiple services. Distributed tracing tells the story of your request as it is processed through your system. Distributed tracing is a powerful tool to debug and analyze your system in addition to request logging and metrics. - -When enabled, the `TracingService` will instruct $productName$ to initiate a trace on requests by generating and populating an `x-request-id` HTTP header. Services can make use of this `x-request-id` header in logging and forward it in downstream requests for tracing. $productName$ also integrates with external trace visualization services, including [LightStep](https://lightstep.com/) and Zipkin-compatible APIs such as [Zipkin](https://zipkin.io/) and [Jaeger](https://github.com/jaegertracing/) to allow you to store and visualize traces. You can read further on [Envoy's Tracing capabilities](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/tracing). - -A `TracingService` manifest configures $productName$ to use an external trace visualization service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TracingService -metadata: - name: tracing -spec: - service: "example-zipkin:9411" - driver: zipkin - config: {} - custom_tags: # optional - - tag: host - request_header: - name: ":authority" - default_value: "unknown" - - tag: path - request_header: - name: ":path" - default_value: "unknown" - sampling: - overall: 100 -``` - -| Field | Description | values | -| --------- | ----------- | ------------- | -| `service` | gives the URL of the external HTTP trace service. | ex. `example-zipkin:9411` | -| `driver` | provides the driver information that handles communicating with the service | enum:
`lightstep`
`zipkin`
`datadog` | -| `config` | provides additional configuration options for the selected `driver`. Supported configuration for each driver is found below. | | -| `tag_headers` | **Deprecated** - it is recommend that you switch to using `custom_tags`| | -| `custom_tags` | configure tags to attach to traces. See section below for more details. | | -| `propagation_modes` | (optional) if present, specifies a list of the propogation modes to be used | enum:
`ENVOY`
`LIGHTSTEP`
`B3`
`TRACE_CONTEXT` | -| `sampling` | (optional) if present, specifies some target percentages of requests that will be traced. | | - -Please note that you must use the HTTP/2 pseudo-header names. For example: - -- the `host` header should be specified as the `:authority` header; and -- the `method` header should be specified as the `:method` header. - -## Sampling - -Configuring `sampling` will specify some target percentages of requests that will be traced. This is beneficial for high-volume services to control the amount of tracing data collected. Sampling can be configured with the following fields: - -- `client`: percentage of requests that will be force traced if the `x-client-trace-id` header is set. Defaults to 100. -- `random`: percentage of requests that will be randomly traced. Defaults to 100. -- `overall`: percentage of requests that will be traced after all other checks have been applied (force tracing, sampling, etc.). -This field functions as an upper limit on the total configured sampling rate. For instance, setting `client` -to `100%` but `overall` to `1%` will result in only `1%` of client requests with the appropriate headers to be force -traced. Defaults to 100. - -## Custom Tags and Tag Headers - -When collecting traces, $productName$ will attach tags to the `span`'s that are generated which are useful for observability. See the [Envoy Tracing Docs](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/tracing#what-data-each-trace-contains) for the default list of data collected. - -Previous versions of $productName$ only supported adding additional tags through the use of the `tag_headers` field. This field is now **deprecated** and it is recommended to use `custom_tags` which supports a more powerful set of features for adding additional tags to a span. - - -If both tag_headers and custom_tags are set then tag_headers will be ignored. - - -`custom_tags` provides support for configuring additional tags based on [Envoy Custom Tags](https://www.envoyproxy.io/docs/envoy/latest/api-v3/type/tracing/v3/custom_tag.proto%23custom-tag). The following custom tag kinds supported are: - -- `request_header` - set tag from header in the request -- `environment` - set tag from an environment variable -- `literal` - set tag based on a configured literal value - -Each custom_tag supports setting oneOf `request_header`, `literal` or `environment`. Each tag should have its own entry in `custom_tags`. - -For example: - -```yaml -custom_tags: - - tag: host - request_header: - name: ":authority" - default_value: "unknown host" # optional - - tag: path - request_header: ":path" - name: ":authority" - default_value: "unknown path" # optional - - tag: cluster - literal: - value: "us-east-cluster" - - tag: nodeID - environment: - name: SERVER_ID - default_value: "unknown" # optional -``` - -### Lightstep driver configurations - -- `access_token_file` provides the location of the file containing the access token to the LightStep API. - -### Zipkin driver configurations - -- `collector_endpoint` gives the API endpoint of the Zipkin service where the spans will be sent. The default value is `/api/v2/spans` -- `collector_endpoint_version` gives the transport version used when sending data to your Zipkin collector. The default value is `HTTP_JSON` and it must be one of `HTTP_JSON` or `HTTP_PROTO`. -- `collector_endpoint_hostname` sets the hostname Envoy will use when sending data to your Zipkin collector. The default value is the name of the underlying Envoy cluster. -- `trace_id_128bit` whether a 128-bit `trace id` will be used when creating a new trace instance. Defaults to `true`. Setting to `false` will result in a 64-bit trace id being used. -- `shared_span_context` whether client and server spans will share the same `span id`. The default value is `true`. - -### Datadog Driver Configurations - -- `service_name` the name of the service which is attached to the traces. The default value is `ambassador`. - -You may only use a single `TracingService` manifest per $productName$ deployment. Ensure [ambassador_id](../../running#ambassador_id) is set correctly in the `TracingService` manifest. - -## Example - -Check out the [DataDog](../../../../howtos/tracing-datadog) and [Zipkin](../../../../howtos/tracing-zipkin) HOWTOs. diff --git a/content/en/docs/3.2/topics/running/statistics/8877-metrics.md b/content/en/docs/3.2/topics/running/statistics/8877-metrics.md deleted file mode 100644 index c8d0d431..00000000 --- a/content/en/docs/3.2/topics/running/statistics/8877-metrics.md +++ /dev/null @@ -1,65 +0,0 @@ -# The metrics endpoint - -> For an overview of other options for gathering statistics on -> $productName$, see the [Statistics and Monitoring](../) overview. - -Each $productName$ pod exposes statistics and metrics for that pod at -`http://{POD}:8877/metrics`. The response is in the text-based -Prometheus [exposition format][]. - -[exposition format]: https://prometheus.io/docs/instrumenting/exposition_formats/ - -## Understanding the statistics - -The Prometheus exposition format includes special "HELP" lines that -make the file self-documenting as to what specific statistics mean. - - - -- `envoy_*`: See the [Envoy documentation][`GET /stats/prometheus`]. -- `ambassador_*`: - - `ambassador_edge_stack_*` (not present in $OSSproductName$): - - `ambassador_edge_stack_go_*`: See [`promethus.NewGoCollector()`][]. - - `ambassador_edge_stack_promhttp_*` See [`promhttp.Handler()`][]. - - `ambassador_edge_stack_process_*`: See [`promethus.NewProcessCollector()`][].. - - `ambassador_*_time_seconds` (for `*` = one of `aconf`, `diagnostics`, `econf`, `fetcher`, `ir`, or `reconfiguration`): - Gauges of how long the various core operations take in the diagd - process. - - `ambassador_diagnostics_(errors|notices)`: The number of - diagnostics errors and notices that would be shown in the - diagnostics UI or the Edge Policy Console. - - `ambassador_diagnostics_info`: [Info][`prometheus_client.Info`] - about the $productName$ install; all information is presented in - labels; the value of the Gauge is always "1". - - `ambassador_process_*`: See [`prometheus_client.ProcessCollector`][]. - -[`GET /stats/prometheus`]: https://www.envoyproxy.io/docs/envoy/v1.23.0/operations/admin.html#get--stats-prometheus -[`prometheus.NewProcessCollector`]: https://godoc.org/github.com/prometheus/client_golang/prometheus#NewProcessCollector -[`prometheus.NewGoCollector`]: https://godoc.org/github.com/prometheus/client_golang/prometheus#NewGoCollector -[`promhttp.Handler()`]: https://godoc.org/github.com/prometheus/client_golang/prometheus/promhttp#Handler -[`prometheus_client.Info`]: https://github.com/prometheus/client_python#info -[`prometheus_client.ProcessCollector`]: https://github.com/prometheus/client_python#process-collector - -## Polling the `:8877/metrics` endpoint with Prometheus - -To scrape metrics directly, follow the instructions for [Monitoring -with Prometheus and Grafana](../../../../howtos/prometheus). - -### Using Grafana to visualize statistics gathered by Prometheus - -#### Sample dashboard - -We provide a [sample Grafana dashboard](https://grafana.com/dashboards/4698) -that displays information collected by Prometheus from the -`:8877/metrics` endpoint. - - -![Screenshot of a Grafana dashboard that displays just information from Envoy](../../../images/grafana.png) diff --git a/content/en/docs/3.2/topics/running/statistics/envoy-statsd.md b/content/en/docs/3.2/topics/running/statistics/envoy-statsd.md deleted file mode 100644 index 7cbcc208..00000000 --- a/content/en/docs/3.2/topics/running/statistics/envoy-statsd.md +++ /dev/null @@ -1,109 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Envoy statistics with StatsD - -> For an overview of other options for gathering statistics on -> $productName$, see the [Statistics and Monitoring](../) overview. - -At the core of $productName$ is [Envoy Proxy], which has built-in -support for exporting a multitude of statistics about its own -operations to StatsD (or to the modified DogStatsD used by Datadog). - -[Envoy Proxy]: https://www.envoyproxy.io - -If enabled, then $productName$ has Envoy expose this information via the -[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: - -```diff - spec: - containers: - - env: -+ - name: STATSD_ENABLED -+ value: "true" - - name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: -``` - -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. - -We have included a few example configurations in -[the `statsd-sink/` directory](https://github.com/emissary-ingress/emissary/tree/master/deployments/statsd-sink) -to help you get started. Clone or download the -repository to get local, editable copies and open a terminal -window in the `emissary/deployments/` folder. - -## Using Graphite as the StatsD sink - -[Graphite] is a web-based real-time graphing system. Spin up an -example Graphite setup: - -[Graphite]: http://graphite.readthedocs.org/ - -``` -kubectl apply -f statsd-sink/graphite/graphite-statsd-sink.yaml -``` - -This sets up the `statsd-sink` service and a deployment that contains -Graphite and its related infrastructure. Graphite's web interface is -available at `http://statsd-sink/` from within the cluster. Use port -forwarding to access the interface from your local machine: - -``` -SINKPOD=$(kubectl get pod -l service=statsd-sink -o jsonpath="{.items[0].metadata.name}") -kubectl port-forward $SINKPOD 8080:80 -``` - -This sets up Graphite access at `http://localhost:8080/`. - -## Using Datadog DogStatsD as the StatsD sink - -If you are a user of the [Datadog] monitoring system, pulling in the -Envoy statistics from $productName$ is very easy. - -[Datadog]: https://www.datadoghq.com/ - -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: - -```diff - spec: - containers: - - env: -+ - name: STATSD_ENABLED -+ value: "true" -+ - name: DOGSTATSD -+ value: "true" - - name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: -``` - -Then, you will need to deploy the DogStatsD agent in to your cluster -to act as the StatsD sink. To do this, replace the sample API key in -our [sample YAML file][`dd-statsd-sink.yaml`] with your own, then -apply that YAML: - -[`dd-statsd-sink.yaml`]: https://github.com/emissary-ingress/emissary/blob/master/deployments/statsd-sink/datadog/dd-statsd-sink.yaml - -``` -kubectl apply -f statsd-sink/datadog/dd-statsd-sink.yaml -``` - -This sets up the `statsd-sink` service and a deployment of the -DogStatsD agent that forwards the $productName$ statistics to your -Datadog account. - -Additionally, $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). diff --git a/content/en/docs/3.2/topics/running/statistics/index.md b/content/en/docs/3.2/topics/running/statistics/index.md deleted file mode 100644 index ab44009f..00000000 --- a/content/en/docs/3.2/topics/running/statistics/index.md +++ /dev/null @@ -1,84 +0,0 @@ -# Statistics and monitoring - -$productName$ collects many statistics internally, and makes it easy to -direct this information to a statistics and monitoring tool of your -choice. - -As an example, here are some interesting statistics to investigate: - -- `upstream_rq_total` is the total - number of requests that a particular service has received via $productName$. The rate of change of this value is one basic measure of - service utilization, i.e. requests per second. -- `upstream_rq_xx` is the total number - of requests to which a service responded with a given status code. - This value divided by the prior one, taken on - a rolling window basis, represents the recent response rate of the - service. There are corresponding classes for `2xx`, `3xx`, `4xx` and `5xx` counters that can - help clarify the nature of responses. -- `upstream_rq_time` is a Prometheus histogram or StatsD timer - that tracks the latency in milliseconds of a given service from $productName$'s perspective. - -## Overriding Statistics Names - -The optional `stats_name` element of every CRD that references a service (`Mapping`, `TCPMapping`, -`AuthService`, `LogService`, `RateLimitService`, and `TracingService`) can override the name under which cluster statistics -are logged (`usersvc` above). If not set, the default is the `service` value, with non-alphanumeric characters replaced by -underscores: - -- `service: foo` will just use `foo` -- `service: foo:8080` will use `foo_8080` -- `service: http://foo:8080` will use `http___foo_8080` -- `service: foo.othernamespace` will use `foo_othernamespace` - -The last example is worth special mention: a resource in a different namespace than the one in which $productName$ is running will automatically be qualified with the namespace of the resource itself. So, for example, if $productName$ is running in the `ambassador` namespace, and this `Mapping` is present in the `default` namespace: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: default-mapping - namespace: default -spec: - prefix: /default/ - service: default-service -``` - -then the `service` will be qualified to `default-service.default`, so the `stats_name` will be `default_service_default` rather than simply `default_service`. To change this behavior, set `stats_name` explicitly. - -## Monitoring Statistics - -There are several ways to get different statistics out of $productName$: - -- [The `:8877/metrics` endpoint](./8877-metrics) can be polled for - aggregated statistics (in a Prometheus-compatible format). This is - our recommended method as both Envoy metrics and $productName$ control plane - metrics are collected. -- $productName$ can push [Envoy statistics](./envoy-statsd) over the - StatsD or DogStatsD protocol. - -## The Four Golden Signals - -The [Four Golden Signals](https://sre.google/sre-book/monitoring-distributed-systems/) are four generally-accepted metrics -that are important to monitor for good information about service health: - -### Latency - -The time it takes to service a request as a histogram of time taken by individual requests, which can be an effective latency metric. -In StatsD, this stat would be expressed as `cluster.$name.upstream_rq_time`. -While in Prometheus format, this metric would be expressed as `envoy_cluster_upstream_rq_time_bucket{envoy_cluster_name="$name"}`. - -### Traffic - -The amount of demand being placed on your system as a gauge that shows the number of active outstanding requests, which can be a good proxy for traffic. -In StatsD, this stat would be expressed as `cluster.$name.upstream_rq_active`. -While in Prometheus format, this metric would be expressed as `envoy_cluster_upstream_rq_active{envoy_cluster_name="$name"}`. - -### Errors - -The number of failing requests. Some errors (e.g. a request succeeds, but gives the wrong answer) can only be detected by application-specific monitoring; however, many errors can be spotted simply by looking at the HTTP status code of requests. Monitoring it over time can show error rates. -In StatsD, `cluster.$name.upstream_rq_5xx` is a counter of HTTP `5xx` responses. -While in Prometheus, `envoy_cluster_upstream_rq_xx{envoy_response_code_class="5", envoy_cluster_name="$name"}` is a counter of HTTP `5xx` responses. - -### Saturation - -The hardest metric to measure, saturation describes how much of the total capability of the system to respond to requests is being used. Fully measuring saturation often requires application-specific monitoring, but looking at the 99th percentile of latency over a short window - perhaps a minute - can often give an early indication of saturation problems. diff --git a/content/en/docs/3.2/topics/running/tls/cleartext-redirection.md b/content/en/docs/3.2/topics/running/tls/cleartext-redirection.md deleted file mode 100644 index 18f588ce..00000000 --- a/content/en/docs/3.2/topics/running/tls/cleartext-redirection.md +++ /dev/null @@ -1,80 +0,0 @@ ---- - description: Cleartext support - While most modern web applications choose to encrypt all traffic, there are some cases where supporting cleartext communications is i… ---- - -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`. - - - The 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. - - -## Cleartext Routing - -To allow cleartext to be routed, set the `requestPolicy.insecure.action` of a `Host` to `Route`: - -```yaml -requestPolicy: - insecure: - action: Redirect -``` - -This allows routing for either HTTP and HTTPS, or _only_ HTTP, depending on `tlsSecret` configuration: - -- If the `Host` does not specify a `tlsSecret`, it will only route HTTP, not terminating TLS at all. -- If the `Host` does specify a `tlsSecret`, it will route both HTTP and HTTPS. - - - The 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. - - -## HTTP->HTTPS redirection - -Most websites that force HTTPS will also automatically redirect any -requests that come into it over HTTP: - -``` -Client $productName$ -| | -| http:///api | -| --------------------------> | -| | -| 301: https:///api | -| <-------------------------- | -| | -| https:///api | -| --------------------------> | -| | -``` - -In $productName$, this is configured by setting the `insecure.action` in a `Host` to `Redirect`. - -```yaml -requestPolicy: - insecure: - action: Redirect -``` - -$productName$ determines which requests are secure and which are insecure using the -`securityModel` of the [`Listener`] that accepts the request. - -[`Listener`]: ../../listener - - - The 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. - diff --git a/content/en/docs/3.2/topics/running/tls/index.md b/content/en/docs/3.2/topics/running/tls/index.md deleted file mode 100644 index 850fb5c0..00000000 --- a/content/en/docs/3.2/topics/running/tls/index.md +++ /dev/null @@ -1,487 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Transport Layer Security (TLS) - -$productName$'s robust TLS support exposes configuration options -for many different TLS use cases, using the [`Host`](#host) and -[`TLSContext`](#host-and-tlscontext) resources in concert. - -## Certificates and Secrets - -Properly-functioning TLS requires the use of [TLS certificates] to prove that the -various systems communicating are who they say they are. At minimum, $productName$ -must have a server certificate that identifies it to clients; when [mTLS] or -[client certificate authentication] are in use, additional certificates are needed. - -You supply certificates to $productName$ in Kubernetes [TLS Secrets]. These Secrets -_must_ contain valid X.509 certificates with valid PKCS1, PKCS8, or Elliptic Curve private -keys. If a Secret does not contain a valid certificate, an error message will be logged, for -example: - -``` -tls-broken-cert.default.1 2 errors:; 1. K8sSecret secret tls-broken-cert.default tls.key cannot be parsed as PKCS1 or PKCS8: asn1: syntax error: data truncated; 2. K8sSecret secret tls-broken-cert.default tls.crt cannot be parsed as x.509: x509: malformed certificate -``` - -If you set the `AMBASSADOR_FORCE_SECRET_VALIDATION` environment variable, the invalid -Secret will be rejected, and a `Host` or `TLSContext` resource attempting to use an invalid -certificate will be disabled entirely. **Note** that in $productName$ $version$, this -includes disabling cleartext communication for such a `Host`. - -[TLS Certificates]: https://protonmail.com/blog/tls-ssl-certificate/ -[mTLS]: mtls -[client certificate authentication]: ../../../howtos/client-cert-validation/ -[TLS Secrets]: https://kubernetes.io/docs/concepts/configuration/secret/#tls-secrets - -## `Host` - -A `Host` represents a domain in $productName$ and defines how the domain manages TLS. For more information on the Host resource, see [The Host CRD reference documentation](../host-crd). - -**If no `Host`s are present**, $productName$ synthesizes a `Host` that -allows only cleartext routing. You will need to explictly define `Host`s to enable -TLS termination. - - - The examples below do not define a requestPolicy; however, most real-world - usage of $productName$ will require defining the requestPolicy.
-
- For more information, please refer to the Host documentation. - - -### Bring your own certificate - -The `Host` can read a certificate from a Kubernetes Secret and use that certificate -to terminate TLS on a domain. - -The following example shows the certificate contained in the Kubernetes Secret named -`host-secret` configured to have $productName$ terminate TLS on the `host.example.com` -domain: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: host-secret -``` - -By default, `tlsSecret` will only look for the named secret in the same namespace as the `Host`. -In the above example, the secret `host-secret` will need to exist within the `default` namespace -since that is the namespace of the `Host`. - -To reference a secret that is in a different namespace from the `Host`, the `namespace` field is required. -The below example will configure the `Host` to use the `host-secret` secret from the `example` namespace. - -```yaml ---- -apiVersion: getambassador.io/v2 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - acmeProvider: - authority: none - tlsSecret: - name: host-secret - namespace: example -``` - - - - The Kubernetes Secret named by 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. - - - -### Advanced TLS configuration with the `Host` - -You can specify TLS configuration directly in the `Host` via the `tls` field. This is the -recommended method to do more advanced TLS configuration for a single `Host`. - -For example, the configuration to enforce a minimum TLS version on the `Host` looks as follows: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: min-secret - tls: - min_tls_version: v1.2 -``` - - - - The Kubernetes Secret named by 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. - - - -The following fields are accepted in the `tls` field: -```yaml -tls: - cert_chain_file: # string - private_key_file: # string - ca_secret: # string - cacert_chain_file: # string - alpn_protocols: # string - cert_required: # bool - min_tls_version: # string - max_tls_version: # string - cipher_suites: # array of strings - ecdh_curves: # array of strings - sni: # string - crl_secret: # string -``` - -These fields have the same function as in the [`TLSContext`](#tlscontext) resource, -as described below. - -### `Host` and `TLSContext` - -You can link a `Host` to a [`TLSContext`](#tlscontext) instead of defining `tls` -settings in the `Host` itself. This is primarily useful for sharing settings between -multiple `Host`s. - -#### Link a `TLSContext` to the `Host` - - - It is invalid to use both the 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. - - -To link a [`TLSContext`](#tlscontext) with a `Host`, create a [`TLSContext`](#tlscontext) -with the desired configuration and link it to the `Host` by setting the `tlsContext.name` -field in the `Host`. For example, to enforce a minimum TLS version on the `Host` above, -create a `TLSContext` with any name with the following configuration: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: min-tls-context -spec: - hosts: - - host.example.com - secret: min-secret - min_tls_version: v1.2 -``` - -Next, link it to the `Host` via the `tlsContext` field as shown: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: min-secret - tlsContext: - name: min-tls-context -``` - - - - The `Host` and the `TLSContext` must name the same Kubernetes Secret; if not, - $productName$ will disable TLS for the `Host`. - - - - - - The Kubernetes Secret named by 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. - - - - - - The `Host`'s `hostname` and the `TLSContext`'s `hosts` must have compatible settings. If - they do not, requests may not be accepted. - - - -See [`TLSContext`](#tlscontext) below to read more on the description of these fields. - -#### Create a `TLSContext` with the name `{{AMBASSADORHOST}}-context` (DEPRECATED) - - - This implicit 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. - - -The `Host` will implicitly link to the `TLSContext` when a `TLSContext` exists with the following: - -- the name `{{NAME_OF_AMBASSADORHOST}}-context` -- `hosts` in the `TLSContext` set to the same value as `hostname` in the `Host`, and -- `secret` in the `TLSContext` set to the same value as `tlsSecret` in the `Host` - -**As noted above, this implicit linking is deprecated.** - -For example, another way to enforce a minimum TLS version on the `Host` above would -be to simply create the `TLSContext` with the name `example-host-context` and then not modify the `Host`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-host-context -spec: - hosts: - - host.example.com - secret: host-secret - min_tls_version: v1.2 -``` - - - - The `Host` and the `TLSContext` must name the same Kubernetes Secret; if not, - $productName$ will disable TLS for the `Host`. - - - - - - The Kubernetes Secret named by 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. - - - - - - The `Host`'s `hostname` and the `TLSContext`'s `hosts` must have compatible settings. If - they do not, requests may not be accepted. - - - -Full reference for all options available to the `TLSContext` can be found [below](#tlscontext). - -## TLSContext - -The `TLSContext` is used to configure advanced TLS options in $productName$. -Remember, a `TLSContext` must always be paired with a `Host`. - -A full schema of the `TLSContext` can be found below with descriptions of the -different configuration options. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-host-context -spec: - # 'hosts' defines the hosts for which this TLSContext is relevant. - # It ties into SNI. A TLSContext without "hosts" is useful only for - # originating TLS. - # type: array of strings - # - # hosts: [] - - # 'sni' defines the SNI string to use on originated connections. - # type: string - # - # sni: None - - # 'secret' defines a Kubernetes Secret that contains the TLS certificate we - # use for origination or termination. If not specified, $productName$ will look - # at the value of cert_chain_file and private_key_file. - # type: string - # - # secret: None - - # 'ca_secret' defines a Kubernetes Secret that contains the TLS certificate we - # use for verifying incoming TLS client certificates. - # type: string - # - # ca_secret: None - - # Tells $productName$ whether to interpret a "." in the secret name as a "." or - # a namespace identifier. - # type: boolean - # - # secret_namespacing: true - - # 'cert_required' can be set to true to _require_ TLS client certificate - # authentication. - # type: boolean - # - # cert_required: false - - # 'alpn_protocols' is used to enable the TLS ALPN protocol. It is required - # if you want to do GRPC over TLS; typically it will be set to "h2" for that - # case. - # type: string (comma-separated list) - # - # alpn_protocols: None - - # 'min_tls_version' sets the minimum acceptable TLS version: v1.0, v1.1, - # v1.2, or v1.3. It defaults to v1.0. - # min_tls_version: v1.0 - - # 'max_tls_version' sets the maximum acceptable TLS version: v1.0, v1.1, - # v1.2, or v1.3. It defaults to v1.3. - # max_tls_version: v1.3 - - # Tells $productName$ to load TLS certificates from a file in its container. - # type: string - # - # cert_chain_file: None - # private_key_file: None - # cacert_chain_file: None -``` - - - - `secret` and (if used) `ca_secret` must specify Kubernetes Secrets containing valid TLS - certificates. If `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and either Secret contains - an invalid certificate, $productName$ will reject the Secret, which will also completely - disable any `Host` using the `TLSContext`; see [**Certificates and Secrets**](#certificates-and-secrets) - above. - - - -### ALPN protocols - -The `alpn_protocols` setting configures the TLS ALPN protocol. To use gRPC over -TLS, set `alpn_protocols: h2`. If you need to support HTTP/2 upgrade from -HTTP/1, set `alpn_protocols: h2,http/1.1` in the configuration. - -#### HTTP/2 support - -The `alpn_protocols` setting is also required for HTTP/2 support. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls -spec: - secret: ambassador-certs - hosts: ["*"] - alpn_protocols: h2[, http/1.1] -``` -Without setting alpn_protocols as shown above, HTTP2 will not be available via -negotiation and will have to be explicitly requested by the client. - -If you leave off http/1.1, only HTTP2 connections will be supported. - -### TLS parameters - -The `min_tls_version` setting configures the minimum TLS protocol version that -$productName$ will use to establish a secure connection. When a client -using a lower version attempts to connect to the server, the handshake will -result in the following error: `tls: protocol version not supported`. - -The `max_tls_version` setting configures the maximum TLS protocol version that -$productName$ will use to establish a secure connection. When a client -using a higher version attempts to connect to the server, the handshake will -result in the following error: -`tls: server selected unsupported protocol version`. - -The `cipher_suites` setting configures the supported ciphers found below using the -[configuration parameters for BoringSSL](https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#Cipher-suite-configuration) when negotiating a TLS 1.0-1.2 connection. -This setting has no effect when negotiating a TLS 1.3 connection. When a client does not -support a matching cipher a handshake error will result. - -The `ecdh_curves` setting configures the supported ECDH curves when negotiating -a TLS connection. When a client does not support a matching ECDH a handshake -error will result. - -``` - - AES128-SHA - - AES256-SHA - - AES128-GCM-SHA256 - - AES256-GCM-SHA384 - - ECDHE-RSA-AES128-SHA - - ECDHE-RSA-AES256-SHA - - ECDHE-RSA-AES128-GCM-SHA256 - - ECDHE-RSA-AES256-GCM-SHA384 - - ECDHE-RSA-CHACHA20-POLY1305 - - ECDHE-ECDSA-AES128-SHA - - ECDHE-ECDSA-AES256-SHA - - ECDHE-ECDSA-AES128-GCM-SHA256 - - ECDHE-ECDSA-AES256-GCM-SHA384 - - ECDHE-ECDSA-CHACHA20-POLY1305 - - ECDHE-PSK-AES128-CBC-SHA - - ECDHE-PSK-AES256-CBC-SHA - - ECDHE-PSK-CHACHA20-POLY1305 - - PSK-AES128-CBC-SHA - - PSK-AES256-CBC-SHA - - DES-CBC3-SHA -``` - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls -spec: - hosts: ["*"] - secret: ambassador-certs - min_tls_version: v1.0 - max_tls_version: v1.3 - cipher_suites: - - "[ECDHE-ECDSA-AES128-GCM-SHA256|ECDHE-ECDSA-CHACHA20-POLY1305]" - - "[ECDHE-RSA-AES128-GCM-SHA256|ECDHE-RSA-CHACHA20-POLY1305]" - ecdh_curves: - - X25519 - - P-256 -``` - - -The `crl_secret` field allows you to reference a Kubernetes Secret that contains a certificate revocation list. -If specified, $productName$ will verify that the presented peer certificate has not been revoked by this CRL even if they are otherwise valid. This provides a way to reject certificates before they expire or if they become compromised. -The `crl_secret` field takes a PEM-formatted [Certificate Revocation List](https://en.wikipedia.org/wiki/Certificate_revocation_list) in a `crl.pem` entry. - -Note that if a CRL is provided for any certificate authority in a trust chain, a CRL must be provided for all certificate authorities in that chain. Failure to do so will result in verification failure for both revoked and unrevoked certificates from that chain. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls-crl -spec: - hosts: ["*"] - secret: ambassador-certs - min_tls_version: v1.0 - max_tls_version: v1.3 - crl_secret: 'ambassador-crl' ---- -apiVersion: v1 -kind: Secret -metadata: - name: ambassador-crl - namespace: ambassador -type: Opaque -data: - crl.pem: | - {BASE64 CRL CONTENTS} ---- -``` diff --git a/content/en/docs/3.2/topics/running/tls/mtls.md b/content/en/docs/3.2/topics/running/tls/mtls.md deleted file mode 100644 index 1b039cf8..00000000 --- a/content/en/docs/3.2/topics/running/tls/mtls.md +++ /dev/null @@ -1,88 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Mutual TLS (mTLS) - -Many organizations have security concerns that require all network traffic -throughout their cluster be encrypted. With traditional architectures, -this was not that complicated of a requirement since internal network traffic -was fairly minimal. With microservices, we are making many more requests over -the network that must all be authenticated and secured. - -In order for services to authenticate with each other, they will each need to -provide a certificate and key that the other trusts before establishing a -connection. This action of both the client and server providing and validating -certificates is referred to as mutual TLS. - -## mTLS with $productName$ - -Since $productName$ is a reverse proxy acting as the entry point to your cluster, -$productName$ is acting as the client as it proxies requests to services upstream. - -It is trivial to configure $productName$ to simply originate TLS connections as -the client to upstream services by setting -`service: https://{{UPSTREAM_SERVICE}}` in the `Mapping` configuration. -However, in order to do mTLS with services upstream, $productName$ must also -have certificates to authenticate itself with the service. - -To do this, we can use the `TLSContext` object to get certificates from a -Kubernetes `Secret` and use those to authenticate with the upstream service. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: upstream-context -spec: - hosts: [] - secret: upstream-certs -``` - -We use `hosts: []` for this `TLSContext` since we do not want to use it to terminate -TLS connections from the client. We are just using this to load certificates for -requests upstream. - - - - The Kubernetes Secret must contain a valid TLS certificate. If the environment - variable `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) in the TLS overview. - - - -After loading the certificates, we can tell $productName$ when to use them by -setting the `tls` parameter in a `Mapping`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: upstream-mapping -spec: - hostname: "*" - prefix: /upstream/ - service: upstream-service - tls: upstream-context -``` - -Now, when $productName$ proxies a request to `upstream-service`, it will provide -the certificates in the `upstream-certs` secret for authentication when -encrypting traffic. - -## Service mesh - -As you can imagine, when you have many services in your cluster all -authenticating with each other, managing all of those certificates can become a -very big challenge. - -For this reason, many organizations rely on a service mesh for their -service-to-service authentication and encryption. - -$productName$ integrates with multiple service meshes and makes it easy to -configure mTLS to upstream services for all of them. Click the links below to -see how to configure $productName$ to do mTLS with any of these service meshes: - -- [Consul Connect](../../../../howtos/consul/) - -- [Istio](../../../../howtos/istio/) diff --git a/content/en/docs/3.2/topics/running/tls/origination.md b/content/en/docs/3.2/topics/running/tls/origination.md deleted file mode 100644 index b15dd5f8..00000000 --- a/content/en/docs/3.2/topics/running/tls/origination.md +++ /dev/null @@ -1,82 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# TLS origination - -Sometimes you may want traffic from $productName$ to your services to be encrypted. For the cases where terminating TLS at the ingress is not enough, $productName$ can be configured to originate TLS connections to your upstream services. - -## Basic configuration - -Telling $productName$ to talk to your services over HTTPS is easily configured in the `Mapping` definition by setting `https://` in the `service` field. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: basic-tls -spec: - hostname: "*" - prefix: / - service: https://example-service -``` - -## Advanced configuration using a `TLSContext` - -If your upstream services require more than basic HTTPS support (for example, providing a client certificate or -setting the minimum TLS version support) you must create a `TLSContext` for $productName$ to use when -originating TLS. For example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls-context -spec: - secret: self-signed-cert - min_tls_version: v1.3 - sni: some-sni-hostname -``` - - - - The Kubernetes Secret named by `secret` must contain a valid TLS certificate. If the - environment variable `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and the Secret contains - an invalid certificate, $productName$ will reject the `TLSContext` and prevent its use; - see [**Certificates and Secrets**](../#certificates-and-secrets) in the TLS overview. - - - -Configure $productName$ to use this `TLSContext` for connections to upstream services by setting the `tls` attribute of a `Mapping`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-with-tls-context -spec: - hostname: "*" - prefix: / - service: https://example-service - tls: tls-context -``` - -The `example-service` service must now support TLS v1.3 for $productName$ to connect. - - - - The Kubernetes Secret named by `secret` must contain a valid TLS certificate. If the - environment variable `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and the Secret contains - an invalid certificate, $productName$ will reject the `TLSContext` and prevent its use; - see [**Certificates and Secrets**](../#certificates-and-secrets) in the TLS overview. - - - - - - A `TLSContext` requires a certificate be provided, even in cases where the upstream - service does not require it (for origination) and the `TLSContext` is not being used - to terminate TLS. In this case, simply generate and provide a self-signed certificate. - - diff --git a/content/en/docs/3.2/topics/running/tls/sni.md b/content/en/docs/3.2/topics/running/tls/sni.md deleted file mode 100644 index 92e4992f..00000000 --- a/content/en/docs/3.2/topics/running/tls/sni.md +++ /dev/null @@ -1,103 +0,0 @@ -# Server Name Indication (SNI) - -$productName$ supports serving multiple `Host`s behind a single IP address, each -with their own certificate. - -This is as easy to do as creating a `Host` for each domain or subdomain you -want $productName$ to serve, getting a certificate for each, and telling -$productName$ which `Host` the route should be created for. - -The example below configures two `Host`s and assigns routes to them. - -## Configuring a `Host` - -The `Host` resources lets you separate configuration for each distinct domain -and subdomain you plan on serving behind $productName$. - -Let's start by creating a simple `Host` and providing our own certificate in -the `host-cert` secret. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: host-cert -``` - -Now let's create a second `Host` for a different domain we want to serve behind -$productName$. This second `Host` uses $AESproductName$'s automatic TLS -to get a certificate from Let's Encrypt. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: host.foo.com - acmeProvider: - email: julian@example.com -``` - -We now have two `Host`s with two different certificates. - - - A minimum version of TLS 1.1 is required to properly use SNI. When setting up your TLS configuration, be sure you are not using TLS 1.0 or older. - - -## Configuring routes - -Now that we have two domains behind $productName$, we can create routes for either -or both of them. - -We do this by setting the `hostname` attribute of a `Mapping` to the domain the -`Mapping` should be created for. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin -spec: - prefix: /httpbin/ - service: httpbin.org:80 - host_rewrite: httpbin.org - hostname: host.example.com -``` - -The above creates a `/httpbin/` endpoint for `host.example.com`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mockbin -spec: - prefix: /foo/ - service: foo-service - hostname: host.foo.com -``` - -The above creates a `/foo/` endpoint for `host.foo.com`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: frontend -spec: - hostname: "*" - prefix: /bar/ - service: bar-endpoint -``` - -The above creates a `/bar/` endpoint for all `Host`s. diff --git a/content/en/docs/3.2/topics/using/authservice.md b/content/en/docs/3.2/topics/using/authservice.md deleted file mode 100644 index cfe3598b..00000000 --- a/content/en/docs/3.2/topics/using/authservice.md +++ /dev/null @@ -1,23 +0,0 @@ -# AuthService settings - -A Mapping can pass these settings along to an [AuthService](../../running/services/auth-service). This is helpful to allow these specific configurations to apply only to certain Mappings and not globally. - -## Bypass authentication - -An AuthService can be disabled for a specific Mapping with the `bypass_auth` attribute. This will tell $productName$ to allow all requests for that Mapping through without interacting with the external auth service. This could be helpful, for example, for a public API. - -```yaml -bypass_auth: true -``` - -## Context extensions - -The `auth_context_extensions` attribute will pass the given values along to the AuthService when authentication happens. The values are arbitrary key value pairs formatted as strings. - -```yaml -auth_context_extensions: - foo: bar - baz: zing -``` - -More information is available on [the Envoy documentation on external authentication](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto.html#extensions-filters-http-ext-authz-v3-checksettings). diff --git a/content/en/docs/3.2/topics/using/canary.md b/content/en/docs/3.2/topics/using/canary.md deleted file mode 100644 index f99de1a3..00000000 --- a/content/en/docs/3.2/topics/using/canary.md +++ /dev/null @@ -1,41 +0,0 @@ -# Canary releases - -Canary releasing is a deployment pattern where a small percentage of traffic is diverted to an early ("canary") release of a particular service. This technique lets you test a release on a small subset of users, mitigating the impact of any given bug. Canary releasing also allows you to quickly roll back to a known good version in the event of an unexpected error. Detailed monitoring of core service metrics is an essential part of canary releasing, as monitoring enables the rapid detection of problems in the canary release. - -## Canary releases in Kubernetes - -Kubernetes supports a basic canary release workflow using its core objects. In this workflow, a service owner can create a Kubernetes [service](https://kubernetes.io/docs/concepts/services-networking/service/). This service can then be pointed to multiple [deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/). Each deployment can be a different version. By specifying the number of `replicas` in a given deployment, you can control how much traffic goes between different versions. For example, you could set `replicas: 3` for `v1`, and `replicas: 1` for `v2`, to ensure that 25% of traffic goes to `v2`. This approach works but is fairly coarse-grained unless you have lots of replicas. Moreover, auto-scaling doesn't work well with this strategy. - -## Canary releases in $productName$ - -$productName$ supports fine-grained canary releases. $productName$ uses a weighted round-robin scheme to route traffic between multiple services. Full metrics are collected for all services, making it easy to compare the relative performance of the canary and production. - -### The weight attribute - -The `weight` attribute specifies how much traffic for a given resource will be routed using a given mapping. Its value is an integer percentage between 0 and 100. $productName$ will balance weights to make sure that, for every resource, the mappings for that resource will have weights adding to 100%. (In the simplest case, a single mapping is guaranteed to receive 100% of the traffic no matter whether it's assigned a `weight` or not.) - -Specifying a weight only makes sense if you have multiple mappings for the same resource, and typically you would _not_ assign a weight to the "default" mapping (the mapping expected to handle most traffic): letting $productName$ assign that mapping all the traffic not otherwise spoken for tends to make life easier when updating weights. - -Here's an example, which might appear during a canary deployment: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - prefix: /backend/ - service: quotev2 - weight: 10 -``` - -In this case, the quote-backend2 will receive 10% of the requests for `/backend/`, and $productName$ will assign the remaining 90% to the quote-backend. diff --git a/content/en/docs/3.2/topics/using/circuit-breakers.md b/content/en/docs/3.2/topics/using/circuit-breakers.md deleted file mode 100644 index 97b40f57..00000000 --- a/content/en/docs/3.2/topics/using/circuit-breakers.md +++ /dev/null @@ -1,116 +0,0 @@ -# Circuit breakers - -Circuit breakers are a powerful technique to improve resilience. By preventing additional connections or requests to an overloaded service, circuit breakers limit the ["blast radius"](https://www.ibm.com/garage/method/practices/manage/practice_limited_blast_radius/) of an overloaded service. By design, $productName$ circuit breakers are distributed, i.e., different $productName$ instances do not coordinate circuit breaker information. - -## Circuit breaker configuration - -A default circuit breaking configuration can be set for all -$productName$ resources in the [`ambassador -Module`](../../running/ambassador), or set to a different value on a -per-resource basis for [`Mappings`](../mappings), -[`TCPMappings`](../tcpmappings/), and -[`AuthServices`](../../running/services/auth-service/). - -The `circuit_breakers` attribute configures circuit breaking. The following fields are supported: - -```yaml -circuit_breakers: -- priority: - max_connections: - max_pending_requests: - max_requests: - max_retries: -``` - -|Key|Default value|Description| -|---|---|---| -|`priority`|`default`|Specifies the priority to which the circuit breaker settings apply to; it can be set to either `default` or `high`.| -|`max_connections`|`1024`|Specifies the maximum number of connections that $productName$ will make to the services. In practice, this is more applicable to HTTP/1.1 than HTTP/2.| -|`max_pending_requests`|`1024`|Specifies the maximum number of requests that will be queued while waiting for a connection. In practice, this is more applicable to HTTP/1.1 than HTTP/2.| -|`max_requests`|`1024`|Specifies the maximum number of parallel outstanding requests to an upstream service. In practice, this is more applicable to HTTP/2 than HTTP/1.1.| -|`max_retries`|`3`|Specifies the maximum number of parallel retries allowed to an upstream service.| - -The `max_*` fields can be reduced to shrink the "blast radius," or -increased to enable $productName$ to handle a larger number of -concurrent requests. - -## Examples - -Circuit breakers defined on a single `Mapping`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - circuit_breakers: - - max_connections: 2048 - max_pending_requests: 2048 -``` - -Circuit breakers defined on a single `AuthService`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: AuthService -metadata: - name: dancing-walrus -spec: - auth_service: http://dancing-walrus:8500 - proto: grpc - circuit_breakers: - - max_requests: 4096 -``` - -A global circuit breaker: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - circuit_breakers: - - max_connections: 2048 - max_pending_requests: 2048 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote -``` - -## Circuit breakers and automatic retries - -Circuit breakers are best used in conjunction with [automatic retries](../retries). Here are some examples: - -* You've configured automatic retries for failed requests to a service. Your service is under heavy load, and starting to time out on servicing requests. In this case, automatic retries can exacerbate your problem, increasing the total request volume by 2x or more. By aggressively circuit breaking, you can mitigate failure in this scenario. -* To circuit break when services are slow, you can combine circuit breakers with retries. Reduce the time out for retries, and then set a circuit breaker that detects many retries. In this setup, if your service doesn't respond quickly, a flood of retries will occur, which can then trip the circuit breaker. - -Note that setting circuit breaker thresholds requires careful monitoring and experimentation. We recommend you start with conservative values for circuit breakers and adjust them over time. - -## More about circuit breakers - -Responses from a broken circuit contain the `x-envoy-overloaded` header. - -The following are the default values for circuit breaking if nothing is specified: - -```yaml -circuit_breakers: -- priority: default - max_connections: 1024 - max_pending_requests: 1024 - max_requests: 1024 - max_retries: 3 -``` - -Circuit breaker metrics are exposed in StatsD. For more information about the specific statistics, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/circuit_breaking.html). diff --git a/content/en/docs/3.2/topics/using/cors.md b/content/en/docs/3.2/topics/using/cors.md deleted file mode 100644 index 315e4694..00000000 --- a/content/en/docs/3.2/topics/using/cors.md +++ /dev/null @@ -1,155 +0,0 @@ -# Cross-Origin Resource Sharing (CORS) - -Cross-Origin resource sharing lets users request resources (e.g., images, fonts, videos) from domains outside the original domain. - -CORS configuration can be set for all $productName$ mappings in the [`ambassador Module`](../../running/ambassador), or set per [`Mapping`](../mappings). - -When the CORS attribute is set at either the `Mapping` or `Module` level, $productName$ will intercept the pre-flight `OPTIONS` request and respond with the appropriate CORS headers. This means you will not need to implement any logic in your upstreams to handle these CORS `OPTIONS` requests. - -The flow of the request will look similar to the following: -``` -Client $productName$ Upstream - | OPTIONS | | - | —————————————————> | | - | CORS_RESP | | - | <————————————————— | | - | GET /foo/ | | - | —————————————————> | ————————————> | - | | RESP | - | <————————————————————————————————— | -``` -## The `cors` attribute - -The `cors` attribute enables the CORS filter. The following settings are supported: - -- `origins`: Specifies a list of allowed domains for the `Access-Control-Allow-Origin` header. To allow all origins, use the wildcard `"*"` value. Format can be either of: - - comma-separated list, e.g. - ```yaml - origins: http://foo.example,http://bar.example - ``` - - YAML array, e.g. - ```yaml - origins: - - http://foo.example - - http://bar.example - ``` - -- `methods`: if present, specifies a list of allowed methods for the `Access-Control-Allow-Methods` header. Format can be either of: - - comma-separated list, e.g. - ```yaml - methods: POST, GET, OPTIONS - ``` - - YAML array, e.g. - ```yaml - methods: - - GET - - POST - - OPTIONS - ``` - -- `headers`: if present, specifies a list of allowed headers for the `Access-Control-Allow-Headers` header. Format can be either of: - - comma-separated list, e.g. - ```yaml - headers: Content-Type - ``` - - YAML array, e.g. - ```yaml - headers: - - Content-Type - ``` - -- `credentials`: if present with a true value (boolean), will send a `true` value for the `Access-Control-Allow-Credentials` header. - -- `exposed_headers`: if present, specifies a list of allowed headers for the `Access-Control-Expose-Headers` header. Format can be either of: - - comma-separated list, e.g. - ```yaml - exposed_headers: X-Custom-Header - ``` - - YAML array, e.g. - ```yaml - exposed_headers: - - X-Custom-Header - ``` - -- `max_age`: if present, indicated how long the results of the preflight request can be cached, in seconds. This value must be a string. - -## Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cors -spec: - prefix: /cors/ - service: cors-example - cors: - origins: http://foo.example,http://bar.example - methods: POST, GET, OPTIONS - headers: Content-Type - credentials: true - exposed_headers: X-Custom-Header - max_age: "86400" -``` - -## AuthService and Cross-Origin Resource Sharing - -When you use external authorization, each incoming request is authenticated before routing to its destination, including pre-flight `OPTIONS` requests. - -By default, many [`AuthService`](../../running/services/auth-service) implementations will deny these requests. If this is the case, you will need to add some logic to your `AuthService` to accept all CORS headers. - -For example, a possible configuration for Spring Boot 2.0.1: - -```java -@EnableWebSecurity -class SecurityConfig extends WebSecurityConfigurerAdapter { - - public void configure(final HttpSecurity http) throws Exception { - http - .cors().configurationSource(new PermissiveCorsConfigurationSource()).and() - .csrf().disable() - .authorizeRequests() - .antMatchers("**").permitAll(); - } - - private static class PermissiveCorsConfigurationSource implements CorsConfigurationSource { - /** - * Return a {@link CorsConfiguration} based on the incoming request. - * - * @param request - * @return the associated {@link CorsConfiguration}, or {@code null} if none - */ - @Override - public CorsConfiguration getCorsConfiguration(final HttpServletRequest request) { - final CorsConfiguration configuration = new CorsConfiguration(); - configuration.setAllowCredentials(true); - configuration.setAllowedHeaders(Collections.singletonList("*")); - configuration.setAllowedMethods(Collections.singletonList("*")); - configuration.setAllowedOrigins(Collections.singletonList("*")); - return configuration; - } - } -} -``` - -This is okay since CORS is being handled by $productName$ after authentication. - -The flow of this request will look similar to the following: - -``` -Client $productName$ Auth Upstream - | OPTIONS | | | - | —————————————————> | ————————————> | | - | | CORS_ACCEPT_* | | - | CORS_RESP |<——————————————| | - | <——————————————————| | | - | GET /foo/ | | | - | —————————————————> | ————————————> | | - | | AUTH_RESP | | - | | <———————————— | | - | | AUTH_ALLOW | | - | | ————————————————————————————> | - | | | RESP | - | <————————————————————————————————————————————————— | - ``` diff --git a/content/en/docs/3.2/topics/using/defaults.md b/content/en/docs/3.2/topics/using/defaults.md deleted file mode 100644 index 673a08be..00000000 --- a/content/en/docs/3.2/topics/using/defaults.md +++ /dev/null @@ -1,32 +0,0 @@ -# Using `ambassador` `Module` defaults - -## The defaults element - -If present, the `ambassador Module` can define a set of defaults that will automatically be applied to certain resources: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - class1: # This is a class. Different resource types will look in different classes. - key1: value1 # Within a class, you can set different keys. - key2: value2 - ... - class2: - ... - top_key1: value1 # If a key isn't found in a resource's class, the system will look in the - top_key2: value2 # toplevel defaults dictionary for it. -``` - -### Mapping - -Currently, only the `Mapping` resource uses the `defaults` mechanism. `Mapping` looks first for defaultable resources in the `httpmapping` class, including: - -- [`add_request_headers`](../../using/headers/add_request_headers) -- [`add_response_headers`](../../using/headers/add_response_headers) -- [`remove_request_headers`](../../using/headers/remove_request_headers) -- [`remove_response_headers`](../../using/headers/remove_response_headers) diff --git a/content/en/docs/3.2/topics/using/gateway-api.md b/content/en/docs/3.2/topics/using/gateway-api.md deleted file mode 100644 index 5e92cd0d..00000000 --- a/content/en/docs/3.2/topics/using/gateway-api.md +++ /dev/null @@ -1,19 +0,0 @@ -# Gateway API - -## Using the Gateway API - -$productName$ now supports a limited subset of the new `v1alpha1` [Gateway API](https://gateway-api.sigs.k8s.io/). -Note that the Gateway API is not supported when `AMBASSADOR_LEGACY_MODE` is set. - -Support is currently limited to the following fields, however this will expand in future releases: - - - `Gateway.spec.listeners.port` - - `HTTPRoute.spec.rules.matches.path.type` (`Exact`, `Prefix`, and `RegularExpression`) - - `HTTPRoute.spec.rules.matches.path.value` - - `HTTPRoute.spec.rules.matches.header.type` (`Exact` and `RegularExpression`) - - `HTTPRoute.spec.rules.matches.header.values` - - `HTTPRoute.spec.rules.forwardTo.serviceName` - - `HTTPRoute.spec.rules.forwardTo.port` - - `HTTPRoute.spec.rules.forwardTo.weight` - -Please see the [specification](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/) for more details. diff --git a/content/en/docs/3.2/topics/using/headers/add_request_headers.md b/content/en/docs/3.2/topics/using/headers/add_request_headers.md deleted file mode 100644 index c6ad4956..00000000 --- a/content/en/docs/3.2/topics/using/headers/add_request_headers.md +++ /dev/null @@ -1,77 +0,0 @@ -# Add request headers - -$productName$ can add a dictionary of HTTP headers that can be added to each request that is passed to a service. - -## The `add_request_headers` attribute - -The `add_request_headers` attribute is a dictionary of `header`: `value` pairs. The `value` can be a `string`, `bool` or `object`. When it is an `object`, the object should have a `value` property, which is the actual header value, and the remaining attributes are additional envoy properties. - -Envoy dynamic values `%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%` and `%PROTOCOL%` are supported, in addition to static values. - -`add_request_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -### Mapping example - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: "*" - prefix: /backend/ - add_request_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-static-2: - value: This the test header #same as above "x-test-static header" - x-test-object: - value: This the value - append: False #True by default - service: quote - ``` - -will add the protocol, client IP, and a static header to `/backend/`. - -### Defaults example - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - add_request_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-static-2: - value: This the test header #same as above "x-test-static header" - x-test-object: - value: This the value - append: False #True by default ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - hostname: "*" - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - hostname: "*" - prefix: /backend2/ - service: quote -``` - -This example will add the same headers for both mappings. diff --git a/content/en/docs/3.2/topics/using/headers/add_response_headers.md b/content/en/docs/3.2/topics/using/headers/add_response_headers.md deleted file mode 100644 index 236ace61..00000000 --- a/content/en/docs/3.2/topics/using/headers/add_response_headers.md +++ /dev/null @@ -1,73 +0,0 @@ -# Add response headers - -$productName$ can add a dictionary of HTTP headers that can be added to each response that is returned to the client. - -## The `add_response_headers` attribute - -The `add_response_headers` attribute is a dictionary of `header`: `value` pairs. The `value` can be a `string`, `bool` or `object`. When it is an `object`, the object should have a `value` property, which is the actual header value, and the remaining attributes are additional envoy properties. - -Envoy dynamic values `%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%` and `%PROTOCOL%` are supported, in addition to static values. - -`add_response_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -### Mapping example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - add_response_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-object: - append: False - value: this is from object header config - service: quote -``` - -will add the protocol, client IP, and a static header to the response returned to the client. - -### Defaults example - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - add_response_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-object: - append: False - value: this is from object header config ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - hostname: "*" - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - hostname: "*" - prefix: /backend2/ - service: quote -``` - -This example will add the same headers for both mappings. diff --git a/content/en/docs/3.2/topics/using/headers/headers.md b/content/en/docs/3.2/topics/using/headers/headers.md deleted file mode 100644 index 126653b0..00000000 --- a/content/en/docs/3.2/topics/using/headers/headers.md +++ /dev/null @@ -1,76 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Header-based routing - -$productName$ can route to target services based on HTTP headers with the `headers` and `regex_headers` specifications. Multiple mappings with different annotations can be applied to construct more complex routing rules. - -## The `headers` annotation - -The `headers` attribute is a dictionary of `header`: `value` pairs. $productName$ will only allow requests that match the specified `header`: `value` pairs to reach the target service. - -### Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - headers: - x-quote-mode: backend - x-random-header: datawire -``` - -will allow requests to /backend/ to succeed only if the x-quote-mode header has the value backend and the x-random-header has the value `datawire`. - - - 1.x versions of the Ambassador Edge Stack could test for the existence of a header using x-sample-header:true. Since 2.0, the same functionality is achieved by using regex_headers. - - -## Regex headers - -You can also set the `value` of a regex header to `".*"` to test for the existence of a header. - -### Conditional example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-mode -spec: - prefix: /backend/ - service: quote-mode - regex_headers: - x-quote-mode: ".*" - ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-regular -spec: - prefix: /backend/ - service: quote-regular -``` - -will send requests that contain the x-quote-mode header to the quote-mode target, while routing all other requests to the quote-regular target. - -The following mapping will route mobile requests from Android and iPhones to a mobile service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - regex_headers: - user-agent: ".*(iPhone|(a|A)ndroid).*" - prefix: /backend/ - service: quote -``` diff --git a/content/en/docs/3.2/topics/using/headers/host.md b/content/en/docs/3.2/topics/using/headers/host.md deleted file mode 100644 index 5a8dd02c..00000000 --- a/content/en/docs/3.2/topics/using/headers/host.md +++ /dev/null @@ -1,76 +0,0 @@ -# Host headers - -$productName$ supports several different methods for managing the HTTP `Host` header. - -## Using `host` and `host_regex` - -A mapping that specifies the `host` attribute will take effect _only_ if the HTTP `Host` header matches the value in the `host` attribute. If `host_regex` is `true`, the `host` value is taken to be a regular expression. Otherwise, an exact string match is required. - -You may have multiple mappings listing the same resource but different `host` attributes to effect `Host`-based routing. An example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote1 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend-2 -spec: - prefix: /backend/ - host: quote.datawire.io - service: quote2 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend-3 -spec: - prefix: /backend/ - host: "^quote[2-9]\\.datawire\\.io$" - host_regex: true - service: quote3 -``` - -will map requests for `/` to - -- the `quote2` service if the `Host` header is `quote.datawire.io`; -- the `quote3` service if the `Host` header matches `^quote[2-9]\\.datawire\\.io$`; and to -- the `quote1` service otherwise. - -Note that enclosing regular expressions in quotes can be important to prevent backslashes from being doubled. - -## Using `host_rewrite` - -By default, the `Host` header is not altered when talking to the service -- whatever `Host` header the client gave to $productName$ will be presented to the service. For many microservices, this will be fine, but if you use $productName$ to route to services that use the `Host` header for routing, it's likely to fail (legacy monoliths are particularly susceptible to this, as well as external services). You can use `host_rewrite` to force the `Host` header to whatever value that such target services need. - -An example: the default $productName$ configuration includes the following mapping for `httpbin.org`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin -spec: - prefix: /httpbin/ - service: httpbin.org:80 - host_rewrite: httpbin.org -``` - -As it happens, `httpbin.org` is virtually hosted, and it simply _will not_ function without a `Host` header of `httpbin.org`, which means that the `host_rewrite` attribute is necessary here. - -## `host` and `method` - -Internally: - -- the `host` attribute becomes a `header` match on the `:authority` header; and -- the `method` attribute becomes a `header` match on the `:method` header. - -You will see these headers in the diagnostic service if you use the `method` or `host` attributes. diff --git a/content/en/docs/3.2/topics/using/headers/remove_request_headers.md b/content/en/docs/3.2/topics/using/headers/remove_request_headers.md deleted file mode 100644 index 62603756..00000000 --- a/content/en/docs/3.2/topics/using/headers/remove_request_headers.md +++ /dev/null @@ -1,57 +0,0 @@ -# Remove request headers - -$productName$ can remove a list of HTTP headers that would be sent to the upstream from the request. - -## The `remove_request_headers` attribute - -The `remove_request_headers` attribute takes a list of keys used to match to the header. - -`remove_request_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -## Mapping example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - remove_request_headers: - - authorization - service: quote -``` - -will drop the header with key `authorization`. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - remove_request_headers: - - authorization ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - prefix: /backend2/ - service: quote -``` - -This is the same as the mapping example, but the headers will be removed for both mappings. diff --git a/content/en/docs/3.2/topics/using/headers/remove_response_headers.md b/content/en/docs/3.2/topics/using/headers/remove_response_headers.md deleted file mode 100644 index 16b18569..00000000 --- a/content/en/docs/3.2/topics/using/headers/remove_response_headers.md +++ /dev/null @@ -1,57 +0,0 @@ -# Remove response headers - -$productName$ can remove a list of HTTP headers that would be sent to the client in the response (e.g. default `x-envoy-upstream-service-time`). - -## The `remove_response_headers` attribute - -The `remove_response_headers` attribute takes a list of keys used to match to the header. - -`remove_request_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -## Mapping example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - remove_response_headers: - - x-envoy-upstream-service-time - service: quote -``` - -will drop the header with key `x-envoy-upstream-service-time`. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - remove_response_headers: - - x-envoy-upstream-service-time ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - prefix: /backend2/ - service: quote -``` - -This is the same as the mapping example, but the headers will be removed for both mappings. diff --git a/content/en/docs/3.2/topics/using/index.md b/content/en/docs/3.2/topics/using/index.md deleted file mode 100644 index a996249e..00000000 --- a/content/en/docs/3.2/topics/using/index.md +++ /dev/null @@ -1,32 +0,0 @@ -# Using $productName$ - -Application development teams use $productName$ to manage edge policies associated with a specific service. This section of the documentation covers core $productName$ elements that are typically used by the application development team. - -* [Introduction to Mappings](intro-mappings) The `Mapping` resource is the core resource used by every application development team. -* Mapping Configuration: - * [Automatic Retries](retries) - * [Canary Releases](canary) - * [Circuit Breakers](circuit-breakers) - * [Cross Origin Resource Sharing](cors) - * HTTP Headers - * [Header-based Routing](headers/headers) - * [Host Header](headers/host) - * [Adding Request Headers](headers/add_request_headers) - * [Adding Response Headers](headers/add_response_headers) - * [Removing Request Headers](headers/remove_request_headers) - * [Remove Response Headers](headers/remove_response_headers) - * [Query Parameter Based Routing](query_parameters) - * [Keepalive](keepalive) - * Protocols - * [TCP](tcpmappings) - * gRPC, HTTP/1.0, gRPC-Web, WebSockets - * [RegEx-based Routing](prefix_regex) - * [Redirects](redirects) - * [Rewrites](rewrites) - * [Timeouts](timeouts) - * [Traffic Shadowing](shadowing) -* [Advanced Mapping Configuration](mappings) -* Rate Limiting - * [Introduction to Rate Limits](rate-limits/) -* [Developer Portal](../../tutorials/dev-portal-tutorial) -* [Gateway API](gateway-api) diff --git a/content/en/docs/3.2/topics/using/intro-mappings.md b/content/en/docs/3.2/topics/using/intro-mappings.md deleted file mode 100644 index 51656052..00000000 --- a/content/en/docs/3.2/topics/using/intro-mappings.md +++ /dev/null @@ -1,148 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Introduction to the Mapping resource - -$productName$ is designed around a [declarative, self-service management model](../../concepts/gitops-continuous-delivery). The core resource used to support application development teams who need to manage the edge with $productName$ is the `Mapping` resource. - - - Remember that Listener and Host resources are -  required for a functioning $productName$ installation that can route traffic!
- Learn more about Listener.
- Learn more about Host. - - -## Quick example - -At its core a `Mapping` resource maps a `resource` to a `service`: - -| Required attribute | Description | -| :------------------------ | :------------------------ | -| `name` | is a string identifying the `Mapping` (e.g. in diagnostics) | -| [`prefix`](#resources) | is the URL prefix identifying your [resource](#resources) | -| [`service`](#services) | is the name of the [service](#services) handling the resource; must include the namespace (e.g. `myservice.othernamespace`) if the service is in a different namespace than $productName$ | - -These resources are defined as Kubernetes Custom Resource Definitions. Here's a simple example that maps all requests to `/httpbin/` to the `httpbin.org` web service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin-mapping -spec: - prefix: /httpbin/ - service: http://httpbin.org -``` - -## Applying a Mapping resource - -A `Mapping` resource can be managed using the same workflow as any other Kubernetes resources (e.g., `service`, `deployment`). For example, if the above `Mapping` is saved into a file called `httpbin-mapping.yaml`, the following command will apply the configuration directly to $productName$: - -``` -kubectl apply -f httpbin-mapping.yaml -``` - -For production use, the general recommended best practice is to store the file in a version control system and apply the changes with a continuous deployment pipeline. For more detail, see [the Ambassador Operating Model](../../concepts/gitops-continuous-delivery). - -## Extending Mappings - -`Mapping` resources support a rich set of annotations to customize the specific routing behavior. Here's an example service for implementing the CQRS pattern (using HTTP): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-get -spec: - prefix: /cqrs/ - method: GET - service: getcqrs ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-put -spec: - prefix: /cqrs/ - method: PUT - service: putcqrs -``` - -More detail on each of the available annotations are discussed in subsequent sections. - -## Resources - -To $productName$, a `resource` is a group of one or more URLs that all share a common prefix in the URL path. For example: - -``` -https://ambassador.example.com/resource1/foo -https://ambassador.example.com/resource1/bar -https://ambassador.example.com/resource1/baz/zing -https://ambassador.example.com/resource1/baz/zung -``` - -all share the `/resource1/` path prefix, so it can be considered a single resource. On the other hand: - -``` -https://ambassador.example.com/resource1/foo -https://ambassador.example.com/resource2/bar -https://ambassador.example.com/resource3/baz/zing -https://ambassador.example.com/resource4/baz/zung -``` - -share only the prefix `/` -- you _could_ tell $productName$ to treat them as a single resource, but it's probably not terribly useful. - -Note that the length of the prefix doesn't matter: if you want to use prefixes like `/v1/this/is/my/very/long/resource/name/`, go right ahead, $productName$ can handle it. - -Also note that $productName$ does not actually require the prefix to start and end with `/` -- however, in practice, it's a good idea. Specifying a prefix of - -``` -/man -``` - -would match all of the following: - -``` -https://ambassador.example.com/man/foo -https://ambassador.example.com/mankind -https://ambassador.example.com/man-it-is/really-hot-today -https://ambassador.example.com/manohmanohman -``` - -which is probably not what was intended. - -## Services - -$productName$ routes traffic to a `service`. A `service` is defined as: - -``` -[scheme://]service[.namespace][:port] -``` - -Where everything except for the `service` is optional. - -- `scheme` can be either `http` or `https`; if not present, the default is `http`. -- `service` is the name of a service (typically the service name in Kubernetes or Consul); it is not allowed to contain the `.` character. -- `namespace` is the namespace in which the service is running. Starting with $productName$ 1.0.0, if not supplied, it defaults to the namespace in which the Mapping resource is defined. The default behavior can be configured using the [`ambassador` Module](../../running/ambassador). When using a Consul resolver, `namespace` is not allowed. -- `port` is the port to which a request should be sent. If not specified, it defaults to `80` when the scheme is `http` or `443` when the scheme is `https`. Note that the [resolver](../../running/resolvers) may return a port in which case the `port` setting is ignored. - -Note that while using `service.namespace.svc.cluster.local` may work for Kubernetes resolvers, the preferred syntax is `service.namespace`. - -## Best practices for configuration - -$productName$'s configuration is assembled from multiple YAML blocks which are managed by independent application teams. This implies: - -- $productName$'s configuration should be under version control. - - While you can always read back the $productName$'s configuration from Kubernetes or its diagnostic service, the $productName$ will not do versioning for you. - -- Be aware that the $productName$ tries to not start with a broken configuration, but it's not perfect. - - Gross errors will result in $productName$ refusing to start, in which case `kubectl logs` will be helpful. However, it's always possible to e.g. map a resource to the wrong service, or use the wrong `rewrite` rules. $productName$ can't detect that on its own, although its diagnostic pages can help you figure it out. - -- Be careful of mapping collisions. - - If two different developers try to map `/user/` to something, this can lead to unexpected behavior. $productName$'s canary-deployment logic means that it's more likely that traffic will be split between them than that it will throw an error -- again, the diagnostic service can help you here. - -**Note:** Unless specified, mapping attributes cannot be applied to any other resource type. diff --git a/content/en/docs/3.2/topics/using/keepalive.md b/content/en/docs/3.2/topics/using/keepalive.md deleted file mode 100644 index d75e96ba..00000000 --- a/content/en/docs/3.2/topics/using/keepalive.md +++ /dev/null @@ -1,70 +0,0 @@ -# Keepalive - -Keepalive option indicates whether `SO_KEEPALIVE` on the socket should be enabled. - -## Keepalive configuration - -Keepalive configuration can be set for all $productName$ mappings in the [`ambassador Module`](../../running/ambassador) or set per [`Mapping`](../mappings). - -The `keepalive` attribute configures keepalive. The following fields are supported: - -```yaml -keepalive: - idle_time: - interval: - probes: -``` - -### `idle_time` - -(Default: `7200`) The number of seconds a connection needs to be idle before keep-alive probes start being sent. - -### `interval` - -(Default: `75`) The number of seconds between keep-alive probes. - -### `probes` - -(Default: `9`) is the maximum number of keepalive probes to send without response before deciding the connection is dead. - -## Examples - -Keepalive probes defined on a single mapping: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - keepalive: - idle_time: 100 - interval: 10 - probes: 9 -``` - -A global keepalive configuration: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - keepalive: - idle_time: 100 - interval: 10 - probes: 9 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote -``` diff --git a/content/en/docs/3.2/topics/using/mappings.md b/content/en/docs/3.2/topics/using/mappings.md deleted file mode 100644 index f930fc62..00000000 --- a/content/en/docs/3.2/topics/using/mappings.md +++ /dev/null @@ -1,189 +0,0 @@ -# Advanced Mapping configuration - -$productName$ is designed so that the author of a given Kubernetes service can easily and flexibly configure how traffic gets routed to the service. The core abstraction used to support service authors is a mapping, which maps a target backend service to a given host or prefix. For Layer 7 protocols such as HTTP, gRPC, or WebSockets, the `Mapping` resource is used. For TCP, the `TCPMapping` resource is used. - -$productName$ _must_ have one or more mappings defined to provide access to any services at all. The name of the mapping must be unique. - -## System-wide defaults for Mappings - -Certain aspects of mappings can be set system-wide using the `defaults` element of the `ambassador Module`: -see [using defaults](../../using/defaults) for more information. The `Mapping` element will look first in -the `httpmapping` default class. - -## Mapping evaluation order - -$productName$ sorts mappings such that those that are more highly constrained are evaluated before those less highly constrained. The prefix length, the request method, constraint headers, and query parameters are all taken into account. - -If absolutely necessary, you can manually set a `precedence` on the mapping (see below). In general, you should not need to use this feature unless you're using the `regex_headers` or `host_regex` matching features. If there's any question about how $productName$ is ordering rules, the diagnostic service is a good first place to look: the order in which mappings appear in the diagnostic service is the order in which they are evaluated. - -## Optional fallback Mapping - -$productName$ will respond with a `404 Not Found` to any request for which no mapping exists. If desired, you can define a fallback "catch-all" mapping so all unmatched requests will be sent to an upstream service. - -For example, defining a mapping with only a `/` prefix will catch all requests previously unhandled and forward them to an external service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: catch-all -spec: - prefix: / - service: https://www.getambassador.io -``` - -### Using `precedence` - -$productName$ sorts mappings such that those that are more highly constrained are evaluated before those less highly constrained. The prefix length, the request method, and the constraint headers are all taken into account. These mechanisms, however, may not be sufficient to guarantee the correct ordering when regular expressions or highly complex constraints are in play. - -For those situations, a `Mapping` can explicitly specify the `precedence`. A `Mapping` with no `precedence` is assumed to have a `precedence` of 0; the higher the `precedence` value, the earlier the `Mapping` is attempted. - -If multiple `Mapping`s have the same `precedence`, $productName$'s normal sorting determines the ordering within the `precedence`; however, there is no way that $productName$ can ever sort a `Mapping` with a lower `precedence` ahead of one at a higher `precedence`. - -### Using `tls` - -To originate TLS, use a `service` with an `https://` prefix. By itself, this will cause $productName$ to originate TLS without presenting a client certificate to the upstream service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-no-cert -spec: - prefix: /prefix/ - service: https://upstream/ -``` - -If you do need to supply a client certificate, you will also need to set `tls` to the name of a defined TLS context. The client certificate given in that context will be presented to the upstream service. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-with-cert -spec: - prefix: /prefix/ - service: https://upstream/ - tls: upstream-cert-context -``` - -(If `tls` is present, $productName$ will originate TLS even if the `service` does not have an `https://` prefix.) - -### Using `cluster_tag` - -If the `cluster_tag` attribute is present, its value will be prepended to cluster names generated from -the `Mapping`. This provides a simple mechanism for customizing the `cluster` name when working with metrics. - -## Using `dns_type` - -If the `dns_type` attribute is present, its value will determine how the DNS is used when locating the upstream service. Valid values are: - -- `strict_dns` (the default): The DNS result is assumed to define the exact membership of the cluster. For example, if DNS returns three IP addresses, the cluster is assumed to have three distinct upstream hosts. If a successful DNS query returns no hosts, the cluster is assumed to be empty. `strict_dns` makes sense for situations like a Kubernetes service, where DNS resolution is fast and returns a relatively small number of IP addresses. - -- `logical_dns`: Instead of assuming that the DNS result defines the full membership of the cluster, every new connection simply uses the first IP address returned by DNS. `logical_dns` makes sense for a service with a large number of IP addresses using round-robin DNS for upstream load balancing: typically each DNS query returns a different first result, and it is not necessarily possible to know the full membership of the cluster. With `logical_dns`, no attempt is made to garbage-collect connections: they will stay open until the upstream closes them. - -If `dns_type` is not given, `strict_dns` is the default, as this is the most conservative choice. When interacting with large web services with many IP addresses, switching to `logical_dns` may be a better choice. For more on the different types of DNS, see the [`strict_dns` Envoy documentation] or the [`logical_dns` Envoy documentation]. - -[`strict_dns` Envoy documentation]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/service_discovery#strict-dns -[`logical_dns` Envoy documentation]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/service_discovery#logical-dns - - -## Namespaces and Mappings - -If `AMBASSADOR_NAMESPACE` is correctly set, $productName$ can map to services in other namespaces by taking advantage of Kubernetes DNS: - -- `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. - -### Linkerd interoperability (`add_linkerd_headers`) - -When using Linkerd, requests going to an upstream service need to include the `l5d-dst-override` header to ensure that Linkerd will route them correctly. Setting `add_linkerd_headers` does this automatically, based on the `service` attribute in the `Mapping`. - -If `add_linkerd_headers` is not specified for a given `Mapping`, the default is taken from the `ambassador`[Module](../../running/ambassador). The overall default is `false`: you must explicitly enable `add_linkerd_headers` for $productName$ to add the header for you (although you can always add it yourself with `add_request_headers`, of course). - -### "Upgrading" to non-HTTP protocols (`allow_upgrade`) - -HTTP has [a mechanism][upgrade-mechanism] where the client can say -`Connection: upgrade` / `Upgrade: PROTOCOL` to switch ("upgrade") from -the current HTTP version to a different one, or even a different -protocol entirely. $productName$ itself understands and can handle the -different HTTP versions, but for other protocols you need to tell -$productName$ to get out of the way, and let the client speak that -protocol directly with your upstream service. You can do this by -setting the `allow_upgrade` field to a case-insensitive list of -protocol names $productName$ will allow switching to from HTTP. After -the upgrade, $productName$ does not interpret the traffic, and behaves -similarly to how it does for `TCPMapping`s. - -[upgrade-mechanism]: https://tools.ietf.org/html/rfc7230#section-6.7 - -This "upgrade" mechanism is a useful way of adding HTTP-based -authentication and access control to another protocol that might not -support authentication; for this reason the designers of the WebSocket -protocol made this "upgrade" mechanism the *only* way of initiating a -WebSocket connection. In a Mapping for an upstream service that -supports WebSockets, you would write - -```yaml -allow_upgrade: -- websocket -``` - -The Kubernetes apiserver itself uses this "upgrade" mechanism to -perform HTTP authentication before switching to SPDY for endpoint used -by `kubectl exec`; if you wanted to use $productName$ to expose the -Kubernetes apiserver such that `kubectl exec` functions, you would -write - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: apiserver -spec: - hostname: "*" - service: https://kubernetes.default - prefix: / - allow_upgrade: - - spdy/3.1 -``` - -There is a deprecated setting `use_websocket`; setting `use_websocket: -true` is equivalent to setting `allow_upgrade: ["websocket"]`. - -## DNS configuration for Mappings - -`respect_dns_ttl` can be set to `true` to force the DNS refresh rate for this `Mapping` to be set to the record’s TTL obtained from DNS resolution. -- Allowed values: `true` or `false` -- Default: `false` - - -`dns_type` can be used to configure the service discovery type between Strict DNS and Logical DNS. You can -- Allowed values: - - `strict_dns`: Ambassador will continuously and asynchronously resolve the specified DNS targets. - - `logical_dns`: Similar to `strict_dns`, but only uses the first IP address returned when a new connection needs to be initiated and Connections are never drained. More optimal for large scale web services that must be accessed via DNS. -- Default: `strict_dns` - - -For more information on the differences between dns types, see [the Envoy documentation for service discovery](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/service_discovery.html). - -> **Note:** When the [endpoint resolver](../../running/resolvers/#the-kubernetes-endpoint-resolver) is used in a `Mapping`, `dns_type` will be ignored in favor of the endpoint resolver's service discovery. - - - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: dnsoverwrite -spec: - service: quote - prefix: /backend/ - dns_type: logical_dns - respect_dns_ttl: true -``` diff --git a/content/en/docs/3.2/topics/using/method.md b/content/en/docs/3.2/topics/using/method.md deleted file mode 100644 index 94185dcd..00000000 --- a/content/en/docs/3.2/topics/using/method.md +++ /dev/null @@ -1,26 +0,0 @@ -# Method-based routing - -$productName$ supports routing based on the HTTP method and regular expression. - -## Using `method` - -The `method` annotation specifies the specific HTTP method for a mapping. The value of the `method` annotation must be in all upper case. - -For example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: get -spec: - hostname: "*" - prefix: /backend/get_only/ - method: GET - service: quote -``` - -## Using `method_regex` - -When `method_regex` is set to `true`, the value of the `method` annotation will be interpreted as a regular expression. diff --git a/content/en/docs/3.2/topics/using/prefix_regex.md b/content/en/docs/3.2/topics/using/prefix_regex.md deleted file mode 100644 index 04a6e4b8..00000000 --- a/content/en/docs/3.2/topics/using/prefix_regex.md +++ /dev/null @@ -1,25 +0,0 @@ -# Prefix regex - -## Using `prefix` and `prefix_regex` - -When the `prefix_regex` attribute is set to `true`, $productName$ configures a [regex route](https://www.envoyproxy.io/docs/envoy/v1.5.0/api-v1/route_config/route#route) instead of a prefix route in Envoy. **This means the entire path must match the regex specified, not only the prefix.** - -## Example with a version in the URL - -If the version is a path parameter and the resources are served by different services, then - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: qotm -spec: - prefix: "/(v1|v2)/qotm/.*" - prefix_regex: true - service: qotm -``` - -will map requests to both `/v1` and `/v2` to the `qotm` service. - -Note that enclosing regular expressions in quotes can be important to prevent backslashes from being doubled. diff --git a/content/en/docs/3.2/topics/using/query-parameters.md b/content/en/docs/3.2/topics/using/query-parameters.md deleted file mode 100644 index 6b880fd4..00000000 --- a/content/en/docs/3.2/topics/using/query-parameters.md +++ /dev/null @@ -1,69 +0,0 @@ -# Query parameter-based routing - -$productName$ can route to target services based on HTTP query parameters with the `query_parameters` and `regex_query_parameters` specifications. Multiple mappings with different annotations can be applied to construct more complex routing rules. - -## The `query_parameters` annotation - -The `query_parameters` attribute is a dictionary of `query_parameter`: `value` pairs. $productName$ will only allow requests that match the specified `query_parameter`: `value` pairs to reach the target service. - -You can also set the `value` of a query parameter to `true` to test for the existence of a query parameter. - -### A basic example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - query_parameters: - quote-mode: backend - random-query-parameter: datawire -``` - -This will allow requests to /backend/ to succeed only if the `quote-mode` query parameter has the value `backend` and the `random-query-parameter` has the value `datawire`. - -## `regex_query_parameters` - -The following mapping will route requests with the `quote-mode` header that contain values that match the regex. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - regex_query_parameters: - quote-mode: "^[a-z].*" - prefix: /backend/ - service: quote -``` - -### A conditional example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-mode -spec: - prefix: /backend/ - service: quote-mode - regex_query_parameters: - quote-mode: .* ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-regular -spec: - prefix: /backend/ - service: quote-regular -``` - -This will send requests that contain the `quote-mode` query parameter (with any value) to the `quote-mode` target, while routing all other requests to the `quote-regular` target. diff --git a/content/en/docs/3.2/topics/using/rate-limits/index.md b/content/en/docs/3.2/topics/using/rate-limits/index.md deleted file mode 100644 index b65f8c5d..00000000 --- a/content/en/docs/3.2/topics/using/rate-limits/index.md +++ /dev/null @@ -1,199 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Basic rate limiting - -Rate limiting in $productName$ is composed of two parts: - -* The [`RateLimitService`](../../running/services/rate-limit-service) resource tells $productName$ what external service - to use for rate limiting. - - If $productName$ cannot contact the rate limit service, it will allow the request to be processed as if there were no rate limit service configuration. - -* _Labels_ that get attached to requests. A label is basic metadata that - is used by the `RateLimitService` to decide which limits to apply to - the request. - - - These labels require Mapping resources with apiVersion - getambassador.io/v2 or newer — if you're updating an old installation, check the - apiVersion! - - -Labels are grouped according to _domain_ and _group_: - -```yaml -labels: - "domain1": - - "group1": - - "my_label_specifier_1" - - "my_label_specifier_2" - - "group2": - - "my_label_specifier_3" - - "my_label_specifier_4" - "domain2": - - ... -``` - -The names of domains and groups are not interpreted by $productName$ in any way: -they are solely there to help configuration authors remember the different groupings. -Note that **at present, rate limiting supports just one domain**: the name of the -domain must be configured in the [`RateLimitService`](../../running/services/rate-limit-service). - - - -## Attaching labels to requests - -There are two ways of setting labels on a request: - -1. You can set labels on an individual [`Mapping`](../mappings). These labels - will only apply to requests that use that `Mapping`. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Mapping - metadata: - name: foo-mapping - spec: - hostname: "*" - prefix: /foo/ - service: foo - labels: - "domain1": - - "group1": - - "my_label_specifier_1" - - "my_label_specifier_2" - - "group2": - - "my_label_specifier_3" - - "my_label_specifier_4" - "domain2": - - ... - ``` - -2. You can set global labels in the [`ambassador` `Module`](../../running/ambassador). - These labels will apply to _every_ request that goes through $productName$. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - spec: - config: - default_labels: - "domain1": - defaults: - - "my_label_specifier_a" - - "my_label_specifier_b" - "domain2": - defaults: - - "my_label_specifier_c" - - "my_label_specifier_d" - ``` - - If a `Mapping` and the defaults both give label groups for the same domain, the - default labels are prepended to each label group from the `Mapping`. If the `Mapping` - does not give any labels for that domain, the global labels are placed into a new - label group named "default" for that domain. - -Each label group is a list of labels; each label is a key/value pair. Since the label -group is a list rather than a map: -- it is possible to have multiple labels with the same key, and -- the order of labels matters. - -> Note: The terminology used by the Envoy documentation differs from -> the terminology used by $productName$: -> -> | $productName$ | Envoy | -> |-----------------|-------------------| -> | label group | descriptor | -> | label | descriptor entry | -> | label specifier | rate limit action | - -The `Mapping`s' listing of the groups of specifiers have names for the -groups; the group names are useful for humans dealing with the YAML, -but are ignored by $productName$, all $productName$ cares about are the -*contents* of the groupings of label specifiers. - -There are 5 types of label specifiers in $productName$: - - - -1. `source_cluster` - - ```yaml - source_cluster: - key: source_cluster - ``` - - Sets the label `source_cluster=«Envoy source cluster name»"`. The Envoy - source cluster name is the name of the Envoy cluster that the request came - in on. - - The syntax of this label currently _requires_ `source_cluster: {}`. - -2. `destination_cluster` - - ```yaml - destination_cluster: - key: destination_cluster - ``` - - Sets the label `destination_cluster=«Envoy destination cluster name»"`. The Envoy - destination cluster name is the name of the Envoy cluster to which the `Mapping` - routes the request. You can get the name for a cluster from the - [diagnostics service](../../running/diagnostics). - - The syntax of this label currently _requires_ `destination_cluster: {}`. - -3. `remote_address` - - ```yaml - remote_address: - key: remote_address - ``` - - Sets the label `remote_address=«IP address of the client»"`. The IP address of - the client will be taken from the `X-Forwarded-For` header, to correctly manage - situations with L7 proxies. This requires that $productName$ be correctly - [configured to communicate](../../../howtos/configure-communications). - - The syntax of this label currently _requires_ `remote_address: {}`. - -4. `request_headers` - - ```yaml - request_headers: - header_name: "header-name" - key: mykey - ``` - - If a header named `header-name` is present, set the label `mykey=«value of the header»`. - If no header named `header-name` is present, **the entire label group is dropped**. - -5. `generic_key` - - ```yaml - generic_key: - key: mykey - value: myvalue - ``` - - Sets the label `«mykey»=«myval»`. Note that supplying a `key` is supported only - with the Envoy V3 API. - -## Rate limiting requests based on their labels - -This is determined by your `RateLimitService` implementation. See the -[Basic Rate Limiting tutorial](../../../howtos/rate-limiting-tutorial) for an -example `RateLimitService` implementation for $productName$. - -If you'd rather not write your own `RateLimitService` implementation, -$AESproductName$ provides a `RateLimitService` implementation that is -configured by a `RateLimit` custom resource. See the -[$AESproductName$ RateLimit Reference](/docs/edge-stack/latest/topics/using/rate-limits/rate-limits/) -for more information. diff --git a/content/en/docs/3.2/topics/using/redirects.md b/content/en/docs/3.2/topics/using/redirects.md deleted file mode 100644 index f55c467d..00000000 --- a/content/en/docs/3.2/topics/using/redirects.md +++ /dev/null @@ -1,142 +0,0 @@ -# Redirects - -$productName$ can perform 3xx redirects on `Mapping`s to a different host, with various options to redirect the path and to return a different 3xx response code instead of the default 301. - -## Schema - -| Name | Type | Description | -| --- | --- | --- | -| `spec.host_redirect` | Boolean | This is *required* to be set to `true` to use any type of redirect, otherwise the request will be proxied instead of redirected. | -| `spec.path_redirect` | String | Optional, changes the path for the redirect. | -| `spec.prefix_redirect` | String | Optional, matches the `prefix` value and replaces it with the `prefix_redirect` value. | -| `spec.regex_redirect` | String | Optional, uses regex to match and replace the `prefix` value. | -| `spec.redirect_response_code` | Integer | Optional, changes the response code from the default 301, valid values are 301, 302, 303, 307, and 308. | -| `spec.config. x_forwarded_proto_redirect` | Boolean | Redirect only the originating HTTP requests to HTTPS, allowing the originating HTTPS requests to pass through. | -| `spec.config. use_remote_address` | Boolean | Required to be set to `false` to use the `x_forwarded_proto_redirect` feature. | - -## Examples - -### Basic redirect - -To effect any type of HTTP `Redirect`, the `Mapping` *must* set `host_redirect` to `true`, with `service` set to the host to which the client should be redirected: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - prefix: /redirect/ - service: httpbin.org - host_redirect: true - hostname: '*' -``` - -Using this `Mapping`, a request to `http://$AMBASSADOR_URL/redirect/` will be redirected to `http://httpbin.org/redirect/`. - -> As always with $productName$, the trailing `/` on any URL with a -`Mapping` is required! - -### Path redirect - -The `Mapping` may optionally also set additional properties to customize the behavior of the HTTP redirect response. - -To also change the path portion of the URL during the redirect, set `path_redirect`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - hostname: '*' - prefix: /redirect/ - service: httpbin.org - host_redirect: true - path_redirect: /ip -``` - -Here, a request to `http://$AMBASSADOR_URL/redirect/` will be redirected to `http://httpbin.org/ip/`. - -### Prefix redirect - -To change only a prefix of the path portion of the URL, set `prefix_redirect`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - hostname: '*' - prefix: /redirect/path/ - service: httpbin.org - host_redirect: true - prefix_redirect: /ip -``` - -Now, a request to `http://$AMBASSADOR_URL/redirect/path/` will be redirected to `http://httpbin.org/ip/`. The prefix `/redirect/path/` was matched and replaced with `/ip/`. - -### Regex redirect - -`regex_redirect` matches a regular expression to replace instead of a fixed prefix. -[See more information about using regex with $productName$](../rewrites/#regex_rewrite). - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - prefix: /foo/ - service: httpbin.org - host_redirect: true - regex_redirect: - pattern: '/foo/([0-9]*)/list' - substitution: '/bar/\1' -``` -A request to `http://$AMBASSADOR_URL/foo/12345/list` will be redirected to -`http://$AMBASSADOR_URL/bar/12345`. - -### Redirect response code - -To change the HTTP response code return by $productName$, set `redirect_reponse_code`. If this is not set, 301 is returned by default. Valid values include 301, 302, 303, 307, and 308. This -can be used with any type of redirect. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - prefix: /ip/ - service: httpbin.org - host_redirect: true - redirect_response_code: 302 -``` - -A request to `http://$AMBASSADOR_URL/ip/` will result in an HTTP 302 redirect to `http://httpbin.org/ip`. - -### X-FORWARDED-PROTO redirect - -In cases when TLS is being terminated at an external layer 7 load balancer, then you would want to redirect only the originating HTTP requests to HTTPS, and let the originating HTTPS requests pass through. - -This distinction between an originating HTTP request and an originating HTTPS request is done based on the `X-FORWARDED-PROTO` header that the external layer 7 load balancer adds to every request it forwards after TLS termination. - -To enable this `X-FORWARDED-PROTO` based HTTP to HTTPS redirection, add a `x_forwarded_proto_redirect: true` field to `ambassador Module`'s configuration. Note that when this feature is enabled `use_remote_address` MUST be set to false. - -An example configuration is as follows - - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - x_forwarded_proto_redirect: true - use_remote_address: false -``` - -Note: Setting `x_forwarded_proto_redirect: true` will impact all your $productName$ mappings. Every HTTP request to $productName$ will only be allowed to pass if it has an `X-FORWARDED-PROTO: https` header. diff --git a/content/en/docs/3.2/topics/using/retries.md b/content/en/docs/3.2/topics/using/retries.md deleted file mode 100644 index d018ab59..00000000 --- a/content/en/docs/3.2/topics/using/retries.md +++ /dev/null @@ -1,84 +0,0 @@ -# Automatic retries - -Sometimes requests fail. When these requests fail for transient issues, $productName$ can automatically retry the request. - -Retry policy can be set for all $productName$ mappings in the [`ambassador Module`](../../running/ambassador), or set per [`Mapping`](../mappings). Generally speaking, you should set `retry_policy` on a per mapping basis. Global retries can easily result in unexpected cascade failures. - -> Note that when setting `retry_policy`, adjusting `max_retries` in the [circuit breaker](https://www.getambassador.io/docs/edge-stack/pre-release/topics/using/circuit-breakers/) configuration should also be considered in order to account for all desired retries. - -## Configuring retries - -The `retry_policy` attribute configures automatic retries. The following fields are supported: - -```yaml -retry_policy: - retry_on: - num_retries: - per_try_timeout: -``` - -### `retry_on` - -(Required) Specifies the condition under which $productName$ retries a failed request. - -| Value | Description | -| --- | --- | -|`5xx`| Retries if the upstream service responds with any 5xx code or does not respond at all -|`gateway-error`| Similar to a `5xx` but only applies to a 502, 503, or 504 response -|`connect-failure`| Retries on a connection failure to the upstream service (included in `5xx`) -|`retriable-4xx`| Retries on a retriable 4xx response (currently only 409) -|`refused-stream`| Retires if the upstream service sends a REFUSED_STREAM error (included in `5xx`) -|`retriable-status-codes`| Retries based on status codes set in the `x-envoy-retriable-status-codes` header. If that header isn't set, $productName$ will not retry the request. - - For more details on each of these values, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/v1.9.0/configuration/http_filters/router_filter#x-envoy-retry-on). - -### `num_retries` - -(Default: 1) Specifies the number of retries to execute for a failed request. - -### `per_try_timeout` - -(Default: global request timeout) Specify the timeout for each retry. Must be in seconds or nanoseconds, e.g., `1s`, `1500ns`. - -## Examples - -A per mapping retry policy: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - retry_policy: - retry_on: "5xx" - num_retries: 10 -``` - -A global retry policy (not recommended): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - retry_policy: - retry_on: "retriable-4xx" - num_retries: 4 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - hostname: '*' -``` diff --git a/content/en/docs/3.2/topics/using/rewrites.md b/content/en/docs/3.2/topics/using/rewrites.md deleted file mode 100644 index 44d0a961..00000000 --- a/content/en/docs/3.2/topics/using/rewrites.md +++ /dev/null @@ -1,100 +0,0 @@ -# Rewrites - -Once $productName$ uses a prefix to identify the service to which a given request should be passed, it can rewrite the URL before handing it off to the service. - -There are two approaches for rewriting: `rewrite` for simpler scenarios and `regex_rewrite` for more advanced rewriting. - -**Please note that** only one of these two can be configured for a mapping **at the same time**. As a result $productName$ ignores `rewrite` when `regex_rewrite` is provided. - -## `rewrite` - -By default, the `prefix` is rewritten to `/`, so e.g., if we map `/backend-api/` to the service `service1`, then - - -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/content/en/docs/3.2/topics/using/shadowing.md b/content/en/docs/3.2/topics/using/shadowing.md deleted file mode 100644 index dd95fbba..00000000 --- a/content/en/docs/3.2/topics/using/shadowing.md +++ /dev/null @@ -1,78 +0,0 @@ -# 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. - -![Shadowing](../../images/shadowing.png) - -## 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/content/en/docs/3.2/topics/using/tcpmappings.md b/content/en/docs/3.2/topics/using/tcpmappings.md deleted file mode 100644 index f246e799..00000000 --- a/content/en/docs/3.2/topics/using/tcpmappings.md +++ /dev/null @@ -1,300 +0,0 @@ -# `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/content/en/docs/3.2/topics/using/timeouts.md b/content/en/docs/3.2/topics/using/timeouts.md deleted file mode 100644 index ae004102..00000000 --- a/content/en/docs/3.2/topics/using/timeouts.md +++ /dev/null @@ -1,66 +0,0 @@ -# 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/content/en/docs/3.2/tutorials/dev-portal-tutorial.md b/content/en/docs/3.2/tutorials/dev-portal-tutorial.md deleted file mode 100644 index d3c0d0a8..00000000 --- a/content/en/docs/3.2/tutorials/dev-portal-tutorial.md +++ /dev/null @@ -1,29 +0,0 @@ -# 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:///docs/` to see the -publicly visible Developer Portal. Make sure you include the trailing `/`. -This is a fully customizable portal that you can share with third parties who -need information about your APIs. diff --git a/content/en/docs/3.2/tutorials/getting-started.md b/content/en/docs/3.2/tutorials/getting-started.md deleted file mode 100644 index 80263119..00000000 --- a/content/en/docs/3.2/tutorials/getting-started.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: "Getting Started with $productName$" -description: "Learn how to install $productName$ with either Helm or kubectl to get started routing traffic from the edge of your Kubernetes cluster to your services..." ---- - -import Alert from '@material-ui/lab/Alert'; -import GettingStartedEmissary21Tabs from './gs-tabs' - -# $productName$ quick start - -
-

Contents

- -- [1. Installation](#1-installation) - - [Connecting your installation to Ambassador Cloud](#connecting-your-installation-to-ambassador-cloud) -- [2. Routing traffic from the edge](#2-routing-traffic-from-the-edge) -- [What's next?](#img-classos-logo-srcimageslogopng-whats-next) - -
- -## 1. Installation - -We'll start by installing $productName$ into your cluster. - -**We recommend using Helm** but there are other options below to choose from. - - - -### Connecting your installation to Ambassador Cloud - -Now is a great moment to connect your new installation to Ambassador Cloud in order to fully leverage the power of $productName$ and the Developer Control Plane (DCP). - -1. Log in to [Ambassador Cloud](https://app.getambassador.io/cloud/services/) with GitHub, GitLab or Google and select your team account. - -2. At the top, click **Add Services** then click **Connection Instructions** in the "Connect your installation" section. - -3. Follow the prompts to name the cluster and click **Generate a Cloud Token**. - -4. Follow the prompts to install the cloud token into your cluster. - -5. When the token installation completes, your services will be listed in the DCP. - -Success! At this point, you have installed $productName$. Now let's get some traffic flowing to your services. - -## 2. Routing traffic from the edge - -$productName$ uses Kubernetes Custom Resource Definitions (CRDs) to declaratively define its desired state. The workflow you are going to build uses a simple demo app, a **`Listener` CRD**, and a **`Mapping` CRD**. The `Listener` CRD tells $productName$ what port to listen on, and the `Mapping` CRD tells $productName$ how to route incoming requests by host and URL path from the edge of your cluster to Kubernetes services. - -1. Start by creating a `Listener` resource for HTTP on port 8080: - - ``` - kubectl apply -f - < - This 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.
-
- Learn more about Listener.
- Learn more about Host. - - -2. Apply the YAML for the "Quote" service. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/quickstart/qotm.yaml - ``` - - The Service and Deployment are created in your default namespace. You can use 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](#connecting-your-installation-to-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` - - ![Mapping editor](../images/mapping-editor.png) - - 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 - <Victory! You have created your first $productName$ 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/content/en/docs/3.2/tutorials/gs-tabs.js b/content/en/docs/3.2/tutorials/gs-tabs.js deleted file mode 100644 index eb392504..00000000 --- a/content/en/docs/3.2/tutorials/gs-tabs.js +++ /dev/null @@ -1,131 +0,0 @@ -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 ( - - ); -} - -TabPanel.propTypes = { - children: PropTypes.node, - index: PropTypes.any.isRequired, - value: PropTypes.any.isRequired, -}; - -function a11yProps(index) { - return { - id: `simple-tab-${index}`, - 'aria-controls': `simple-tabpanel-${index}`, - }; -} - -const useStyles = makeStyles((theme) => ({ - root: { - flexGrow: 1, - backgroundColor: 'transparent', - }, -})); - -export default function GettingStartedEmissary21Tabs(props) { - const version = props.version; - const classes = useStyles(); - const [value, setValue] = React.useState(0); - - const handleChange = (event, newValue) => { - setValue(newValue); - }; - - return ( -
- - - } - label="Helm 3" - {...a11yProps(0)} - style={{ minWidth: '10%', textTransform: 'none' }} - /> - } - label="Kubernetes YAML" - {...a11yProps(1)} - style={{ minWidth: '10%', textTransform: 'none' }} - /> - - - - {/*Helm 3 install instructions*/} - - - {'# Add the Repo:' + - '\n' + - 'helm repo add datawire https://app.getambassador.io' + - '\n' + - 'helm repo update' + - '\n \n' + - '# Create Namespace and Install:' + - '\n' + - 'kubectl create namespace emissary && \\' + - '\n' + - `kubectl apply -f https://app.getambassador.io/yaml/emissary/${version}/emissary-crds.yaml` + - '\n' + - 'kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system' + - '\n' + - 'helm install emissary-ingress --namespace emissary datawire/emissary-ingress && \\' + - '\n' + - 'kubectl -n emissary wait --for condition=available --timeout=90s deploy -lapp.kubernetes.io/instance=emissary-ingress' + - '\n'} - - - - - {/*YAML install instructions*/} - - - {'kubectl create namespace emissary && \\' + - '\n' + - `kubectl apply -f https://app.getambassador.io/yaml/emissary/${version}/emissary-crds.yaml && \\` + - '\n' + - 'kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system' + - '\n' + - `kubectl apply -f https://app.getambassador.io/yaml/emissary/${version}/emissary-emissaryns.yaml && \\` + - '\n' + - 'kubectl -n emissary wait --for condition=available --timeout=90s deploy -lproduct=aes' + - '\n'} - - -
- ); -} diff --git a/content/en/docs/3.2/tutorials/gs-tabs2.js b/content/en/docs/3.2/tutorials/gs-tabs2.js deleted file mode 100644 index bfd95047..00000000 --- a/content/en/docs/3.2/tutorials/gs-tabs2.js +++ /dev/null @@ -1,174 +0,0 @@ -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'; - -function TabPanel(props) { - const { children, value, index, ...other } = props; - - return ( - - ); -} - -TabPanel.propTypes = { - children: PropTypes.node, - index: PropTypes.any.isRequired, - value: PropTypes.any.isRequired, -}; - -function a11yProps(index) { - return { - id: `simple-tab-${index}`, - 'aria-controls': `simple-tabpanel-${index}`, - }; -} - -const useStyles = makeStyles((theme) => ({ - root: { - flexGrow: 1, - backgroundColor: 'transparent', - }, -})); - -export default function SimpleTabs() { - const classes = useStyles(); - const [value, setValue] = React.useState(0); - - const handleChange = (event, newValue) => { - setValue(newValue); - }; - - return ( -
- - - - - - - - - - {/*Helm 3 token install instructions*/} - Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Helm. The slideout contains instructions with a - unique cloud-connect-token that is used to connect your - cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'helm upgrade ambassador --namespace ambassador datawire/ambassador \\' + - '\n' + - ' --set agent.cloudConnectToken=$TOKEN && \\' + - '\n' + - 'kubectl -n ambassador wait --for condition=available --timeout=90s deploy -lproduct=aes'} - - - - - {/*Helm 2 token install instructions*/} - Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Helm. The slideout contains instructions with a - unique cloud-connect-token that is used to connect your - cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'helm upgrade --namespace ambassador ambassador datawire/ambassador \\' + - '\n' + - ' --set crds.create=false --set agent.cloudConnectToken=$TOKEN && \\' + - '\n' + - 'kubectl -n ambassador wait --for condition=available --timeout=90s deploy -lproduct=aes'} - - - - - {/*YAML token install instructions*/} - Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Kubernetes YAML. The slideout contains instructions - with a unique cloud-connect-token that is used to connect - your cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'kubectl create configmap -n ambassador ambassador-agent-cloud-token \\' + - '\n' + - ' --from-literal=CLOUD_CONNECT_TOKEN=$TOKEN'} - - - - - {/*edgectl token install instructions*/} - Connecting $productName$ that was installed via edgectl is - identical to the Kubernetes YAML procedure. -
- Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Kubernetes YAML. The slideout contains instructions - with a unique cloud-connect-token that is used to connect - your cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'kubectl create configmap -n ambassador ambassador-agent-cloud-token \\' + - '\n' + - ' --from-literal=CLOUD_CONNECT_TOKEN=$TOKEN'} - - -
- ); -} diff --git a/content/en/docs/3.2/tutorials/quickstart-demo.md b/content/en/docs/3.2/tutorials/quickstart-demo.md deleted file mode 100644 index 70cbce8b..00000000 --- a/content/en/docs/3.2/tutorials/quickstart-demo.md +++ /dev/null @@ -1,176 +0,0 @@ -# $productName$ Tutorial - -In this article, you will explore some of the key features of $productName$ by walking through an example workflow and exploring the -Edge Policy Console. - -## Prerequisites - -You must have [$productName$ installed](../getting-started/) in your -Kubernetes cluster. - -## Routing Traffic from the Edge - -Like any other Kubernetes object, Custom Resource Definitions (CRDs) are used to -declaratively define $productName$’s desired state. The workflow you are going to -build uses a sample deployment and the `Mapping` CRD, which is the core resource -that you will use with $productName$ to manage your edge. It enables you to route -requests by host and URL path from the edge of your cluster to Kubernetes services. - -1. Copy the configuration below and save it to a file named `quote.yaml` so that -you can deploy these resources to your cluster. This basic configuration creates -the `quote` deployment and a service to expose that deployment on port 80. - - ```yaml - --- - apiVersion: apps/v1 - kind: Deployment - metadata: - name: quote - namespace: ambassador - spec: - replicas: 1 - selector: - matchLabels: - app: quote - strategy: - type: RollingUpdate - template: - metadata: - labels: - app: quote - spec: - containers: - - name: backend - image: docker.io/datawire/quote:$quoteVersion$ - ports: - - name: http - containerPort: 8080 - --- - apiVersion: v1 - kind: Service - metadata: - name: quote - namespace: ambassador - spec: - ports: - - name: http - port: 80 - targetPort: 8080 - selector: - app: quote - ``` - -1. Apply the configuration to the cluster with the command `kubectl apply -f quote.yaml`. - -1. Copy the configuration below and save it to a file called `quote-backend.yaml` -so that you can create a `Mapping` on your cluster. This `Mapping` tells $productName$ to route all traffic inbound to the `/backend/` path, on any host that can be used to reach $productName$, to the `quote` service. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Mapping - metadata: - name: quote-backend - namespace: ambassador - spec: - hostname: "*" - prefix: /backend/ - service: quote - ``` - -1. Apply the configuration to the cluster with the command -`kubectl apply -f quote-backend.yaml` - -1. Store the $productName$ `LoadBalancer` address to a local environment variable. -You will use this variable to test accessing your pod. - - ``` - export AMBASSADOR_LB_ENDPOINT=$(kubectl -n ambassador get svc ambassador -o "go-template={{range .status.loadBalancer.ingress}}{{or .ip .hostname}}{{end}}") - ``` - -1. Test the configuration by accessing the service through the $productName$ load -balancer. - - ``` - $ curl -Lk "https://$AMBASSADOR_LB_ENDPOINT/backend/" - { - "server": "idle-cranberry-8tbb6iks", - "quote": "Non-locality is the driver of truth. By summoning, we vibrate.", - "time": "2019-12-11T20:10:16.525471212Z" - } - ``` - -Success, you have created your first $productName$ `Mapping`, routing a -request from your cluster's edge to a service! - -Since the `Mapping` you just created controls how requests are routed, -changing the `Mapping` will immediately change the routing. To see this -in action, use `kubectl` to edit the `Mapping`: - -1. Run `kubectl edit Mapping quote-backend`. - -1. Change `prefix: /backend/` to `prefix: /quoteme/`. - -1. Save the file and let `kubectl` update your `Mapping`. - -1. Run `kubectl get Mappings --namespace ambassador`. You will see the -`quote-backend` `Mapping` has the updated prefix listed. Try to access the -endpoint again via `curl` with the updated prefix. - - ``` - $ kubectl get Mappings --namespace ambassador - NAME PREFIX SERVICE STATE REASON - quote-backend /quoteme/ quote - - $ curl -Lk "https://${AMBASSADOR_LB_ENDPOINT}/quoteme/" - { - "server": "snippy-apple-ci10n7qe", - "quote": "A principal idea is omnipresent, much like candy.", - "time": "2020-11-18T17:15:42.095153306Z" - } - ``` - -1. Change the prefix back to `/backend/` so that you can later use the `Mapping` -with other tutorials. - -## 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. In the Edge Policy Console, navigate to the **APIs** tab. You'll see the -OpenAPI documentation there for the "Quote Service API." Click **GET** to -expand out the documentation. - -1. Navigate to `https:///docs/` to see the -publicly visible Developer Portal. Make sure you include the trailing `/`. -This is a fully customizable portal that you can share with third parties who -need information about your APIs. - -## Next Steps - -Further explore some of the concepts you learned about in this article: -* [`Mapping` resource](../../topics/using/intro-mappings/): routes traffic from -the edge of your cluster to a Kubernetes service -* [`Host` resource](../../topics/running/host-crd/): sets the hostname by which -$productName$ will be accessed and secured with TLS certificates -* [Developer Portal](../../tutorials/dev-portal-tutorial/): -publishes an API catalog and OpenAPI documentation - -$productName$ has a comprehensive range of [features](/features/) to -support the requirements of any edge microservice. - -Learn more about [how developers use $productName$](../../topics/using/) to manage -edge policies. - -Learn more about [how site reliability engineers and operators run $productName$](../../topics/running/) -in production environments. - -To learn how $productName$ works, use cases, best practices, and more, check out -the [Quick Start](../getting-started) or read the [$productName$ Story](../../about/why-ambassador). - -For a custom configuration, you can install $productName$ -[manually](../../topics/install/yaml-install). diff --git a/content/en/docs/3.2/versions.yml b/content/en/docs/3.2/versions.yml deleted file mode 100644 index c899674b..00000000 --- a/content/en/docs/3.2/versions.yml +++ /dev/null @@ -1,35 +0,0 @@ -# branch info -branch: release/v3.2 - -# self -version: 3.2.0 -productName: "Emissary-ingress" -productNamePlural: "Emissary-ingresses" -productNamespace: emissary -productDeploymentName: emissary-ingress -productHelmName: emissary-ingress - -# OSS (self) -ossVersion: 3.2.0 -ossDocsVersion: "pre-release" -ossChartVersion: 8.2.0 -OSSproductName: "Emissary-ingress" -OSSproductNamePlural: "Emissary-ingresses" - -# AES (not self) -aesVersion: 3.2.0 -aesDocsVersion: "3.2" -aesChartVersion: 8.2.0 -AESproductName: "Ambassador Edge Stack" -AESproductNamePlural: "Ambassador Edge Stacks" - -# other products -qotmVersion: 1.7 -quoteVersion: 0.5.0 - -# Most recent version from previous major versions -# This is mostly to ensure that the migration matrix stays up-to-date -versionTwoX: 2.4.1 -chartVersionTwoX: 7.5.1 -versionOneX: 1.14.4 -chartVersionOneX: 6.9.5 diff --git a/content/en/docs/3.3/_index.md b/content/en/docs/3.3/_index.md deleted file mode 100644 index d02844c2..00000000 --- a/content/en/docs/3.3/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: v3.3 docs -cascade: - version: v3.3 - versName: &name v3.3 - git_version_tag: v3.3.0 - exclude_search: true -linkTitle: *name -simple_list: true -weight: -330 # Weight for doc version vX.Y should be -XY0 ---- - -These docs cover everything from setting up and running Emissary-ingress to its operation and usage. diff --git a/content/en/docs/3.3/about/aes-emissary-eol.md b/content/en/docs/3.3/about/aes-emissary-eol.md deleted file mode 100644 index 6afc3142..00000000 --- a/content/en/docs/3.3/about/aes-emissary-eol.md +++ /dev/null @@ -1,56 +0,0 @@ -# $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/content/en/docs/3.3/about/alternatives.md b/content/en/docs/3.3/about/alternatives.md deleted file mode 100644 index bafec087..00000000 --- a/content/en/docs/3.3/about/alternatives.md +++ /dev/null @@ -1,19 +0,0 @@ -# $productName$ vs. other software - -Alternatives to $productName$ fall into three basic categories: - -* Hosted API gateways, such as the [Amazon API gateway](https://aws.amazon.com/api-gateway/). -* Traditional API gateways, such as [Kong](https://konghq.org/). -* L7 proxies, such as [Traefik](https://traefik.io/), [NGINX](http://nginx.org/), [HAProxy](http://www.haproxy.org/), or [Envoy](https://www.envoyproxy.io), or Ingress controllers built on these proxies. - -Both hosted API gateways and traditional API gateways are: - -* Not self-service. The management interfaces on traditional API gateways are not designed for developer self-service, and provide limited safety and usability for developers. -* Not Kubernetes-native. They're typically configured using REST APIs, making it challenging to adopt cloud-native patterns such as GitOps and declarative configuration. -* [Designed for API management, rather than designed for microservices](../../topics/concepts/microservices-api-gateways). - -A Layer 7 proxy can be used as an API gateway, but typically requires additional bespoke development to support microservices use cases. In fact, many API gateways package the additional features needed for an API gateway on top of an L7 proxy. $productName$ uses Envoy, while Kong uses NGINX. If you're interested in deploying Envoy directly, we've written an [introductory tutorial](https://www.datawire.io/guide/traffic/getting-started-lyft-envoy-microservices-resilience/). - -## Istio - -[Istio](https://istio.io) is an open-source service mesh, built on Envoy. A service mesh is designed to manage East/West traffic (traffic between servers and your data center), while an API gateway manages North/South traffic (in and out of your data center). Documentation on how to deploy $productName$ with Istio is [here](../../howtos/istio). In general, we've found that North/South traffic is quite different from East/West traffic (i.e., you don't control the client in the North/South use case). diff --git a/content/en/docs/3.3/about/changes-2.x.md b/content/en/docs/3.3/about/changes-2.x.md deleted file mode 100644 index 389cc89b..00000000 --- a/content/en/docs/3.3/about/changes-2.x.md +++ /dev/null @@ -1,238 +0,0 @@ -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. - - - $productName$ 2.X supports only API versions getambassador.io/v2 - and getambassador.io/v3alpha1. If you are using any resources with - older API versions, you will need to upgrade them. - - -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 [structural CRDs](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. - - - Learn more about Listener.
- Learn more about Host. - - -### 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. - - - Learn more about Host. - - -### `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. - - - Learn more about Host.
- Learn more about Mapping. - - -### 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. - - - Learn more about Host. - - -### `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). - - - Learn more about Host.
- Learn more about TLSContext. - - -### `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). - - - Learn more about Mapping. - - -### `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. - - - Learn more about Mapping. - - -## 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). In $productName$ -2.X, you may switch back to Envoy V2 by setting the `AMBASSADOR_ENVOY_API_VERSION` -environment variable to "V2"; in $productName$ 3.X, support for the Envoy V2 API (and -the `AMBASSADOR_ENVOY_API_VERSION` environment variable) will be removed. - -### 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. - - - Learn more about Listener. - - -### `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/content/en/docs/3.3/about/changes-3.y.md b/content/en/docs/3.3/about/changes-3.y.md deleted file mode 100644 index 91105d28..00000000 --- a/content/en/docs/3.3/about/changes-3.y.md +++ /dev/null @@ -1,52 +0,0 @@ -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 AuthServices 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, -``` - - - Learn more about Envoy Proxy changes. - - -## 2. Envoy V2 Protocol Support Removed - -With the upgrade to Envoy **1.22**, the V2 Envoy Transport Protocol is no longer supported. -$productName$ 3.X **only** supports [V3 Envoy API](https://www.envoyproxy.io/docs/envoy/latest/api-v3/api). - - -The environment variable AMBASSADOR_ENVOY_API_VERSION has been removed and will no longer have the affect -of changing the transport protocol. - - - -The setting of 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. - diff --git a/content/en/docs/3.3/about/faq.md b/content/en/docs/3.3/about/faq.md deleted file mode 100644 index 513c75c5..00000000 --- a/content/en/docs/3.3/about/faq.md +++ /dev/null @@ -1,79 +0,0 @@ -# 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. -* 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! The core functionality of the $AESproductName$ is free and has no limits whatsoever. If you wish to use one of our additional, proprietary features such as Single Sign-On, you can get a free community license for up to 5 requests per second by registering your connected $AESproductName$ installation in [Ambassador Cloud](https://app.getambassador.io/cloud/). Please contact [sales](/contact-us/) if you need more than 5 RPS. - -For more details on core unlimited features and premium features, see the [editions page](/editions). - -### 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? - -[//]: # (+FIX+ Check for OSS) - -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$? - -[//]: # (+FIX+ Check for OSS) - -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 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/content/en/docs/3.3/about/features-and-benefits.md b/content/en/docs/3.3/about/features-and-benefits.md deleted file mode 100644 index a25d7752..00000000 --- a/content/en/docs/3.3/about/features-and-benefits.md +++ /dev/null @@ -1,43 +0,0 @@ -# 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 - -[//]: # (+FIX+ Forge is no more) - -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 - -[//]: # (+FIX+ we've come to realize that it's better to scale vertically) - -$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 using a custom authentication service. When configured, the $productName$ will check with your external authentication service prior to routing an incoming request. For more information, see the [authentication guide](../../topics/running/services/auth-service). - -## 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/content/en/docs/3.3/about/known-issues.md b/content/en/docs/3.3/about/known-issues.md deleted file mode 100644 index 6b89c65a..00000000 --- a/content/en/docs/3.3/about/known-issues.md +++ /dev/null @@ -1,9 +0,0 @@ -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. diff --git a/content/en/docs/3.3/about/support.md b/content/en/docs/3.3/about/support.md deleted file mode 100644 index 11927f95..00000000 --- a/content/en/docs/3.3/about/support.md +++ /dev/null @@ -1,27 +0,0 @@ -# Need help? - -If you need help deploying $productName$ at your organization, there are several different options available to you. - -## Support tiers - -### $productName$ community support - -When running $OSSproductName$, or $AESproductName$ with free community licenses, [join our Slack channel](http://a8r.io/slack) to talk with other users in the community and get your questions answered. - -If you can’t find an answer there, [contact us](/contact-us) to learn more about the support options available with $AESproductName$ Enterprise. - -### $AESproductName$ Enterprise - -With $AESproductName$ Enterprise, you have access to deployment and production support. To learn more, [contact sales](/contact-us). - -**Deployment and Update Support**: $AESproductName$ can accelerate your migration to Kubernetes, or your upgrade between versions of $AESproductName$. Deployment support helps you with the $AESproductName$ and Kubernetes migration, before you move to production. - -**Production Support**: We offer two types of production support contracts for users deploying the $AESproductName$ in production. We offer both business hour (8am - 5pm EST, M-F) and 24x7 Sev 1 support for the $AESproductName$. 24x7 Sev 1 support includes custom hotfix support for production outages if necessary. - -## File a Github Issue - -If you see a bug you want to fix, see room for documentation improvements, or have something else you want to change, you can [file an issue on github](https://github.com/datawire/ambassador/issues/new). - -## Pricing - -[Contact us](/contact-us) to learn how we can help, and for detailed pricing information. diff --git a/content/en/docs/3.3/about/why-ambassador.md b/content/en/docs/3.3/about/why-ambassador.md deleted file mode 100644 index 0d343983..00000000 --- a/content/en/docs/3.3/about/why-ambassador.md +++ /dev/null @@ -1,54 +0,0 @@ -# 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 an open-source, Kubernetes-native [microservices API gateway](../../topics/concepts/microservices-api-gateways) built on 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/content/en/docs/3.3/community.md b/content/en/docs/3.3/community.md deleted file mode 100644 index 759e4f0e..00000000 --- a/content/en/docs/3.3/community.md +++ /dev/null @@ -1,12 +0,0 @@ -# Community - -## Contributor's guide -Please review our [contributor's guide](https://github.com/emissary-ingress/emissary/blob/master/DEVELOPING.md) -on GitHub to learn how you can help make Emissary-ingress better. - -## Changelog -Our [changelog](https://github.com/emissary-ingress/emissary/blob/master/CHANGELOG.md) -describes new features, bug fixes, and updates to each version of Emissary-ingress. - -## Meetings -Check out our community [meeting schedule](https://github.com/emissary-ingress/emissary/blob/master/MEETING_SCHEDULE.md) for opportunities to interact with Emissary-ingress developers. diff --git a/content/en/docs/3.3/doc-links.yml b/content/en/docs/3.3/doc-links.yml deleted file mode 100644 index bef872db..00000000 --- a/content/en/docs/3.3/doc-links.yml +++ /dev/null @@ -1,223 +0,0 @@ - - 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: $productName$ 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: 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: 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/basic-auth - - title: Rate limiting - items: - - title: Rate limiting service - link: /topics/running/services/rate-limit-service/ - - title: Basic rate limiting - link: /topics/using/rate-limits/ - - 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: 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: 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: 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: 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: Licenses - link: licenses diff --git a/content/en/docs/3.3/features-icons/basic-authentication.svg b/content/en/docs/3.3/features-icons/basic-authentication.svg deleted file mode 100644 index 2bd19edf..00000000 --- a/content/en/docs/3.3/features-icons/basic-authentication.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_897228_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.3/features-icons/canary-release.svg b/content/en/docs/3.3/features-icons/canary-release.svg deleted file mode 100644 index f8de57d9..00000000 --- a/content/en/docs/3.3/features-icons/canary-release.svg +++ /dev/null @@ -1,27 +0,0 @@ - - - - Group 25 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.3/features-icons/cors.svg b/content/en/docs/3.3/features-icons/cors.svg deleted file mode 100644 index e559d924..00000000 --- a/content/en/docs/3.3/features-icons/cors.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_111967_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.3/features-icons/datadog.png b/content/en/docs/3.3/features-icons/datadog.png deleted file mode 100644 index eea05f8c..00000000 Binary files a/content/en/docs/3.3/features-icons/datadog.png and /dev/null differ diff --git a/content/en/docs/3.3/features-icons/datadog.svg b/content/en/docs/3.3/features-icons/datadog.svg deleted file mode 100644 index e46e8118..00000000 --- a/content/en/docs/3.3/features-icons/datadog.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Screen Shot 2018-04-05 at 8.22.25 AM - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.3/features-icons/diagnostics.svg b/content/en/docs/3.3/features-icons/diagnostics.svg deleted file mode 100644 index 940e1bc2..00000000 --- a/content/en/docs/3.3/features-icons/diagnostics.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_196445_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.3/features-icons/distributed-tracing.png b/content/en/docs/3.3/features-icons/distributed-tracing.png deleted file mode 100644 index 6b69e28c..00000000 Binary files a/content/en/docs/3.3/features-icons/distributed-tracing.png and /dev/null differ diff --git a/content/en/docs/3.3/features-icons/grpc.png b/content/en/docs/3.3/features-icons/grpc.png deleted file mode 100644 index b2f5a0d9..00000000 Binary files a/content/en/docs/3.3/features-icons/grpc.png and /dev/null differ diff --git a/content/en/docs/3.3/features-icons/prometheus.svg b/content/en/docs/3.3/features-icons/prometheus.svg deleted file mode 100644 index d5252a66..00000000 --- a/content/en/docs/3.3/features-icons/prometheus.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - prometheus_logo_grey - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.3/features-icons/rate-limiting.svg b/content/en/docs/3.3/features-icons/rate-limiting.svg deleted file mode 100644 index f1b6eacb..00000000 --- a/content/en/docs/3.3/features-icons/rate-limiting.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - Group 10 - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.3/features-icons/regex-routing.svg b/content/en/docs/3.3/features-icons/regex-routing.svg deleted file mode 100644 index 113b53b5..00000000 --- a/content/en/docs/3.3/features-icons/regex-routing.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_699774_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.3/features-icons/request-transformers.svg b/content/en/docs/3.3/features-icons/request-transformers.svg deleted file mode 100644 index 0b13e2dc..00000000 --- a/content/en/docs/3.3/features-icons/request-transformers.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_96239_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.3/features-icons/shadowing.svg b/content/en/docs/3.3/features-icons/shadowing.svg deleted file mode 100644 index 9e85eee1..00000000 --- a/content/en/docs/3.3/features-icons/shadowing.svg +++ /dev/null @@ -1,15 +0,0 @@ - - - - shadow - Created with Sketch. - - - - - - - - - - diff --git a/content/en/docs/3.3/features-icons/statsd.png b/content/en/docs/3.3/features-icons/statsd.png deleted file mode 100644 index 28374438..00000000 Binary files a/content/en/docs/3.3/features-icons/statsd.png and /dev/null differ diff --git a/content/en/docs/3.3/features-icons/statsd.svg b/content/en/docs/3.3/features-icons/statsd.svg deleted file mode 100644 index cabc90db..00000000 --- a/content/en/docs/3.3/features-icons/statsd.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - 88eb31f74479e422e4e9abfc6c2b00ee - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.3/features-icons/third-party-auth.svg b/content/en/docs/3.3/features-icons/third-party-auth.svg deleted file mode 100644 index 5359a24a..00000000 --- a/content/en/docs/3.3/features-icons/third-party-auth.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_511233_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.3/features-icons/timeouts.svg b/content/en/docs/3.3/features-icons/timeouts.svg deleted file mode 100644 index 47f63056..00000000 --- a/content/en/docs/3.3/features-icons/timeouts.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_587034_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.3/features-icons/tls-termination.svg b/content/en/docs/3.3/features-icons/tls-termination.svg deleted file mode 100644 index 6a631a96..00000000 --- a/content/en/docs/3.3/features-icons/tls-termination.svg +++ /dev/null @@ -1,17 +0,0 @@ - - - - noun_63544_cc - Created with Sketch. - - - - - - - - - - - - diff --git a/content/en/docs/3.3/features-icons/url-rewrite.svg b/content/en/docs/3.3/features-icons/url-rewrite.svg deleted file mode 100644 index 023e2e05..00000000 --- a/content/en/docs/3.3/features-icons/url-rewrite.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1295942_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.3/features-icons/websockets.svg b/content/en/docs/3.3/features-icons/websockets.svg deleted file mode 100644 index af17b9c0..00000000 --- a/content/en/docs/3.3/features-icons/websockets.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - noun_50814_cc - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.3/howtos/basic-auth.md b/content/en/docs/3.3/howtos/basic-auth.md deleted file mode 100644 index 70ce27ce..00000000 --- a/content/en/docs/3.3/howtos/basic-auth.md +++ /dev/null @@ -1,191 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Basic authentication (for $productName$) - -[//]: # (+FIX+ link to "authentication and authorization" concept) - - - This guide applies to $OSSproductName$, use of this guide with $AESproductName$ is not supported. $AESproductName$ does authentication using the Filter resource instead of the AuthService resource as described below. - - -$productName$ can authenticate incoming requests before routing them to a backing -service. In this tutorial, we'll configure $productName$ to use an external third -party authentication service. We're assuming also that you are running the -quote application in your cluster as described in the -[$productName$ tutorial](../../tutorials/quickstart-demo/). - -## Before you get started - -This tutorial assumes you have already followed the $productName$ [Installation](../../topics/install/) guide. If you haven't done that already, you should do so now. - -Once complete, you'll have a Kubernetes cluster running $productName$. Let's walk through adding authentication to this setup. - -## 1. Deploy the authentication service - -$productName$ delegates the actual authentication logic to a third party authentication service. We've written a [simple authentication service](https://github.com/datawire/ambassador-auth-service) that: - -- listens for requests on port 3000; -- expects all URLs to begin with `/extauth/`; -- performs HTTP Basic Auth for all URLs starting with `/backend/get-quote/` (other URLs are always permitted); -- accepts only user `username`, password `password`; and -- makes sure that the `x-qotm-session` header is present, generating a new one if needed. - -$productName$ routes _all_ requests through the authentication service: it relies on the auth service to distinguish between requests that need authentication and those that do not. If $productName$ cannot contact the auth service, it will return a 503 for the request; as such, **it is very important to have the auth service running before configuring $productName$ to use it.** - -Here's the YAML we'll start with: - -```yaml ---- -apiVersion: v1 -kind: Service -metadata: - name: example-auth -spec: - type: ClusterIP - selector: - app: example-auth - ports: - - port: 3000 - name: http-example-auth - targetPort: http-api ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: example-auth -spec: - replicas: 1 - strategy: - type: RollingUpdate - selector: - matchLabels: - app: example-auth - template: - metadata: - labels: - app: example-auth - spec: - containers: - - name: example-auth - image: docker.io/datawire/ambassador-auth-service:2.0.0 - imagePullPolicy: Always - ports: - - name: http-api - containerPort: 3000 - resources: - limits: - cpu: "0.1" - memory: 100Mi -``` - -Note that the cluster does not yet contain any $productName$ AuthService definition. This is intentional: we want the service running before we tell $productName$ about it. - -The YAML above is published at getambassador.io, so if you like, you can just do - -``` -kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/demo/demo-auth.yaml -``` - -to spin everything up. (Of course, you can also use a local file, if you prefer.) - -Wait for the pod to be running before continuing. The output of `kubectl get pods` should look something like - -``` -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -example-auth-6c5855b98d-24clp 1/1 Running 0 4m -``` -Note that the `READY` field says `1/1` which means the pod is up and running. - -## 2. Configure $productName$ authentication - -Once the auth service is running, we need to tell $productName$ about it. The easiest way to do that is point it to the `example-auth` service with the following: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: AuthService -metadata: - name: authentication -spec: - auth_service: "example-auth:3000" - path_prefix: "/extauth" - allowed_request_headers: - - "x-qotm-session" - allowed_authorization_headers: - - "x-qotm-session" -``` - -This configuration tells $productName$ about the auth service, notably that it needs the `/extauth` prefix, and that it's OK for it to pass back the `x-qotm-session` header. Note that `path_prefix` and `allowed_*_headers` are optional. - -If the auth service uses a framework like [Gorilla Toolkit](http://www.gorillatoolkit.org) which enforces strict slashes as HTTP path separators, it is possible to end up with an infinite redirect where the auth service's framework redirects any request with non-conformant slashing. This would arise if the above example had `path_prefix: "/extauth/"`, the auth service would see a request for `/extauth//backend/get-quote/` which would then be redirected to `/extauth/backend/get-quote/` rather than actually be handled by the authentication handler. For this reason, remember that the full path of the incoming request including the leading slash, will be appended to `path_prefix` regardless of non-conformant slashing. - -You can apply this file from getambassador.io with - -``` -kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/demo/demo-auth-enable.yaml -``` - -or, again, apply it from a local file if you prefer. - -Note that the cluster does not yet contain any $productName$ AuthService definition. - -## 3. Test authentication - -If we `curl` to a protected URL: - -``` -$ curl -Lv $AMBASSADORURL/backend/get-quote/ -``` - -We get a 401 since we haven't authenticated. - -``` -* TCP_NODELAY set -* Connected to 54.165.128.189 (54.165.128.189) port 32281 (#0) -> GET /backend/get-quote/ HTTP/1.1 -> Host: 54.165.128.189:32281 -> User-Agent: curl/7.63.0 -> Accept: */* -> -< HTTP/1.1 401 Unauthorized -< www-authenticate: Basic realm="Ambassador Realm" -< content-length: 0 -< date: Thu, 23 May 2019 15:24:55 GMT -< server: envoy -< -* Connection #0 to host 54.165.128.189 left intact -``` - -If we authenticate to the service, we will get a quote successfully: - -``` -$ curl -Lv -u username:password $AMBASSADORURL/backend/get-quote/ - -* TCP_NODELAY set -* Connected to 54.165.128.189 (54.165.128.189) port 32281 (#0) -* Server auth using Basic with user 'username' -> GET /backend/get-quote/ HTTP/1.1 -> Host: 54.165.128.189:32281 -> Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= -> User-Agent: curl/7.63.0 -> Accept: */* -> -< HTTP/1.1 200 OK -< content-type: application/json -< date: Thu, 23 May 2019 15:25:06 GMT -< content-length: 172 -< x-envoy-upstream-service-time: 0 -< server: envoy -< -{ - "server": "humble-blueberry-o2v493st", - "quote": "Nihilism gambles with lives, happiness, and even destiny itself!", - "time": "2019-05-23T15:25:06.544417902Z" -* Connection #0 to host 54.165.128.189 left intact -} -``` - -## More - -For more details about configuring authentication, see the [`External` filter](/docs/edge-stack/latest/topics/using/filters/) documentation. diff --git a/content/en/docs/3.3/howtos/cert-manager.md b/content/en/docs/3.3/howtos/cert-manager.md deleted file mode 100644 index 975dd3ff..00000000 --- a/content/en/docs/3.3/howtos/cert-manager.md +++ /dev/null @@ -1,230 +0,0 @@ -# Using cert-manager - -[//]: # (+FIX+ link to "TLS and certificates" concept) - -$AESproductName$ has simple and easy built-in support for automatically [using ACME] with the -`http-01` challenge to create and renew TLS certificates. However, this support is not available -in $OSSproductName$, and it is limited to the ACME `http-01` challenge type. If you're running -$OSSproductName$, or if you require more flexible certificate management (such as using ACME's -`dns-01` challenge, or using a non-ACME certificate source), external certificate management -tools are also supported. - -[using ACME]: ../../topics/running/host-crd/#acme-support - -One such tool is Jetstack's [cert-manager](https://github.com/jetstack/cert-manager), which is a general-purpose tool -for managing certificates in Kubernetes. Cert-manager will automatically create and renew TLS certificates and store -them as Kubernetes secrets for easy use in a cluster. $productName$ will automatically watch for secret -changes and reload certificates upon renewal. - -> **Note:** This document assumes cert-manager v0.15 or greater. This document has been updated to use CRD standards -> specified in v0.15. [Legacy CRD support](https://cert-manager.io/docs/installation/upgrading/upgrading-0.14-0.15/) -> was removed in cert-manager v0.15, see their [upgrading](https://cert-manager.io/docs/installation/upgrading/) -> document for more info. - -## Install cert-manager - -There are many different ways to [install cert-manager](https://cert-manager.io/docs/installation/). For simplicity, we will use Helm. - -1. Create the cert-manager CRDs. - ``` - kubectl apply -f https://github.com/jetstack/cert-manager/releases/latest/download/cert-manager.crds.yaml - ``` - -2. Add the `jetstack` Helm repository. - ``` - helm repo add jetstack https://charts.jetstack.io && helm repo update - ``` - -3. Install cert-manager. - - ``` - kubectl create ns cert-manager - helm install cert-manager --namespace cert-manager jetstack/cert-manager - ``` - -## Issuing certificates - -cert-manager issues certificates from a CA such as [Let's Encrypt](https://letsencrypt.org/). It does this using the ACME protocol which supports various challenge mechanisms for verifying ownership of the domain. - -### Issuer - -An `Issuer` or `ClusterIssuer` identifies which Certificate Authority cert-manager will use to issue a certificate. `Issuer` is a namespaced resource allowing you to use different CAs in each namespace, a `ClusterIssuer` is used to issue certificates in any namespace. Configuration depends on which ACME [challenge](#challenge) you are using. - -### Certificate - -A [Certificate](https://cert-manager.io/docs/concepts/certificate/) is a namespaced resource that references an `Issuer` or `ClusterIssuer` for issuing certificates. `Certificate`s define the DNS name(s) a key and certificate should be issued for, as well as the secret to store those files (e.g. `ambassador-certs`). Configuration depends on which ACME [challenge](#challenge) you are using. - -By duplicating issuers, certificates, and secrets one can support multiple domains with [SNI](../../topics/running/tls/sni). - -## Challenge - -cert-manager supports two kinds of ACME challenges that verify domain ownership in different ways: HTTP-01 and DNS-01. - -### DNS-01 challenge - -The DNS-01 challenge verifies domain ownership by proving you have control over its DNS records. Issuer configuration will depend on your [DNS provider](https://cert-manager.io/docs/configuration/acme/dns01/#supported-dns01-providers). This example uses [AWS Route53](https://cert-manager.io/docs/configuration/acme/dns01/route53/). - -1. Create the IAM policy specified in the cert-manager [AWS Route53](https://cert-manager.io/docs/configuration/acme/dns01/route53/) documentation. - -2. Note the `accessKeyID` and create a `secret` named `prod-route53-credentials-secret` in the cert-manager namespace that has a key value: `secret-access-key` from your AWS IaM credentials. - -3. Create and apply a `ClusterIssuer`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: ClusterIssuer - metadata: - name: letsencrypt-prod - spec: - acme: - email: email@example.com - server: https://acme-v02.api.letsencrypt.org/directory - privateKeySecretRef: - name: letsencrypt-prod - solvers: - - selector: - dnsZones: - - "myzone.route53.com" - dns01: - route53: - region: us-east-1 - accessKeyID: {accessKeyID} - hostedZoneID: {Hosted Zone ID} # optional, allows you to reduce the scope of permissions in Amazon IAM - secretAccessKeySecretRef: - name: prod-route53-credentials-secret - key: secret-access-key - ``` - -4. Create and apply a `Certificate`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: Certificate - metadata: - name: myzone.route53.com - # cert-manager will put the resulting Secret in the same Kubernetes - # namespace as the Certificate. You should create the certificate in - # whichever namespace you want to configure a Host. - spec: - secretName: ambassador-certs - issuerRef: - name: letsencrypt-prod - kind: ClusterIssuer - commonName: myzone.route53.com - dnsNames: - - myzone.route53.com - ``` - -5. Verify the secret is created. - - ``` - $ kubectl get secrets -n ambassador - NAME TYPE DATA AGE - ambassador-certs kubernetes.io/tls 2 1h - ``` - -### HTTP-01 challenge - -The HTTP-01 challenge verifies ownership of the domain by sending a request for a specific file on that domain. cert-manager accomplishes this by sending a request to a temporary pod with the prefix `/.well-known/acme-challenge/`. To perform this challenge: - -1. Create and apply a `ClusterIssuer`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: ClusterIssuer - metadata: - name: letsencrypt-prod - spec: - acme: - email: email@example.com - server: https://acme-v02.api.letsencrypt.org/directory - privateKeySecretRef: - name: letsencrypt-prod - solvers: - - http01: - ingress: - class: nginx - selector: {} - ``` - -2. Create and apply a `Certificate`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: Certificate - metadata: - name: ambassador-certs - # cert-manager will put the resulting Secret in the same Kubernetes - # namespace as the Certificate. You should create the certificate in - # whichever namespace you want to configure a Host. - namespace: ambassador - spec: - secretName: ambassador-certs - issuerRef: - name: letsencrypt-prod - kind: ClusterIssuer - dnsNames: - - example.com - ``` - -3. Apply both the `ClusterIssuer` and `Certificate` - - After applying both of these YAML manifests, you will notice that cert-manager has spun up a temporary pod named `cm-acme-http-solver-xxxx` but no certificate has been issued. Check the cert-manager logs and you will see a log message that looks like this: - - ``` - $ kubectl logs cert-manager-756d6d885d-v7gmg - ... - Preparing certificate default/ambassador-certs with issuer - Calling GetOrder - Calling GetAuthorization - Calling HTTP01ChallengeResponse - Cleaning up old/expired challenges for Certificate default/ambassador-certs - Calling GetChallenge - wrong status code '404' - Looking up Ingresses for selector certmanager.k8s.io/acme-http-domain=161156668,certmanager.k8s.io/acme-http-token=1100680922 - Error preparing issuer for certificate default/ambassador-certs: http-01 self check failed for domain "example.com - ``` - -4. Create a Mapping for the `/.well-known/acme-challenge/` route. - - cert-manager uses an `Ingress` to issue the challenge to `/.well-known/acme-challenge/` that is incompatible with Ambassador. We will need to create a `Mapping` so the cert-manager can reach the temporary pod. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Mapping - metadata: - name: acme-challenge-mapping - spec: - hostname: "*" - prefix: /.well-known/acme-challenge/ - rewrite: "" - service: acme-challenge-service - - --- - apiVersion: v1 - kind: Service - metadata: - name: acme-challenge-service - spec: - ports: - - port: 80 - targetPort: 8089 - selector: - acme.cert-manager.io/http01-solver: "true" - ``` - - Apply the YAML and wait a couple of minutes. cert-manager will retry the challenge and issue the certificate. - -5. Verify the secret is created: - - ``` - $ kubectl get secrets - NAME TYPE DATA AGE - ambassador-certs kubernetes.io/tls 2 1h - ambassador-token-846d5 kubernetes.io/service-account-token 3 2h - ``` diff --git a/content/en/docs/3.3/howtos/client-cert-validation.md b/content/en/docs/3.3/howtos/client-cert-validation.md deleted file mode 100644 index 10fe639d..00000000 --- a/content/en/docs/3.3/howtos/client-cert-validation.md +++ /dev/null @@ -1,110 +0,0 @@ -# Client certificate validation - -[//]: # (+FIX+ link to "TLS and client certs" concept) - -Sometimes, for additional security or authentication purposes, you will want -the server to validate who the client is before establishing an encrypted -connection. - -To support this, $productName$ can be configured to use a provided CA certificate -to validate certificates sent from your clients. This allows for client-side -mTLS where both $productName$ and the client provide and validate each other's -certificates. - -## Prerequisites - -- [openssl](https://www.openssl.org/source/) For creating client certificates -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [$productName$](../../tutorials/getting-started) -- [cURL](https://curl.haxx.se/download.html) - - -## Configuration - -1. Create a certificate and key. - - This can be done with a single command with `openssl`: - - ``` - openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 - ``` - - Enter a passcode for PEM files and fill in the certificate information. - Since this certificate will only be shared between a client and $productName$, - the Common Name must be set to something. Everything else can be left blank. - - **Note:** If using MacOS, - [you must](https://curl.haxx.se/mail/archive-2014-10/0053.html) - add the certificate and key as a PKCS encoded file to your Keychain. To do - this: - - 1. Encode `cert.pem` and `key.pem` created above in PKCS format - - ``` - openssl pkcs12 -inkey key.pem -in cert.pem -export -out certificate.p12 - ``` - - 2. Open "Keychain Access" on your system and select "File"->"Import Items..." - - 3. Navigate to your working directory and select the `certificate.p12` file - we just created above. - -2. Create a secret to hold the client CA certificate. - - ``` - kubectl create secret generic client-cacert --from-file=tls.crt=cert.pem - ``` - -3. Configure $productName$ to use this certificate for client certificate validation. - - First create a `Host` to manage your domain: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Host - metadata: - name: example-host - spec: - hostname: host.example.com - acmeProvider: - email: julian@example.com - ``` - - Then create a `TLSContext` to configure advanced TLS options like client - certificate validation: - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: TLSContext - metadata: - name: example-host-context - spec: - hosts: - - host.example.com - secret: host.example.com - ca_secret: client-cacert - cert_required: false # Optional: Configures $productName$ to reject the request if the client does not provide a certificate. Default: false - ``` - - **Note**: Client certificate validation requires $productName$ be configured to terminate TLS - - $productName$ is now be configured to validate certificates that the client provides. - -4. Test that $productName$ is validating the client certificates with `curl` - - **Linux**: - ``` - curl -v --cert cert.pem --key key.pem https://host.example.com/ - ``` - - **MacOS**: - ``` - curl -v --cert certificate.p12:[password] https://host.example.com/ - ``` - - Looking through the verbose output, you can see we are sending a client - certificate and $productName$ is validating it. - - If you need further proof, simply create a new set of certificates and - try sending the curl with those. You will see $productName$ deny the request. diff --git a/content/en/docs/3.3/howtos/configure-communications.md b/content/en/docs/3.3/howtos/configure-communications.md deleted file mode 100644 index 1ac09d2c..00000000 --- a/content/en/docs/3.3/howtos/configure-communications.md +++ /dev/null @@ -1,763 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -Configuring $productName$ Communications -======================================== - -For $productName$ to do its job of managing network communications for your services, it first needs to know how its own communications should be set up. This is handled by a combination of resources: the `Listener`, the `Host`, and the `TLSContext`. - -- `Listener`: defines where, and how, $productName$ should listen for requests from the network. -- `Host`: defines which hostnames $productName$ should care about, and how to handle different kinds of requests for those hosts. `Host`s can be associated with one or more `Listener`s. -- `TLSContext`: defines whether, and how, $productName$ will manage TLS certificates and options. `TLSContext`s can be associated with one or more `Host`s. - -Once the basic communications setup is in place, $productName$ `Mapping`s and `TCPMapping`s can be associated with `Host`s to actually do routing. - - - Remember that Listener and Host resources are  - required for a functioning $productName$ installation that can route traffic!
- Learn more about Listener.
- Learn more about Host. - - - - Remember than $productName$ does not make sure that a wildcard Host exists! If the - wildcard behavior is needed, a Host with a hostname of "*" - must be defined by the user. - - - - Several different resources work together to configure communications. A working knowledge of all of them - can be very useful:
- Learn more about Listener.
- Learn more about Host.
- Learn more about Mapping.
- Learn more about TCPMapping.
- Learn more about TLSContext. - - -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]: ../../topics/running/tls -[certificates]: ../../topics/running/tls#certificates-and-secrets -[check the logs]: ../../topics/running/debugging#review-logs - -Examples / Cookbook -------------------- - -### Basic HTTP and HTTPS - -A useful configuration is to support either HTTP or HTTPS, in this case on either port 8080 or port 8443. This -tends to make it as easy as possible to communicate with the services behind the $productName$ instance. It uses -two `Listener`s and at least one `Host`. - - -#### `Listener`s: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: http-listener -spec: - port: 8080 - protocol: HTTPS # NOT A TYPO, see below - securityModel: XFP - hostBinding: - namespace: - from: SELF # See below ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: - namespace: - from: SELF # See below -``` - -- Both `Listener`s use `protocol: HTTPS` to allow Envoy to inspect incoming connections, determine - whether or not TLS is in play, and set `X-Forwarded-Proto` appropriately. The `securityModel` then specifies - that `X-Forwarded-Proto` will determine whether requests will be considered secure or insecure. - -- The `hostBinding` shown here will allow any `Host` in the same namespace as the `Listener`s - to be associated with both `Listener`s; in turn, that will allow access to that `Host`'s - `Mapping`s from either port. For greater control, use a `selector` instead. - -- Note that the `Listener`s do not specify anything about TLS certificates. The `Host` - handles that; see below. - - - Learn more about Listener - - -#### `Host` - -This example will assume that we expect to be reachable as `foo.example.com`, and that the `foo.example.com` -certificate is stored in the Kubernetes `Secret` named `foo-secret`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: "foo.example.com" - tlsSecret: - name: foo-secret - requestPolicy: - insecure: - action: Redirect -``` - -- The `tlsSecret` specifies the certificate in use for TLS termination. -- The `requestPolicy` specifies routing HTTPS and redirecting HTTP to HTTPS. -- Since the `Host` does not specify a `selector`, only `Mapping`s with a `hostname` that matches - `foo.example.com` will be associated with this `Host`. -- **Note well** that simply defining a `TLSContext` is not sufficient to terminate TLS: you must define either - a `Host` or an `Ingress`. -- Note that if no `Host` is present, but a TLS secret named `fallback-secret` is available, the system will - currently define a `Host` using `fallback-secret`. **This behavior is subject to change.** - - - Learn more about Host - - -### HTTP-Only - -Another straightforward configuration is to support only HTTP, in this case on port 8080. This uses a single -`Listener` and a single `Host`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: http-listener -spec: - port: 8080 - protocol: HTTP - securityModel: INSECURE - hostBinding: - namespace: - from: SELF # See below ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: "foo.example.com" - requestPolicy: - insecure: - action: Route -``` - -- Here, we listen only on port 8080, and only for HTTP. HTTPS will be rejected. -- Since requests are only allowed using HTTP, we declare all requests `INSECURE` by definition. -- The `Host` specifies routing HTTP, rather than redirecting it. - - - - Learn more about Listener
- Learn more about Host - - -### TLS using ACME ($AESproductName$ only) - -This scenario uses ACME to get certificates for `foo.example.com` and `bar.example.com`. HTTPS traffic to either -host is routed; HTTP traffic to `foo.example.com` will be redirected to HTTPS, but HTTP traffic to `bar.example.com` -will be rejected outright. - -Since this example uses ACME, **it is only supported in $AESproductName$**. - -For demonstration purposes, we show this example listening for HTTPS on port 9999, using `X-Forwarded-Proto`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener-9999 -spec: - port: 9999 - protocol: HTTPS - securityModel: XFP - hostBinding: # Edit as needed - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - acmeProvider: - email: julian@example.com ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - acmeProvider: - email: julian@example.com - requestPolicy: - insecure: - action: Reject -``` - -(`Mapping`s are not shown.) - -- Our `Listener`s will accept HTTPS and HTTP on port 9999, and the protocol used will dictate whether - the requests are secure (HTTPS) or insecure (HTTP). -- `foo-host` defaults to ACME with Let's Encrypt, since `acmeProvider.authority` is not provided. -- `foo-host` defaults to redirecting insecure requests, since the default for `requestPolicy.insecure.action` is `Redirect`. -- `bar-host` uses Let's Encrypt as well, but it will reject insecure requests. - -**If you use ACME for multiple Hosts, add a wildcard Host too.** -This is required to manage a known issue. This issue will be resolved in a future Ambassador Edge Stack release. - - - Learn more about Listener
- Learn more about Host - - -### Multiple TLS Certificates - -This scenario uses TLS without ACME. Each of our two `Host`s uses a distinct TLS certificate. HTTPS -traffic to either`foo.example.com` or `bar.example.com` is routed, but this time `foo.example.com` will redirect -HTTP requests, while `bar.example.com` will route them. - -Since this example does not use ACME, it is supported in $productName$ as well as $AESproductName$. - -For demonstration purposes, we show this example listening for HTTPS on port 4848, using `X-Forwarded-Proto`. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: foo-example-secret -data: - tls.crt: -certificate PEM- - tls.key: -secret key PEM- ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: bar-example-secret -data: - tls.crt: -certificate PEM- - tls.key: -secret key PEM- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener-4848 -spec: - port: 4848 - protocol: HTTPS - securityModel: XFP - hostBinding: # Edit as needed - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - tlsSecret: - name: foo-example-secret ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - tlsSecret: - name: bar-example-secret - requestPolicy: - insecure: - action: Route -``` - -- `foo-host` and `bar-host` simply reference the `tlsSecret` to use for termination. - - If the secret involved contains a wildcard cert, or a cert with multiple SAN, both `Host`s could - reference the same `tlsSecret`. -- `foo-host` relies on the default insecure routing action of `Redirect`. -- `bar-host` must explicitly specify routing HTTP. - - - - Learn more about Listener
- Learn more about Host - - -### Using a `TLSContext` - -If you need to share other TLS settings between two `Host`s, you can reference a `TLSContext` as well as -the `tlsSecret`. This is the same as the previous example, but we use a `TLSContext` to set `ALPN` information, -and we assume that the `Secret` contains a wildcard cert. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: wildcard-example-secret -data: - tls.crt: -wildcard here- - tls.key: -wildcard here- ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-context -spec: - secret: wildcard-example-secret - alpn_protocols: [h2, istio] ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener-4848 -spec: - port: 4848 - protocol: HTTPS - securityModel: XFP - hostBinding: # Edit as needed - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - tlsContext: - name: example-context - tlsSecret: - name: wildcard-example-secret ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - tlsContext: - name: example-context - tlsSecret: - name: wildcard-example-secret - requestPolicy: - insecure: - action: Route -``` - -- Note that specifying the `tlsSecret` is still necessary, even when `tlsContext` is specified. - - - - Learn more about Listener
- Learn more about Host - - -### ACME With a TLSContext ($AESproductName$ Only) - -In $AESproductName$, you can use a `TLSContext` with ACME as well. This example is the same as "TLS using ACME", -but we use a `TLSContext` to set `ALPN` information. Again, ACME is only supported in $AESproductName$. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-context -spec: - secret: example-acme-secret - alpn_protocols: [h2, istio] ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - acmeProvider: - email: julian@example.com - tlsContext: - name: example-context - tlsSecret: - name: example-acme-secret -``` - -- Note that we don't provide the `Secret`: the ACME client will create it for us. - - - - Learn more about Listener
- Learn more about Host - - -### Using an L7 Load Balancer to Terminate TLS - -In this scenario, a layer 7 load balancer ahead of $productName$ will terminate TLS, so $productName$ will always see HTTP with a known good `X-Forwarded-Protocol`. We'll use that to route HTTPS and redirect HTTP. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: lb-listener -spec: - port: 8443 - protocol: HTTP - securityModel: XFP - l7Depth: 1 - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: "foo.example.com" - requestPolicy: - insecure: - action: Redirect -``` - -- We set `l7Depth` to 1 to indicate that there's a single trusted L7 load balancer ahead of us. -- We specifically set this Listener to HTTP-only, but we stick with port 8443 just because we expect people setting up TLS at all to expect to use port 8443. (There's nothing special about the port number, pick whatever you like.) -- Our `Host` does not specify a `tlsSecret`, so $productName$ will not try to terminate TLS. -- Since the `Listener` still pays attention to `X-Forwarded-Proto`, both secure and insecure requests - are possible, and we use the `Host` to route HTTPS and redirect HTTP. - - - - Learn more about Listener
- Learn more about Host - - -### Using a Split L4 Load Balancer to Terminate TLS - -Here, we assume that $productName$ is behind a load balancer setup that handles TLS at layer 4: - -- Incoming cleartext traffic is forwarded to $productName$ on port 8080. -- Incoming TLS traffic is terminated at the load balancer, then forwarded to $productName$ _as cleartext_ on port 8443. -- This might involve multiple L4 load balancers, but the actual number doesn't matter. -- The actual port numbers we use don't matter either, as long as $productName$ and the load balancer(s) agree on which port is for which traffic. - -We're going to route HTTPS for both `foo.example.com` and `bar.example.com`, redirect HTTP for `foo.example.com`, and reject HTTP for `bar.example.com`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: split-lb-one-listener -spec: - protocol: HTTP - port: 8080 - securityModel: INSECURE - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: split-lb-two-listener -spec: - protocol: HTTP - port: 8443 - securityModel: SECURE - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - requestPolicy: - insecure: - action: Reject -``` - -- Since L4 load balancers cannot set `X-Forwarded-Protocol`, we don't use it at all here: instead, we dictate that 8080 and 8443 both speak cleartext HTTP, but everything arriving at port 8080 is insecure and everything at port 8443 is secure. - - - - Learn more about Listener
- Learn more about Host - - -### Listening on Multiple Ports - -There's no reason you need to use ports 8080 and 8443, or that you're limited to two ports. Here we'll use ports 9001 and 9002 for HTTP, and port 4001 for HTTPS. We'll route traffic irrespective of protocol. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-9001 -spec: - protocol: HTTP - port: 9001 - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-9002 -spec: - protocol: HTTP - port: 9002 - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-4001 -spec: - protocol: HTTPS - port: 4001 - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: route-host -spec: - requestPolicy: - insecure: - action: Route -``` - -- We can use `X-Forwarded-Proto` for all our `Listener`s: the HTTP-only `Listener`s will set it correctly. -- Each `Listener` can specify only one port, but there's no hardcoded limit on the number of `Listener`s you can have. - - - - Learn more about Listener
- Learn more about Host - - -### Using Labels to Associate `Host`s and `Listener`s - -In the examples above, the `Listener`s all associate with any `Host` in their namespace. In this -example, we will use Kubernetes labels to control the association instead. - -Here, we'll listen for HTTP to `foo.example.com` on port 8888, and for either HTTP or HTTPS to `bar.example.com` on -port 9999 (where we'll redirect HTTP to HTTPS). Traffic to `baz.example.com` will work on both ports, and we'll route -HTTP for it rather than redirecting. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-8888 -spec: - protocol: HTTP - port: 8888 - securityModel: XFP - hostBinding: - selector: - matchLabels: - tenant: foo ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-9999 -spec: - protocol: HTTPS - port: 9999 - securityModel: XFP - hostBinding: - selector: - matchLabels: - tenant: bar ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: bar-secret -data: - tls.crt: -wildcard here- - tls.key: -wildcard here- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host - labels: - tenant: foo -spec: - hostname: foo.example.com - requestPolicy: - insecure: - action: Route ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host - labels: - tenant: bar -spec: - hostname: bar.example.com - tlsSecret: - name: bar-secret ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: baz-host - labels: - tenant: foo - tenant: bar -spec: - hostname: baz.example.com - tlsSecret: - name: bar-secret - requestPolicy: - insecure: - action: Route -``` - -- Note the `labels` on each `Host`, which the `hostBinding` on the `Listener` can reference. - - Note also that only label selectors are supported at the moment. - - - - Learn more about Listener
- Learn more about Host - - -### Wildcard `Host`s and `Mapping`s - -In a `Mapping`, the `host` is now treated as a glob rather than an exact match, with the goal of vastly reducing the need for `host_regex`. (The `hostname` in a `Host` has always been treated as a glob). - -- **Note that only prefix and suffix matches are supported**, so `*.example.com` and `foo.*` are both fine, but `foo.*.com` will not work -- you'll need to use `host_regex` if you really need that. (This is an Envoy limitation.) - -In this example, we'll accept both HTTP and HTTPS, but: - -- Cleartext traffic to any host in `lowsec.example.com` will be routed. -- Cleartext traffic to any host in `normal.example.com` will be redirected. -- Any other cleartext traffic will be rejected. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: example-secret -data: - tls.crt: -wildcard for *.example.com here- - tls.key: -wildcard for *.example.com here- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-8443 -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: lowsec-host -spec: - hostname: "*.lowsec.example.com" - tlsSecret: - name: example-secret - requestPolicy: - insecure: - action: Route ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: normal-host -spec: - hostname: "*.normal.example.com" - tlsSecret: - name: example-secret - requestPolicy: # We could leave this out since - insecure: # redirecting is the default, but - action: Redirect # it's spelled out for clarity. ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: catchall-host -spec: - hostname: "*.example.com" - tlsSecret: - name: example-secret - requestPolicy: - insecure: - action: Reject -``` - -- We'll listen for HTTP or HTTPS on port 8443. -- The three `Host`s apply different insecure routing actions depending on the hostname. -- You could also do this with `host_regex`, but using `host` with globs will give better performance. - - Being able to _not_ associate a given `Mapping` with a given `Host` when the `Mapping`'s - `host` doesn't match helps a lot when you have many `Host`s. - - Reliably determining if a regex (for the `Mapping`) matches a glob (for the `Host`) isn't really possible, so we can't prune `host_regex` `Mapping`s at all. - - - Learn more about Listener
- Learn more about Host - diff --git a/content/en/docs/3.3/howtos/consul.md b/content/en/docs/3.3/howtos/consul.md deleted file mode 100644 index d75e35ce..00000000 --- a/content/en/docs/3.3/howtos/consul.md +++ /dev/null @@ -1,564 +0,0 @@ - -import Alert from '@material-ui/lab/Alert'; - -# Consul integration - -
-

Contents

- -- [Consul integration](#consul-integration) - - [Architecture overview](#architecture-overview) - - [Installing Consul](#installing-consul) - - [Installing $productName$](#installing-consul) - - [Using Consul for service discovery](#using-consul-for-service-discovery) - - [Using Consul for authorization and encryption](#using-consul-for-authorization-and-encryption) - - [Environment variables](#environment-variables) - - [More information](#more-information) - -
- -[Consul](https://www.consul.io) is a widely used service mesh. -$productName$ natively supports service discovery and unauthenticated -communication to services in Consul. Additionally, the *Ambassador -Consul Connector* enables $productName$ to encrypt and authenticate -its communication via mTLS with services in Consul that make use of -[Consul's *Connect* feature](https://www.consul.io/docs/connect). - -## Architecture overview - -Using Consul with $productName$ is particularly useful when deploying -$productName$ in hybrid cloud environments where you deploy -applications on VMs and Kubernetes. In this environment, Consul -enables $productName$ to securely route over TLS to any application -regardless of where it is deployed. - -In this architecture, Consul serves as the source of truth for your -entire data center, tracking available endpoints, service -configuration, and secrets for TLS encryption. New applications and -services automatically register themselves with Consul using the -Consul agent or API. When you send a request through $productName$, -$productName$ sends the request to an endpoint based on the data in -Consul. - -![ambassador-consul](../images/consul-ambassador.png) - -This guide first instructs you on registering a service with Consul -and using $productName$ to dynamically route requests to that service -based on Consul's service discovery data, and subsequently instructs -you on using using the Ambassador Consul Connector to use Consul for -authorizing and encrypting requests. - -## Installing Consul - -If you already have Consul installed in your cluster, then go ahead -and skip to the next section. - -1. Before you install Consul, make sure to check the Consul - documentation for any setup steps specific to your platform. Below - you can find setup guides for some of the more popular Kubernetes - platforms. This step is primarily to ensure you have the proper - permissions to set up Consul. You can skip these guides if your - cluster is already configured to grant you the necessary - permissions. - - - [Microsoft Azure Kubernetes Service (AKS)](https://learn.hashicorp.com/tutorials/consul/kubernetes-aks-azure?utm_source=consul.io&utm_medium=docs) - - [Amazon Elastic Kubernetes Service (EKS)](https://learn.hashicorp.com/tutorials/consul/kubernetes-eks-aws?utm_source=consul.io&utm_medium=docs) - - [Google Kubernetes Engine (GKE)](https://learn.hashicorp.com/tutorials/consul/kubernetes-gke-google?utm_source=consul.io&utm_medium=docs) - - - - If you did not find your Kubernetes platform above, check the - [Consul documentation here](https://www.consul.io/docs/k8s) to see - if there are specific setup instructions for your platform. - - - -2. Add the Hashicorp repository for installing Consul with Helm. If - you do not have Helm installed, you can find an [installation guide - here](https://helm.sh/docs/intro/install/). - - ```shell - helm repo add hashicorp https://helm.releases.hashicorp.com - ``` - -3. Create a new `consul-values.yaml` YAML file for the Consul - installation values and copy the values below into that file. - - ```yaml - global: - datacenter: dc1 - - ui: - service: - type: 'LoadBalancer' - - syncCatalog: - enabled: true - - server: - replicas: 1 - bootstrapExpect: 1 - - connectInject: - enabled: true - ``` - - - - Note: you are free to change the value of the `datacenter` field in - the install values. This is the the name of your Consul - Datacenter. - - - -4. Install Consul with Helm using the `consul-values.yaml` values file - you just created. - - ```shell - helm install -f consul-values.yaml hashicorp hashicorp/consul - ``` - -## Installing $productName$ - -If you have not already installed $productName$ in to your cluster, -then go to the [quick start guide](../../tutorials/getting-started) -before continuing any further in this guide. - -## Using Consul for service discovery - -This section of the guide instructs you on configuring $productName$ -to look for services registered to Consul, registering a demo -application with Consul, and configuring $productName$ to route to -this application using endpoint data from Consul. - -In this tutorial, you deploy the application in Kubernetes. However, -this application can be deployed anywhere in your data center, such as -on a VM. - -1. Configure $productName$ to look for services registered to Consul - by creating the `ConsulResolver`. Use `kubectl` to apply the - following manifest: - - ```shell - kubectl apply -f < - - **Note:** If you changed the name of your `datacenter` in the - Consul install values, make sure to change it in the resolver above - to match the name of your datacenter. - - If you changed the name of the helm install from `hashicorp` to - another value, make sure to update the value of the `address` field - in your resolver to match it. - - If you are having trouble figuring out what your `address` field - should be, it follow this format: - `http://{consul_server_pod}.{consul_server_service}.{namespace}.svc.cluster.local:{consul_port}`. - The default Consul port should be `8500` unless you changed it. - - - - This tells $productName$ that Consul is a service discovery endpoint. - - You must set the resolver to your `ConsulResolver` on a - per-`Mapping` basis, otherwise for that `Mapping` $productName$ - uses the default resolver. That is, in order for a `Mapping` to - make use of a service registered in Consul, you need to add - `resolver: consul-dc1` to that `Mapping`. - - For more information about resolver configuration, see the - [resolver reference documentation](../../topics/running/resolvers). - (If you're using Consul deployed elsewhere in your data center, - make sure the `address` points to your Consul FQDN or IP address). - -2. Deploy the Quote demo application. Use `kubectl` to - apply the following manifest: - - ```shell - kubectl apply -f < - - The `SERVICE_NAME` environment variable in the `quote-consul` - `Deployment` specifies the service name for Consul. The default - value is set to "quote-consul", so you only need to include it if - you want to change the service name. - - - - The Quote application contains code to automatically - register itself with Consul, using the `CONSUL_IP` and `POD_IP` - environment variables specified within the `quote-consul` container - spec. - - When you apply this manifest, it registers the `Pod` in the - `quote-consul` `Deployment` as a Consul service with the name - `quote-consul` and the IP address of the `Pod`. - - - - The `"consul.hashicorp.com/connect-inject": "false"` annotation - tells Consul that for this `Deployment` you do not want to use the - sidecar proxy that is part of Consul's Connect feature. Without - Consul's sidecar, the service needs to include code to make a - request to Consul to register the service. The manifest includes - the environment variables `CONSUL_IP`, `POD_IP`, and `SERVICE_NAME` - to provide the Quote service with enough information - to build that request and send it to Consul. To see how this code - works, see our [our Git repo for the Quote - service](https://github.com/datawire/quote). - - - -3. Verify the `quote-consul` `Deployment`'s `Pod` has been registered - with Consul. You can verify this by accessing the Consul UI. - - First use `kubectl port-forward` to make the UI available on your - local workstation: - - ```shell - kubectl port-forward service/hashicorp-consul-ui 8500:80 - ``` - - Then, while the port-forward is running, go to - http://localhost:8500/ in a web browser. You should see a service - named `quote-consul`. - - After you have verified that you see the `quote-consul` service in - your web browser, you may kill the port-forward. - - - - Port forwarding not working for you? Make sure the service name - matches your Consul UI service by checking `kubectl get svc -A` - - - -4. Configure $productName$ to make use of this `quote-consul` service. - Use `kubectl` to apply the following manifest: - - ```shell - kubectl apply -f < - -**Congratulations!** You're successfully routing traffic to the Quote -application, the location of which is registered in -Consul. - - - -## Using Consul for authorization and encryption - -In this part of the guide, you'll install a different version of the -demo application that now uses Consul's *Connect* feature to authorize -its incoming connections using mTLS, and install *Ambassador Consul -Connector* to enable $productName$ to authenticate to such services. - -The following steps assume you've already set up Consul for service -discovery, as detailed above. - -1. The Ambassador Consul Connector retrieves the TLS certificate - issued by the Consul CA and stores it in a Kubernetes `Secret` for - $productName$ to use. Deploy the Ambassador Consul Connector with - `kubectl`: - - ```shell - kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/consul/ambassador-consul-connector.yaml - ``` - - This installs in to your cluster: - - - RBAC resources. - - The Ambassador Consul Connector service. - - A `TLSContext` named `ambassador-consul` to load the - `ambassador-consul-connect` `Secret` into $productName$. - -2. Deploy a new version of the demo application, and configure it to - inject the Consul Connect sidecar by setting - `"consul.hashicorp.com/connect-inject"` to `true`. Note that in - this version of the configuration, you do not have to configure - environment variables for the location of the Consul server. Use - `kubectl` to apply the following manifest: - - ```yaml - kubectl apply -f - < - - Note: Annotations are used to attach metadata to Kubernetes - objects. You can use annotations to link external information to - objects, working in a similar, yet different, fashion to labels. - For more information on annotations, refer to the [Annotating - Kubernetes Services for - Humans](https://kubernetes.io/blog/2021/04/20/annotating-k8s-for-humans/) - article, or get started with annotations in your own cluster with - the [Ambassador Cloud Quick start - guide](https://www.getambassador.io/docs/cloud/latest/service-catalog/quick-start/). - - - - This deploys a demo application `Deployment` called `quote-connect` - (different than the `quote-consul` `Deployment` in the previous - section) with the Consul Connect sidecar proxy. The Connect - sidecar registers the application with Consul, requires TLS to - access the application, and exposes other [Consul Service - Segmentation](https://www.consul.io/docs/connect) features. - - The annotation `consul.hashicorp.com/connect-inject` being set to - `true` in this `Deployment` tells Consul that you want this - `Deployment` to use the Consul Connect sidecar. The sidecar - proxies requests to the service that it is attached to. Keep this - in mind mind when debug requests to the service. - -4. Verify the `quote-connect` `Deployment`'s `Pod` has been registered - with Consul. You can verify this by accessing the Consul UI. - - First use `kubectl port-forward` to make the UI available on your - local workstation: - - ```shell - kubectl port-forward service/hashicorp-consul-ui 8500:80 - ``` - - Then, while the port-forward is running, open - http://localhost:8500/ in a web browser. You should see a service - named `quote-connect`. - - After you have verified that you see the `quote-connect` service in - your web browser, you may kill the port-forward. - -5. Create a `Mapping` to configure $productName$ route to the - `quote-connect` service in Consul. Use `kubectl` to apply the - following manifest: - - ```shell - kubectl apply -f < - -**Congratulations!** You successfully configured the service to work -with the Consul Connect sidecar. - - - -### Environment variables - -The Ambassador Consul Connector can be configured with the following -environment variables. The defaults are best for most use-cases. - -| Environment Variable | Description | Default | -|------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------| -| `_AMBASSADOR_ID` | Set 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`) | `""` | -| `_CONSUL_HOST` | Set the IP or DNS name of the target Consul HTTP API server | `127.0.0.1` | -| `_CONSUL_PORT` | Set the port number of the target Consul HTTP API server | `8500` | -| `_AMBASSADOR_TLS_SECRET_NAME` | Set the name of the Kubernetes `v1.Secret` created by this program that contains the Consul-generated TLS certificate. | `$AMBASSADOR_ID-consul-connect` | -| `_AMBASSADOR_TLS_SECRET_NAMESPACE` | Set the namespace of the Kubernetes `v1.Secret` created by this program. | (same Namespace as the Pod running this integration) | - -## More information - -For more about $productName$'s integration with Consul, read the -[service discovery configuration](../../topics/running/resolvers) -documentation. diff --git a/content/en/docs/3.3/howtos/dist-tracing.md b/content/en/docs/3.3/howtos/dist-tracing.md deleted file mode 100644 index bc40df8f..00000000 --- a/content/en/docs/3.3/howtos/dist-tracing.md +++ /dev/null @@ -1,49 +0,0 @@ -# Explore distributed tracing and Kubernetes monitoring - -The Kubernetes monitoring and distributed tracing landscape is hard to grasp. Although this conceptual approach to [observability is nothing new](https://blog.getambassador.io/distributed-tracing-with-java-microdonuts-kubernetes-and-the-ambassador-api-gateway-ace15b62a89e) — companies like New Relic revolutionized single-application performance monitoring (APM) over a decade ago — it took a few years and the [Dapper publication](https://research.google/pubs/pub36356/) for this idea to migrate to distributed applications. The importance of this technology is only increasing, as more and more of us are building [“deep systems”](https://lightstep.com/deep-systems/). - -As the industry is slowly but surely maturing, standardization is underway. Standardization means proprietary vendor solutions and open source projects are able to collaborate, making our lives easier. For newcomers, understanding the plethora of options, concepts, specifications, and implementations available is still a daunting task: - -* How are Zipkin and Jaeger related? -* What is header propagation? -* Which headers format should I use? -* Who owns the initialization of a trace context? -* How are the data points collected? - -The [K8s Initializer](https://app.getambassador.io/initializer/) can make it easy to enable distributed tracing in any microservices-based system by offering an opinionated and preconfigured application stack that will get you up and running in no time. This way, you can focus on understanding your service topology and interactions rather than waste days on attempting to understand competing standard integrations and tuning configuration switches. - -## One-Click Tracing Configuration with the K8s Initializer - -The K8s Initializer is a tool we built for you to quickly bootstrap any Kubernetes cluster with your own application-ready playground. It will generate YAML manifests for ingress, observability, and more in just a few clicks. Once installed on a local or remote Kubernetes cluster, the generated Kubernetes manifest resources will give you a perfect sandbox environment to deploy your own applications and explore standard integrations. - -Specifically for observability and distributed tracing, the K8s Initializer bundles a Jaeger installation to collect and visualize traces along with a pre-configured Ambassador Edge Stack acting as the ingress controller that will create a trace context on every request. A single selection is required. - -As per the option we selected, we’ll be generating Zipkin-format traces and use B3 headers for propagation between our services. There you have it! Instrument your Java, Python, Golang or Node.js applications with Zipkin and B3 header propagation libraries, then configure your code to send the trace data to the `jaeger-collector.monitoring:9411` service endpoint. - -All that is left to do is making a few requests and visualizing the trace data in the Jaeger UI. - -## Visualizing Trace Data - -As we installed the Ambassador Edge Stack as our ingress controller for Kubernetes via the K8s Initializer, it will instrument parent trace spans for each request coming into our Kubernetes cluster from the internet. The K8s Initializer also pre-configured Ambassador to exposes the Jaeger UI on a subpath: `https://$AMBASSADOR_IP/jaeger/` - -Simply by visiting this URL on our installation, we are able to visualize the generated and collected trace information emitted by our Ambassador installation: - -![Jaeger screenshot](../images/jaeger.png) - -## Tracing the Future: OpenTelemetry - -The [OpenTelemetry project](https://opentelemetry.io/) was created with the intent of stopping the proliferation of API standards and libraries one might need to support for all their observability needs, effectively replacing the Zipkin-API, OpenCensus, OpenTracing and more competing implementations. - -> OpenTelemetry provides a single set of APIs, libraries, agents, and collector services to capture distributed traces and metrics from your application. You can analyze them using Prometheus, Jaeger, and other observability tools.
--[https://opentelemetry.io/](https://opentelemetry.io/) - -It’s at this point in the conversation that someone inevitably mentions that XKCD... - -![XKCD #927](../images/xkcd.png) - -OpenTelemetry ultimately supports multiple formats in its [OpenTelemetry-Collector](https://github.com/open-telemetry/opentelemetry-collector), easing the transition from one technology to another when installed as a middleware and translator to relay trace data to other collectors. Along with many of its long-awaited features, it supports multiple trace exporters for Jaeger, Zipkin and proprietary APIs. - -## Learn More -In this tutorial, we’ve shown you how to monitor your Kubernetes application with distributed tracing in just a few clicks with the K8s Initializer. To learn more about these tools and distributed tracing, we also recommend [A Complete Guide to Distributed Tracing by the Lightstep Team](https://lightstep.com/distributed-tracing/). - -We also have guides to setup Edge Stack with [Datadog](../tracing-datadog/), [Zipkin](../tracing-zipkin/), and [Prometheus and Grafana](../prometheus). diff --git a/content/en/docs/3.3/howtos/external-dns.md b/content/en/docs/3.3/howtos/external-dns.md deleted file mode 100644 index f0f51dbb..00000000 --- a/content/en/docs/3.3/howtos/external-dns.md +++ /dev/null @@ -1,130 +0,0 @@ -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 - -Start by checking the [ExternalDNS repo's deployment instructions](https://github.com/kubernetes-sigs/external-dns#deploying-to-a-cluster) to get information about the supported DNS providers and steps to setup ExternalDNS for your provider. Each DNS provider will have its own required steps as well as annotations, arguments, and permissions needed for the following configuration. - - -### Installation - -Configuration for a `ServiceAccount`, `ClusterRole`, and `ClusterRoleBinding` are necessary for the ExternalDNS deployment to support compatability 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 above for annotations and arguments for your DNS Provider. - - -1. Create a YAML file named `externaldns-config.yaml`, and copy the following configuration into it. - - - Ensure that the apiGroups include "getambassador.io" following "networking.k8s.io" and the resources include "hosts" after "ingresses". - - - ```yaml - --- - apiVersion: v1 - kind: ServiceAccount - metadata: - name: external-dns - annotations: - eks.amazonaws.com/role-arn: {ARN} # AWS ARN role - --- - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRole - metadata: - name: external-dns - rules: - - apiGroups: [""] - resources: ["services","endpoints","pods"] - verbs: ["get","watch","list"] - - apiGroups: ["extensions","networking.k8s.io", "getambassador.io"] - resources: ["ingresses", "hosts"] - verbs: ["get","watch","list"] - - apiGroups: [""] - resources: ["nodes"] - verbs: ["list","watch"] - --- - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRoleBinding - metadata: - name: external-dns-viewer - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: external-dns - subjects: - - kind: ServiceAccount - name: external-dns - namespace: default - --- - apiVersion: apps/v1 - kind: Deployment - metadata: - name: external-dns - spec: - strategy: - type: Recreate - selector: - matchLabels: - app: external-dns - template: - metadata: - labels: - app: external-dns - annotations: - iam.amazonaws.com/role: {ARN} # AWS ARN role - spec: - serviceAccountName: external-dns - containers: - - name: external-dns - image: registry.opensource.zalan.do/teapot/external-dns:latest - args: - - --source=ambassador-host - - --domain-filter=example.net # will make ExternalDNS see only the hosted zones matching provided domain, omit to process all available hosted zones - - --provider=aws - - --policy=upsert-only # would prevent ExternalDNS from deleting any records, omit to enable full synchronization - - --aws-zone-type=public # only look at public hosted zones (valid values are public, private or no value for both) - - --registry=txt - - --txt-owner-id= {Hosted Zone ID} # Insert Route53 Hosted Zone ID here - ``` - -2. Review the arguments section from the ExternalDNS deployment - - Configure or remove arguments to fit your needs. Additional arguments required for your DNS provider can be found by checking the [ExternalDNS repo's deployment instructions](https://github.com/kubernetes-sigs/external-dns#deploying-to-a-cluster). - - * `--source=ambassador-host` - required across all DNS providers to tell ExternalDNS to look for hostnames in the $productName$ `Host` configurations. - -3. Apply the above config with the following command to deploy ExternalDNS to your cluster and configure support for $productName$ - - ```shell - kubectl apply -f externaldns-ambassador.yaml - ``` - - - For the above example, ensure that you are using an EKS cluster, or register your cluster with AWS so that ExternalDNS can view and edit your AWS Hosted Zones. If you are using a cluster outside EKS and not registered with AWS you will see permissions errors from the ExternalDNS pod when attempting to list the Hosted Zones. - - -## Usage - -After applying the above configuration, ExternalDNS is ready to use. Configure a `Host` with the following annotation to allow ExternalDNS to get the IP address of your $productName$'s LoadBalancer and register it with your DNS provider. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: your-hostname - annotations: - external-dns.ambassador-service: $productDeploymentName$.$productNamespace$ -spec: - acmeProvider: - authority: none - hostname: your-hostname.example.com -``` - - -Victory! ExternalDNS is now running and configured to report $productName$'s IP and hostname with your DNS provider. diff --git a/content/en/docs/3.3/howtos/filter-dev-guide.md b/content/en/docs/3.3/howtos/filter-dev-guide.md deleted file mode 100644 index eefe8b6b..00000000 --- a/content/en/docs/3.3/howtos/filter-dev-guide.md +++ /dev/null @@ -1,97 +0,0 @@ -# Developing custom filters for routing - -Sometimes you may want $AESproductName$ to manipulate an incoming request. Some example use cases: - -* Inspect an incoming request, and add a custom header that can then be used for routing -* Add custom Authorization headers -* Validate an incoming request fits an OpenAPI specification before passing the request to a target service - -$AESproductName$ supports these use cases by allowing you to execute custom logic in `Filters`. Filters are written in Golang, and managed by $AESproductName$. If you want to write a filter in a language other than Golang, $AESproductName$ also has an HTTP/gRPC interface for Filters called `External`. - -## Prerequisites - -`Plugin` `Filter`s are built as [Go plugins](https://golang.org/pkg/plugin/) and loaded directly into the $AESproductName$ container so they can run in-process with the rest of $AESproductName$. - -To build a `Plugin` `Filter` into the $AESproductName$ container you will need -- Linux or MacOS host (Windows Subsystem for Linux is ok) -- [Docker](https://docs.docker.com/install/) -- [rsync](https://rsync.samba.org/) - -The `Plugin` `Filter` is built by `make` which uses Docker to create a stable build environment in a container and `rsync` to copy files between the container and your host machine. - -See the [README](https://github.com/datawire/apro-example-plugin) for more information on how the `Plugin` works. - -## Creating and deploying filters - -We've created an example filter that you can customize for your particular use case. - -1. Start with the example filter: `git clone - https://github.com/datawire/apro-example-plugin/`. - -2. Make code changes to `param-plugin.go`. Note: If you're developing a non-trivial filter, see the rapid development section below for a faster way to develop and test your filter. - -3. Run `make DOCKER_REGISTRY=...`, setting `DOCKER_REGISTRY` to point - to a registry you have access to. This will generate a Docker image - named `$DOCKER_REGISTRY/amb-sidecar-plugin:VERSION`. - -4. Push the image to your Docker registry: `docker push $DOCKER_REGISTRY/amb-sidecar-plugin:VERSION`. - -5. Configure $AESproductName$ to use the plugin by creating a `Filter` - and `FilterPolicy` CRD, as per the [filter reference](/docs/edge-stack/latest/topics/using/filters/). - -6. Update the standard $AESproductName$ manifest to use your Docker - image instead of the standard sidecar. - - ```patch - value: '60' - - name: AMBASSADOR_INTERNAL_URL - value: https://127.0.0.1:8443 - - image: docker.io/datawire/aes:$version$ - + image: DOCKER_REGISTRY/aes-plugin:VERSION - imagePullPolicy: Always - livenessProbe: - httpGet: - ``` - -## Rapid development of a custom filter - -During development, you may want to sidestep the deployment process for a faster development loop. The `aes-plugin-runner` helps you rapidly develop $AESproductName$ filters locally. - -To install the runner, download the latest version: - -Mac 64-bit | -Linux 64-bit - -Note that the plugin runner must match the version of $AESproductName$ that you are running. Place the binary somewhere in your `$PATH`. - -Information about open-source code used in `aes-plugin-runner` can be found by running `aes-plugin-runner --version`. - -Now, you can quickly test and develop your filter. - -1. In your filter directory, type: `aes-plugin-runner :8080 ./param-plugin.so`. -2. Test the filter by running `curl`: - - ``` - $ curl -Lv localhost:8080?db=2 - * Rebuilt URL to: localhost:8080/?db=2 - * Trying ::1... - * TCP_NODELAY set - * Connected to localhost (::1) port 8080 (#0) - > GET /?db=2 HTTP/1.1 - > Host: localhost:8080 - > User-Agent: curl/7.54.0 - > Accept: */* - > - < HTTP/1.1 200 OK - < X-Dc: Even - < Date: Mon, 25 Feb 2019 19:58:38 GMT - < Content-Length: 0 - < - * Connection #0 to host localhost left intact - ``` - -Note in the example above the `X-Dc` header is added. This lets you inspect the changes the filter is making to your HTTP header. - -## Further reading - -For more details about configuring filters and the `plugin` interface, see the [filter reference](/docs/edge-stack/latest/topics/using/filters/). diff --git a/content/en/docs/3.3/howtos/grpc.md b/content/en/docs/3.3/howtos/grpc.md deleted file mode 100644 index 3967ddf7..00000000 --- a/content/en/docs/3.3/howtos/grpc.md +++ /dev/null @@ -1,403 +0,0 @@ -# gRPC Connections - -$productName$ makes it easy to access your services from outside your application. This includes gRPC services, although a little bit of additional configuration is required: by default, Envoy connects to upstream services using HTTP/1.x and then upgrades to HTTP/2 whenever possible. However, gRPC is built on HTTP/2 and most gRPC servers do not speak HTTP/1.x at all. $productName$ must tell its underlying Envoy that your gRPC service only wants to speak to that HTTP/2, using the `grpc` attribute of a `Mapping`. - -## Writing a gRPC service for $productName$ - -There are many examples and walkthroughs on how to write gRPC applications so that is not what this article will aim to accomplish. If you do not yet have a service written you can find examples of gRPC services in all supported languages here: [gRPC Quickstart](https://grpc.io/docs/quickstart/) - -This document will use the [gRPC python helloworld example](https://github.com/grpc/grpc/tree/master/examples/python/helloworld) to demonstrate how to configure a gRPC service with $productName$. - -Follow the example up through [Run a gRPC application](https://grpc.io/docs/languages/python/quickstart/#run-a-grpc-application) to get started. - -### Dockerize - -After building our gRPC application and testing it locally, we need to package it as a Docker container and deploy it to Kubernetes. - -To run a gRPC application, we need to include the client/server and the protocol buffer definitions. - -For gRPC with python, we need to install `grpcio` and the common protos. - -```Dockerfile -FROM python:2.7 - -WORKDIR /grpc - -ENV PATH "$PATH:/grpc" - -COPY greeter_server.py /grpc -COPY helloworld_pb2.py /grpc -COPY helloworld_pb2_grpc.py /grpc - -RUN python -m pip install grpcio -RUN python -m pip install grpcio-tools googleapis-common-protos - -CMD ["python", "./greeter_server.py"] - -EXPOSE 50051 -``` - -Create the container and test it: - -``` -$ docker build -t /grpc_example -$ docker run -p 50051:50051 /grpc_example -``` - -Where `` is your Docker user or registry. - -Switch to another terminal and from the same directory, run the `greeter_client`. The output should be the same as running it outside of the container. - -``` -$ docker run -p 50051:50051 /grpc_example -Greeter client received: Hello, you! -``` - -Once you verify the container works, push it to your Docker registry: - -``` -$ docker push /grpc_example -``` - -### Mapping gRPC services - -$productName$ `Mapping`s are based on URL prefixes; for gRPC, the URL prefix is the full-service name, including the package path (`package.service`). These are defined in the `.proto` definition file. In the example [proto definition file](https://github.com/grpc/grpc/blob/master/examples/protos/helloworld.proto) we see: - -``` -package helloworld; - -// The greeting service definition. -service Greeter { ... } -``` - -so the URL `prefix` is `helloworld.Greeter` and the mapping would be: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py -spec: - hostname: "*" - grpc: True - prefix: /helloworld.Greeter/ - rewrite: /helloworld.Greeter/ - service: grpc-example -``` - -Note the `grpc: true` line - this is what tells Envoy to use HTTP/2 so the request can communicate with your backend service. Also note that you'll need `prefix` and `rewrite` the same here, since the gRPC service needs the package and service to be in the request to do the right thing. - -### Deploying to Kubernetes - -`grpc_example.yaml` - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - acmeProvider: - authority: none - requestPolicy: - insecure: - action: Route ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py -spec: - hostname: "*" - grpc: True - prefix: /helloworld.Greeter/ - rewrite: /helloworld.Greeter/ - service: grpc-example - ---- -apiVersion: v1 -kind: Service -metadata: - labels: - service: grpc-example - name: grpc-example -spec: - type: ClusterIP - ports: - - name: grpc-greet - port: 80 - targetPort: grpc-api - selector: - service: grpc-example ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: grpc-example -spec: - replicas: 1 - selector: - matchLabels: - service: grpc-example - template: - metadata: - labels: - service: grpc-example - spec: - containers: - - name: grpc-example - image: /grpc_example - ports: - - name: grpc-api - containerPort: 50051 - restartPolicy: Always -``` - -The Host is declared here because we are using gRPC without TLS. Since $productName$ terminates TLS by default, in the Host we add a `requestPolicy` which allows insecure connections. After adding the $productName$ mapping to the service, the rest of the Kubernetes deployment YAML file is pretty straightforward. We need to identify the container image to use, expose the `containerPort` to listen on the same port the Docker container is listening on, and map the service port (80) to the container port (50051). - -> For more information on insecure routing, please refer to the [`Host` documentation](../../topics/running/host-crd#secure-and-insecure-requests). - - -Once you have the YAML file and the correct Docker registry, deploy it to your cluster with `kubectl`. - -``` -$ kubectl apply -f grpc_example.yaml -``` - -### Testing the Deployment - -Make sure to test your Kubernetes deployment before making more advanced changes (like adding TLS). To test any service with $productName$, we will need the hostname of the running $productName$ service which you can get with: - -``` -$ kubectl get service ambassador -o wide -``` -Which should return something similar to: - -``` -NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE -ambassador 10.11.12.13 35.36.37.38 80:31656/TCP 1m -``` -where `EXTERNAL-IP` is the `$AMBASSADORHOST` and 80 is the `$PORT`. - -You will need to open the `greeter_client.py` and change `localhost:50051` to `$AMBASSADORHOST:$PORT` - -```diff -- with grpc.insecure_channel('localhost:50051') as channel: -+ with grpc.insecure_channel(‘$AMBASSADORHOST:$PORT’) as channel: - stub = helloworld_pb2_grpc.GreeterStub(channel) - response = stub.SayHello(helloworld_pb2.HelloRequest(name='you')) - print("Greeter client received: " + response.message) -``` - -After making that change, simply run the client again and you will see the gRPC service in your cluster respond: - -``` -$ python greeter_client.py -Greeter client received: Hello, you! -``` - -### gRPC and TLS - -There is some extra configuration required to connect to a gRPC service through $productName$ over an encrypted channel. Currently, the gRPC call is being sent over cleartext to $productName$ which proxies it to the gRPC application. - -![](../images/grpc-tls.png) - -If you want to add TLS encryption to your gRPC calls, first you need to tell $productName$ to add [ALPN protocols](../../topics/running/tls) which are required by HTTP/2 to do TLS. - -For example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls -spec: - hosts: - - "*" - secret: ambassador-cert - alpn_protocols: h2 -``` - -Next, you need to change the client code slightly and tell it to open a secure RPC channel with $productName$. - -```diff -- with grpc.insecure_channel(‘$AMBASSADORHOST:$PORT’) as channel: -+ with grpc.secure_channel(‘$AMBASSADORHOST:$PORT’, grpc.ssl_channel_credentials()) as channel: - stub = helloworld_pb2_grpc.GreeterStub(channel) - response = stub.SayHello(helloworld_pb2.HelloRequest(name='you')) - print("Greeter client received: " + response.message) -``` - -`grpc.ssl_channel_credentials(root_certificates=None, private_key=None, certificate_chain=None)`returns the root certificate that will be used to validate the certificate and public key sent by $productName$. The default values of `None` tells the gRPC runtime to grab the root certificate from the default location packaged with gRPC and ignore the private key and certificate chain fields. Generally, passing no arguments to the method that requests credentials gives the same behavior. Refer to the languages [API Reference](https://grpc.io/docs/) if this is not the case. - -$productName$ is now terminating TLS from the gRPC client and proxying the call to the application over cleartext. - -![](../images/gRPC-TLS-Ambassador.png) - -If you want to configure authentication in another language, [gRPC provides examples](https://grpc.io/docs/guides/auth.html) with proper syntax for other languages. - -#### Working with Host headers that include the port - -Some gRPC clients automatically include the port in the Host header. This is a problem when using TLS because the certificate will match `myurl.com` but the Host header will be `myurl.com:443`, resulting in the error `rpc error: code = Unimplemented desc =`. If you run into this issue, there are two ways to solve it depending on your use case, both using the Module resource. - -The first is to set the `strip_matching_host_port` [property](../../topics/running/ambassador#strip-matching-host-port) to `true`. However, this only works if the port in the header matches the port that Envoy listens on (8443 by default). In the default installation of $productName$, the public port is 443, which then maps internally to 8443, so this only works for custom installations where the public service port matches the port in the Listener resource. - -The second solution is to use the following [Lua script](../../topics/running/ambassador#lua-scripts), which always strips the port: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador - namespace: ambassador -spec: - config: - lua_scripts: | - function envoy_on_request(request_handle) - local authority = request_handle:headers():get(":authority") - if(string.find(authority, ":") ~= nil) - then - local authority_index = string.find(authority, ":") - local stripped_authority = string.sub(authority, 1, authority_index - 1) - request_handle:headers():replace(":authority", stripped_authority) - end - end -``` - -#### Originating TLS with gRPC service - -![](../images/gRPC-TLS-Originate.png) - -$productName$ can originate TLS with your gRPC service so the entire RPC channel is encrypted. To configure this, first get some TLS certificates and configure the server to open a secure channel with them. Using self-signed certs this can be done with OpenSSL and adding a couple of lines to the server code. - -```diff -def serve(): - server = grpc.server(futures.ThreadPoolExecutor(max_workers=10)) -+ with open('certs/server.key', 'rb') as f: -+ private_key = f.read() -+ with open('certs/server.crt', 'rb') as f: -+ cert_chain = f.read() -+ server_creds = grpc.ssl_server_credentials( ( (private_key, cert_chain), ) ) - helloworld_pb2_grpc.add_GreeterServicer_to_server(Greeter(), server) -- server.add_insecure_port('[::]:50052') -+ server.add_secure_port('[::]:50052', server_creds) - server.start() -``` - -Rebuild your docker container **making sure the certificates are included** and follow the same steps of testing and deploying to Kubernetes. You will need to make a small change to the client code to test locally. - -```diff -- with grpc.insecure_channel(‘localhost:$PORT’) as channel: -+ with grpc.secure_channel(‘localhost:$PORT’, grpc.ssl_channel_credentials(open('certs/server.crt', 'rb').read())) as channel: - stub = helloworld_pb2_grpc.GreeterStub(channel) - response = stub.SayHello(helloworld_pb2.HelloRequest(name='you')) - print("Greeter client received: " + response.message) -``` - -Once deployed we will need to tell $productName$ to originate TLS to the application. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py-tls -spec: - hostname: "*" - grpc: True - tls: upstream - prefix: /hello.Greeter/ - rewrite: /hello.Greeter/ - service: https://grpc-py - ---- -apiVersion: v1 -kind: Service -metadata: - labels: - service: grpc-py - name: grpc-py -spec: - type: ClusterIP - ports: - - name: grpc-greet - port: 443 - targetPort: grpc-api - selector: - service: grpc-py -``` - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: upstream -spec: - alpn_protocols: h2 - secret: ambassador-cert -``` - -We need to tell $productName$ to route to the `service:` over https and have the service listen on `443`. We also need to tell $productName$ to use ALPN protocols when originating TLS with the application, the same way we did with TLS termination. This is done by setting `alpn_protocols: ["h2"]` in a `TLSContext` telling the service to use that tls-context in the mapping by setting `tls: upstream`. - -Refer to the [TLS document](../../topics/running/tls/origination#advanced-configuration-using-a-tlscontext) for more information on TLS origination. - -### gRPC headers - -gRPC services use [HTTP/2 headers](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md). This means that some header-based routing rules will need to be rewritten to support HTTP/2 headers. For example, `host: subdomain.host.com` needs to be rewritten using the `headers: ` attribute with the `:authority` header: - -``` -headers: - :authority: subdomain.host.com -``` - -## Note - -### Ingress controllers - -Some [Kubernetes ingress controllers](https://kubernetes.io/docs/concepts/services-networking/ingress/) do not support HTTP/2 fully. As a result, if you are running $productName$ with an ingress controller in front, you may find that gRPC requests fail even with correct $productName$ configuration. - -A simple way around this is to use $productName$ with a `LoadBalancer` service, rather than an Ingress controller. You can also consider using [$productName$ as your Ingress Controller](../../topics/running/ingress-controller). - -### Mappings with hosts - -As with any `Mapping`, your gRPC service's `Mapping` may include a `host`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py -spec: - hostname: "*" - grpc: true - prefix: /helloworld.Greeter/ - rewrite: /helloworld.Greeter/ - service: grpc-example - host: api.example.com -``` - -Some gRPC client libraries produce requests where the `host` or `:authority` header includes the port number. For example, a request to the above service might include `host: api.example.com:443` instead of just `host: api.example.com`. To avoid having $productName$ return a 404 (not found) response to these requests due to the mismatched host, you may want to set `strip_matching_host_port` in the [Ambassador module](../../topics/running/ambassador#strip-matching-host-port). - -Alternately, you may find it cleaner to make sure your gRPC client does not include the port in the `host` header. Here is an example using gRPC/Go. - -```go -hostname := "api.example.com" -port := "443" -config := &tls.Config{ServerName: hostname} -creds := credentials.NewTLS(config) -opts := []grpc.DialOption{ - grpc.WithTransportCredentials(creds), -// ... -} -conn, err := grpc.Dial(hostname+":"+port, opts...) -// ... -``` - -## gRPC-Web - -$productName$ also supports the [gRPC-Web](../../topics/running/ambassador#grpc) protocol for browser-based gRPC applications. diff --git a/content/en/docs/3.3/howtos/http3-aks.md b/content/en/docs/3.3/howtos/http3-aks.md deleted file mode 100644 index 2f9be012..00000000 --- a/content/en/docs/3.3/howtos/http3-aks.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "$productName$ - HTTP/3 support for Azure Kubernetes Service (AKS)" -description: "How to configure HTTP/3 support for Azure Kubernetes Service (AKS). This guide shows how to setup the LoadBalancer service for AKS to support both TCP and UDP communications." ---- - -# Azure Kubernetes Service Engine HTTP/3 configuration - -This guide shows how to setup HTTP/3 support for Azure Kubernetes Service (AKS). The instructions provided in this page are a continuation of the [HTTP/3 in $productName$](../../topics/running/http3) documentation. - -## Configuring an external load balancer for AKS - -To configure an external load balancer for AKS, you need to: - -1. Reserve a public static IP address. -2. Create two `LoadBalancer` services, one for TCP and one for UDP. -3. Assign the public static IP address to the `loadBalancerIP` field. - -An example of the two load balancer services described above looks as follows: - -```yaml -# selectors and labels removed for clarity -apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$ - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - --- - apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$-udp - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http3 - port: 443 # Default support for HTTP/3 requires you to use 443 for the external client-facing port. - targetPort: 8443 - protocol: UDP - -``` - -In the above example, AKS generates two `LoadBalancer` services, one for UDP and the other for TCP. - - -You should verify that the Managed Identity or Serivce Principal has permissions to assign the IP address to the newly created LoadBalancer services. Refer to the Azure Docs - Managed Identity for more information. - diff --git a/content/en/docs/3.3/howtos/http3-eks.md b/content/en/docs/3.3/howtos/http3-eks.md deleted file mode 100644 index d09a1af5..00000000 --- a/content/en/docs/3.3/howtos/http3-eks.md +++ /dev/null @@ -1,252 +0,0 @@ ---- -title: "HTTP/3 with Amazon Elastic Kubernetes Service (EKS) | $productName$" -description: "How to configure HTTP/3 support for Amazon Elastic Kubernetes Service (EKS). This guide shows how to setup the LoadBalancer service for EKS to support both TCP and UDP communications." ---- - -# Amazon Elastic Kubernetes Service HTTP/3 configuration - -This guide shows how to setup HTTP/3 support for Amazon Elastic Kubernetes Service (EKS) The instructions provided in this page are a continuation of the [HTTP/3 in $productName$](../../topics/running/http3) documentation. - -## Create a network load balancer (NLB) - - The virtual private cloud (VPC) for your load balancer needs one public subnet in each availability zone where you have targets. - - ```shell - SUBNET_IDS=( ) - - aws elbv2 create-load-balancer \ - --name ${CLUSTER_NAME}-nlb \ - --type network \ - --subnets ${SUBNET_IDS} - ``` - -## Create a NodePort service - -Now create a `NodePort` service for $productName$ installation with two entries. Use `port: 443` to include support for both TCP and UDP traffic. - ```yaml - # Selectors and labels removed for clarity. - apiVersion: v1 - kind: Service - metadata: - name: $productDeploymentName$-http3 - namespace: $productNamespace$ - spec: - type: NodePort - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - nodePort: 30080 - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - nodePort: 30443 - - name: http3 - port: 443 - targetPort: 8443 - protocol: UDP - nodePort: 30443 - ``` - -## Create target groups - -Run the following command with the variables for your VPC ID and cluster name: - - ```shell - VPC_ID= - CLUSTER_NAME= - - aws elbv2 create-target-group --name ${CLUSTER_NAME}-tcp-tg \ - --protocol TCP --port 30080 --vpc-id ${VPC_ID} \ - --health-check-protocol TCP \ - --health-check-port 30080 \ - --target-type instance - - aws elbv2 create-target-group --name ${CLUSTER_NAME}-tcp-udp-tg \ - --protocol TCP_UDP --port 30443 --vpc-id ${VPC_ID} \ - --health-check-protocol TCP \ - --health-check-port 30443 \ - --target-type instance - ``` - -## Register your instances - -Next, register your cluster's instance with the the instance IDs and Amazon Resource Names (ARN). - -To get your cluster's instance IDs, enter the following command: - ```shell - aws ec2 describe-instances \ - --filters Name=tag:eks:cluster-name,Values=${CLUSTER_NAME} \ - --output text - --query 'Reservations[*].Instances[*].InstanceId' \ - ``` - -To get your ARNs, enter the following command: - ```shell - TCP_TG_NAME=${CLUSTER_NAME}-tcp-tg-name - TCP_UDP_TG_NAME=${CLUSTER_NAME}-tcp-udp-tg-name - - aws elbv2 describe-target-groups \ - --query 'TargetGroups[?TargetGroupName==`'${TCP_TG_NAME}'`].TargetGroupArn' \ - --output text - aws elbv2 describe-target-groups \ - --query 'TargetGroups[?TargetGroupName==`'${TCP_UDP_TG_NAME}'`]. TargetGroupArn' \ - --output text - ``` - -Register the instances with the target groups and load balancer using the instance IDs and ARNs you retrieved. - ```shell - INSTANCE_IDS=( ) - REGION= - TG_NAME= - TCP_TG_ARN=arn:aws:elasticloadbalancing:${REGION}:079.....:targetgroup/${TG_NAME}/... - TCP_UDP_TG_ARN=arn:aws:elasticloadbalancing:${REGION}:079.....:targetgroup/${TG_NAME}/... - - aws elbv2 register-targets --target-group-arn ${TCP_TG_ARN} --targets ${INSTANCE_IDS} - aws elbv2 register-targets --target-group-arn ${TCP_UDP_TG_ARN} --targets ${INSTANCE_IDS} - ``` - -## Create listeners in AWS. - -Register your cluster's instance with the instance IDs and ARNs. - -To get the load balancer's ARN, enter the following command: - ```shell - aws elbv2 describe-load-balancers --name ${CLUSTER_NAME}-nlb \ - --query 'LoadBalancers[0].LoadBalancerArn' \ - --output text - ``` - -Create a TCP listener on port 80 that that forwards to the TargetGroup {TCP_TG_ARN}. - ```shell - aws elbv2 create-listener --load-balancer-arn ${LB_ARN} \ - --protocol TCP --port 80 \ - --default-actions Type=forward,TargetGroupArn=${TCP_TG_ARN} - ``` - - Create a TCP_UDP listener on port 443 that forwards to the TargetGroup {TCP_UDP_TG_ARN}. - ```shell - aws elbv2 create-listener --load-balancer-arn ${LB_ARN} \ - --protocol TCP_UDP --port 443 \ - --default-actions Type=forward,TargetGroupArn=${TCP_UDP_TG_ARN} - ``` - -## Update the security groups - -Now you need to update your security groups to receive traffic. This security group covers all node groups attached to the EKS cluster: - ```shell - aws eks describe-cluster --name ${CLUSTER_NAME} | grep clusterSecurityGroupId - ``` - -Now authorize the cluster security group to allow internet traffic: - ```shell - for x in ${CLUSTER_SG}; do \ - aws ec2 authorize-security-group-ingress --group-id $$x --protocol tcp --port 30080 --cidr 0.0.0.0/0; \ - aws ec2 authorize-security-group-ingress --group-id $$x --protocol tcp --port 30443 --cidr 0.0.0.0/0; \ - aws ec2 authorize-security-group-ingress --group-id $$x --protocol udp --port 30443 --cidr 0.0.0.0/0; \ - done - ``` - -## Get the DNS name for the load balancers - -Enter the following command to get the DNS name for your load balancers and create a CNAME record at your domain provider: - ```shell - aws elbv2 describe-load-balancers --name ${CLUSTER_NAME}-nlb \ - --query 'LoadBalancers[0].DNSName' \ - --output text - ``` - -## Create Listener resources - -Now you need to create the `Listener` resources for $productName$. The first `Listener` in the example below handles traffic for HTTP/1.1 and HTTP/2, while the second `Listener` handles all HTTP/3 traffic. - - ```yaml - kubectl apply -f - < - acmeProvider: - authority: none - tlsSecret: - name: tls-cert # The QUIC network protocol requires TLS with a valid certificate - tls: - min_tls_version: v1.3 - max_tls_version: v1.3 - alpn_protocols: h2,http/1.1 - EOF - ``` - -## Apply the quote service and a Mapping to test the HTTP/3 configuration. - -Finally, apply the quote service to a $productName$ `Mapping`. - - ```shell - kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$version$/quickstart/qotm.yaml - kubectl apply -f - </backend/ - ``` -Your domain now shows that it is being served with HTTP/3. diff --git a/content/en/docs/3.3/howtos/http3-gke.md b/content/en/docs/3.3/howtos/http3-gke.md deleted file mode 100644 index 677e89e3..00000000 --- a/content/en/docs/3.3/howtos/http3-gke.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: "$productName$ - HTTP/3 support for Google Kubernetes Engine (GKE)" -description: "How to configure HTTP/3 support for Google Kubernetes Engine (GKE). This guide shows how to setup the LoadBalancer service for GKE to support both TCP and UDP communications." ---- - -# Google Kubernetes Service Engine HTTP/3 configuration - -This guide shows how to setup HTTP/3 support for Google Kubernetes Engine (GKE). The instructions provided in this page are a continuation of the [HTTP/3 in $productName$](../../topics/running/http3) documentation. - -## Configuring an external load balancer for GKE - -Currently, GKE only supports adding feature flags to `alpha` clusters, and doesn't support the creation of mixed protocol services of type `LoadBalancer`. To configure an external load balancer for GKE, you need to: - -1. Reserve a public static IP address. -2. Create two `LoadBalancer` services, one for TCP and one for UDP. -3. Assign the public static IP address to the `loadBalancerIP` field. - -An example of the two load balancer services described above looks as follows: - -```yaml -# selectors and labels removed for clarity -apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$ - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - --- - apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$-udp - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http3 - port: 443 # Default support for HTTP/3 requires you to use 443 for the external client-facing port. - targetPort: 8443 - protocol: UDP - -``` - -In the above example, GKE generates two `LoadBalancer` services, one for UDP and the other for TCP. diff --git a/content/en/docs/3.3/howtos/index.md b/content/en/docs/3.3/howtos/index.md deleted file mode 100644 index f16cdd46..00000000 --- a/content/en/docs/3.3/howtos/index.md +++ /dev/null @@ -1,25 +0,0 @@ -# "How-to" guides - -These guides are designed to help users quickly accomplish common tasks. The guides assume a certain level of understanding of $productName$. Many of these guides are contributed by third parties; we welcome contributions via Pull Request at https://github.com/emissary-ingress/emissary. - -* Integrating with Service Mesh. $productName$ natively integrates with many service meshes. - * [HashiCorp Consul](consul) - * [Istio](istio) - * [Linkerd](linkerd2) -* Distributed tracing. $productName$ natively supports a number of distributed tracing systems to enable developers to visualize request flow in microservice and service-oriented architectures. - * [Datadog](tracing-datadog) - * [Zipkin](tracing-zipkin) -* Monitoring. $productName$ integrates with a number of different monitoring/metrics providers. - * [Prometheus](prometheus) -* [Developing Custom Filters](filter-dev-guide) -* Frameworks and Protocols. $productName$ supports a wide range of protocols and cloud-native frameworks. - * [gRPC](grpc) - * [Knative Serverless Framework](knative) - * [WebSockets](websockets) -* Security. $productName$ supports a number of strategies for securing Kubernetes services. - * [Protecting the Diagnostics Interface](protecting-diag-access) - * [HTTPS and TLS termination](tls-termination) - * [Certificate Manager](cert-manager) can be used to automatically obtain and renew TLS certificates; $AESproductName$ natively integrates this functionality. - * [Client Certificate Validation](client-cert-validation) - * [Basic Authentication](basic-auth) is a tutorial on how to use the external authentication API to code your own authentication service. - * [Basic Rate Limiting](rate-limiting-tutorial) diff --git a/content/en/docs/3.3/howtos/istio.md b/content/en/docs/3.3/howtos/istio.md deleted file mode 100644 index 6fa74fcf..00000000 --- a/content/en/docs/3.3/howtos/istio.md +++ /dev/null @@ -1,445 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Istio integration - -$productName$ and Istio: Edge Proxy and Service Mesh together in one. $productName$ is deployed at the edge of your network and routes incoming traffic to your internal services (aka "north-south" traffic). [Istio](https://istio.io/) is a service mesh for microservices, and is designed to add application-level Layer (L7) observability, routing, and resilience to service-to-service traffic (aka "east-west" traffic). Both Istio and $productName$ are built using [Envoy](https://www.envoyproxy.io). - -$productName$ and Istio can be deployed together on Kubernetes. In this configuration, $productName$ manages -traditional edge functions such as authentication, TLS termination, and edge routing. Istio mediates communication -from $productName$ to services, and communication between services. - -This allows the operator to have the best of both worlds: a high performance, modern edge service ($productName$) combined with a state-of-the-art service mesh (Istio). While Istio has introduced a [Gateway](https://istio.io/latest/docs/tasks/traffic-management/ingress/ingress-control/#configuring-ingress-using-an-istio-gateway) abstraction, $productName$ still has a much broader feature set for edge routing than Istio. For more on this topic, see our blog post on [API Gateway vs Service Mesh](https://blog.getambassador.io/api-gateway-vs-service-mesh-104c01fa4784). - -This guide explains how to take advantage of both $productName$ and Istio to have complete control and observability over how requests are made in your cluster: - -- [Install Istio](#install-istio) and configure auto-injection -- [Install $productName$ with Istio integration](#install-edge) -- [Configure an mTLS `TLSContext`](#configure-an-mtls-tlscontext) -- [Route to services using mTLS](#route-to-services-using-mtls) - -If desired, you may also - -- [Enable strict mTLS](#enable-strict-mtls) -- [Configure Prometheus metrics collection](#configure-prometheus-metrics-collection) -- [Configure Istio distributed tracing](#configure-istio-distributed-tracing) - -To follow this guide, you need: - -- A Kubernetes cluster version 1.15 and above -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- Istio version 1.10 or higher - -## Install Istio - -Start by [installing Istio](https://istio.io/docs/setup/getting-started/). Any supported installation method for -Istio will work for use with $productName$. - -### Configure Istio Auto-Injection - -Istio functions by supplying a sidecar container running Envoy with every service in the mesh (including -$productName$). The sidecar is what enforces Istio policies for traffic to and from the service, notably -including mTLS encryption and certificate handling. As such, it is very important that the sidecar be -correctly supplied for every service in the mesh! - -While it is possible to manage sidecars by hand, it is far easier to allow Istio to automatically inject -the sidecar as necessary. To do this, set the `istio-injection` label on each Kubernetes Namespace for -which you want auto-injection: - -```yaml -kubectl label namespace $namespace istio-injection=enabled --overwrite -``` - - - The following example uses the `istio-injection` label to arrange for auto-injection in the - `$productNamespace$` Namespace below. You can manage sidecar injection by hand if you wish; what - is critical is that every service that participates in the Istio mesh have the Istio - sidecar. - - -## Install $productName$ with Istio Integration - -Properly integrating $productName$ with Istio provides support for: - -* [Mutual TLS (mTLS)](../../topics/running/tls/mtls/), with certificates managed by Istio, to allow end-to-end encryption -for east-west traffic; -* Automatic generation of Prometheus metrics for services; and -* Istio distributed tracing for end-to-end observability. - -The simplest way to enable everything is to install $productName$ using [Helm](https://helm.sh), though -you can use manual installation with YAML if you wish. - -### Installation with Helm (Recommended) - -To install with Helm, write the following YAML to a file called `istio-integration.yaml`: - -```yaml -# Listeners are required in $productName$ 2.0. -# This will create the two default Listeners for HTTP on port 8080 and HTTPS on port 8443. -createDefaultListeners: true - -# These are annotations that will be added to the $productName$ pods. -podAnnotations: - # These first two annotations tell Istio not to try to do port management for the - # $productName$ pod itself. Though these annotations are placed on the $productName$ - # pods, they are interpreted by Istio. - traffic.sidecar.istio.io/includeInboundPorts: "" # do not intercept any inbound ports - traffic.sidecar.istio.io/includeOutboundIPRanges: "" # do not intercept any outbound traffic - - # We use proxy.istio.io/config to tell the Istio proxy to write newly-generated mTLS certificates - # into /etc/istio-certs, which will be mounted below. Though this annotation is placed on the - # $productName$ pods, it is interpreted by Istio. - proxy.istio.io/config: | - proxyMetadata: - OUTPUT_CERTS: /etc/istio-certs - - # We use sidecar.istio.io/userVolumeMount to tell the Istio sidecars to mount the istio-certs - # volume at /etc/istio-certs, allowing the sidecars to see the generated certificates. Though - # this annotation is placed on the $productName$ pods, it is interpreted by Istio. - sidecar.istio.io/userVolumeMount: '[{"name": "istio-certs", "mountPath": "/etc/istio-certs"}]' - -# We define a single storage volume called "istio-certs". It starts out empty, and Istio -# uses it to communicate mTLS certs between the Istio proxy and the Istio sidecars (see the -# annotations above). -volumes: - - emptyDir: - medium: Memory - name: istio-certs - -# We also tell $productName$ to mount the "istio-certs" volume at /etc/istio-certs in the -# $productName$ pod. This gives $productName$ access to the mTLS certificates, too. -volumeMounts: - - name: istio-certs - mountPath: /etc/istio-certs/ - readOnly: true - -# Finally, we need to set some environment variables for $productName$. -env: - # AMBASSADOR_ISTIO_SECRET_DIR tells $productName$ to look for Istio mTLS certs, and to - # make them available as a secret named "istio-certs". - AMBASSADOR_ISTIO_SECRET_DIR: "/etc/istio-certs" - - # AMBASSADOR_ENVOY_BASE_ID is set to prevent collisions with the Istio sidecar's Envoy, - # which runs with base-id 0. - AMBASSADOR_ENVOY_BASE_ID: "1" -``` - -To install $productName$ with Helm, use these values to configure Istio integration: - -1. Create the `$productNamespace$` Namespace: - - ```yaml - kubectl create namespace $productNamespace$ - ``` - -2. Enable Istio auto-injection for it: - - ```yaml - kubectl label namespace $productNamespace$ istio-injection=enabled --overwrite - ``` - -3. Make sure the Helm repo is configured: - - ```bash - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - -4. Use Helm to install $productName$ in $productNamespace$: - - ```bash - helm install $productHelmName$ --namespace $productNamespace$ -f istio-integration.yaml datawire/$productHelmName$ && \ - kubectl -n $productNamespace$ wait --for condition=available --timeout=90s deploy -lapp.kubernetes.io/instance=$productDeploymentName$ - ``` - -### Installation Using YAML - -To install using YAML files, you need to manually incorporate the contents of the `istio-integration.yaml` -file shown above into your deployment YAML: - -* `pod-annotations` should be configured as Kubernetes `annotations` on the $productName$ Pods; -* `volumes`, `volumeMounts`, and `env` contents should be included in the $productDeploymentName$ Deployment; and -* you must also label the $productNamespace$ Namespace for auto-injection as described above. - -### Configuring an Existing Installation - -If you have already installed $productName$ and want to enable Istio: - -1. Install Istio. -2. Label the $productNamespace$ namespace for Istio auto-injection, as above. -2. Edit the $productName$ Deployments to contain the `annotations`, `volumes`, `volumeMounts`, and `env` elements - shown above. - * If you installed with Helm, you can use `helm upgrade` with `-f istio-integration.yaml` to modify the - installation for you. -3. Restart the $productName$ pods. - -## Configure an mTLS `TLSContext` - -After configuring $productName$ for Istio integration, the Istio mTLS certificates are available within -$productName$: - -- Both the `istio-proxy` sidecar and $productName$ mount the `istio-certs` volume at `/etc/istio-certs`. -- The `istio-proxy` sidecar saves the mTLS certificates into `/etc/istio-certs` (per the `OUTPUT_CERTS` - environment variable). -- $productName$ reads the mTLS certificates from `/etc/istio-certs` (per the `AMBASSADOR_ISTIO_SECRET_DIR` - environment variable) and creates a Secret named `istio-certs`. - - - At present, the Secret name istio-certs cannot be changed. - - -To make use of the `istio-certs` Secret, create a `TLSContext` referencing it: - - ```shell - $ kubectl apply -f - < - You must either explicitly specify port 80 in your 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 - <This guide applies to $OSSproductName$. It will not work correctly -on $AESproductName$. - -$productName$ can validate incoming requests before routing them to a backing service. In this tutorial, we'll configure $productName$ to use a simple third party rate limit service. (If you don't want to implement your own rate limiting service, $AESproductName$ integrates a [powerful, flexible rate limiting service](/docs/edge-stack/latest/topics/using/rate-limits/rate-limits/).) - -## Before you get started - -This tutorial assumes you have already followed the $productName$ [Installation](../../topics/install/) and [Quickstart Tutorial](../../tutorials/quickstart-demo) guides. If you haven't done that already, you should do so now. - -Once completed, you'll have a Kubernetes cluster running $productName$ and the Quote service. Let's walk through adding rate limiting to this setup. - -## 1. Deploy the rate limit service - -$productName$ delegates the actual rate limit logic to a third party service. We've written a [simple rate limit service](https://github.com/emissary-ingress/emissary/tree/v2.1.0/docker/test-ratelimit) that: - -- listens for requests on port 5000; -- handles gRPC `shouldRateLimit` requests; -- allows requests with the `x-ambassador-test-allow: "true"` header; and -- marks all other requests as `OVER_LIMIT`; - -Here's the YAML we'll start with: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: RateLimitService -metadata: - name: ratelimit -spec: - service: "example-rate-limit:5000" ---- -apiVersion: v1 -kind: Service -metadata: - name: example-rate-limit -spec: - type: ClusterIP - selector: - app: example-rate-limit - ports: - - port: 5000 - name: http-example-rate-limit - targetPort: http-api ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: example-rate-limit -spec: - replicas: 1 - strategy: - type: RollingUpdate - selector: - matchLabels: - app: example-rate-limit - template: - metadata: - labels: - app: example-rate-limit - spec: - containers: - - name: example-rate-limit - image: datawire/test_services:test-ratelimit:0.0.4 - imagePullPolicy: Always - ports: - - name: http-api - containerPort: 5000 - resources: - limits: - cpu: "0.1" - memory: 100Mi -``` - -This configuration tells $productName$ about the rate limit service, notably that it is serving requests at `example-rate-limit:5000`. $productName$ will see the `RateLimitService` and reconfigure itself within a few -seconds, allowing incoming requests to be rate-limited. - -Note that you can configure the `RateLimitService` to use a specific label `domain`. -If `domain` is not specified (which is the situation here), the default is `ambassador`. - -If $productName$ cannot contact the rate limit service, it will allow the request to be processed as if there were no rate limit service configuration. - -## 2. Configure $productName$ Mappings - -$productName$ only validates requests on `Mapping`s which set labels to use for rate limiting, -so you'll need to apply `labels` to your `Mapping`s to enable rate limiting. For more information -on the labelling process, see the [Rate Limits configuration documentation](../../topics/using/rate-limits/). - - - These labels require Mapping resources with apiVersion - getambassador.io/v2 or newer — if you're updating an old installation, check the - apiVersion! - - -If $productName$ cannot contact the rate limit service, it will allow the request to be processed as if there were no rate limit service configuration. - -Replace the label that is applied to the `service-backend` with: - -```yaml -labels: - ambassador: - - request_label_group: - - x-ambassador-test-allow: - request_headers: - key: "x-ambassador-test-allow" - header_name: "x-ambassador-test-allow" -``` - -so the `Mapping` definition will now look like this: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: "*" - prefix: /backend/ - service: quote - labels: - ambassador: - - request_label_group: - - x-ambassador-test-allow: - request_headers: - key: "x-ambassador-test-allow" - header_name: "x-ambassador-test-allow" -``` - - - -Note that the `key` could be anything you like, but our example rate limiting service expects it to -match the name of the header. Also note that since our `RateLimitService` expects to use labels in the -`ambassador` domain, our `Mapping` must match. - -## 2. Test rate limiting - -If we `curl` to a rate-limited URL: - -``` -$ curl -Lv -H "x-ambassador-test-allow: probably" $AMBASSADORURL/backend/ -``` - -We get a 429, since we are limited. - -``` -HTTP/1.1 429 Too Many Requests -content-type: text/html; charset=utf-8 -content-length: 0 -``` - -If we set the correct header value to the service request, we will get a quote successfully: - -``` -$ curl -Lv -H "x-ambassador-test-allow: true" $AMBASSADORURL/backend/ - -TCP_NODELAY set -* Connected to 35.196.173.175 (35.196.173.175) port 80 (#0) -> GET /backed HTTP/1.1 -> Host: 35.196.173.175 -> User-Agent: curl/7.54.0 -> Accept: */* -> -< HTTP/1.1 200 OK -< content-type: application/json -< date: Thu, 23 May 2019 15:25:06 GMT -< content-length: 172 -< x-envoy-upstream-service-time: 0 -< server: envoy -< -{ - "server": "humble-blueberry-o2v493st", - "quote": "Nihilism gambles with lives, happiness, and even destiny itself!", - "time": "2019-05-23T15:25:06.544417902Z" -* Connection #0 to host 54.165.128.189 left intact -} -``` - -## More - -For more details about configuring the external rate limit service, read the [rate limit documentation](../../topics/using/rate-limits/). diff --git a/content/en/docs/3.3/howtos/route.md b/content/en/docs/3.3/howtos/route.md deleted file mode 100644 index b2d9dc0f..00000000 --- a/content/en/docs/3.3/howtos/route.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -description: "$productName$ uses the Mapping resource to map a resource, like a URL prefix, to a Kubernetes service or web service." ---- - -import Alert from '@material-ui/lab/Alert'; - -# Get traffic from the edge - -
-

Contents

- -* [Examples](#examples) -* [Applying a Mapping Resource](#applying-a-mapping-resouce) -* [Resources](#resources) -* [Services](#services) -* [Extending Mappings](#extending-mappings) -* [Best Practices](#best-practices) -* [What's next?](#img-classos-logo-srcimageslogopng-whats-next) - -
- -The core $productName$ resource used to manage cluster ingress is the `Mapping` resource. - -**A `Mapping` resource routes a URL path (or prefix) to a service (either a Kubernetes service or other web service).** - - - Remember that Listener and Host resources are  - required for a functioning $productName$ installation that can route traffic!
- Learn more about Listener.
- Learn more about Host. - - -## Examples - -This `Mapping` would route requests to `https:///webapp/` to the `webapp-svc` Service. **This is not a -complete example on its own; see below.** - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: webapp-mapping -spec: - prefix: /webapp/ - service: webapp-svc -``` - -| Name | Type | Description | -| :--- | :--- | :--- | -| `metadata.name` | String | Identifies the Mapping. | -| `spec.prefix` | String | The URL prefix identifying your resource. [See below](#resources) on how $productName$ handles resources. | -| `spec.service` | String | The service handling the resource. If a Kubernetes service, it must include the namespace (in the format `service.namespace`) if the service is in a different namespace than $productName$. [See below](#services) on service name formatting.| - -Here's another example using a web service that maps requests to `/httpbin/` to `http://httpbin.org` (again, **this is not a -complete example on its own; see below**): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin-mapping -spec: - prefix: /httpbin/ - service: http://httpbin.org - hostname: '*' -``` - -### Complete example configuration - -For demonstration purposes, here's a possible way of combining a `Listener`, a `Host`, and both `Mapping`s above that is complete and functional: - -- it will accept HTTP or HTTPS on port 8443; -- $productName$ is terminating TLS; -- HTTPS to `foo.example.com` will be routed as above; -- HTTP to `foo.example.com` will be redirected to HTTPS; -- HTTP or HTTPS to other hostnames will be rejected; and -- the associations between the `Listener`, the `Host`, and the `Mappings` use Kubernetes `label`s. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: foo-example-secret -data: - tls.crt: -certificate PEM- - tls.key: -secret key PEM- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-8443 -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: - selector: - matchLabels: - exampleName: basic-https ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host - labels: - exampleName: basic-https -spec: - hostname: "foo.example.com" - tlsSecret: - name: foo-example-secret - selector: - matchLabels: - exampleName: basic-https ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: webapp-mapping - labels: - exampleName: basic-https -spec: - prefix: /webapp/ - service: webapp-svc - hostname: 'foo.example.com' ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin-mapping - labels: - exampleName: basic-https -spec: - prefix: /httpbin/ - service: http://httpbin.org - hostname: 'foo.example.com' - -``` - -Note the addition of `label`s and `selector`s to explicitly specify which resources should associate in this example. - - - Learn more about Listener.
- Learn more about Host. - - -## Applying a Mapping resource - -A Mapping resource can be managed using the same workflow as any other Kubernetes resources (like a Service or Deployment). For example, if the above Mapping is saved into a file called `httpbin-mapping.yaml`, the following command will apply the configuration directly to $productName$: - -``` -kubectl apply -f httpbin-mapping.yaml -``` - -For production use, best practice is to store the file in a version control system and apply the changes with a continuous deployment pipeline. The Ambassador Operating Model provides more detail. - -## Resources - -To $productName$, a resource is a group of one or more URLs that all share a common prefix in the URL path. For example, these URLs all share the `/resource1/` path prefix, so `/resource1/` can be considered a single resource: - -* `https://ambassador.example.com/resource1/foo` -* `https://ambassador.example.com/resource1/bar` -* `https://ambassador.example.com/resource1/baz/zing` - -On the other hand, these URLs share only the prefix `/` -- you _could_ tell $productName$ to treat them as a single resource, but it's probably not terribly useful. - -* `https://ambassador.example.com/resource1/foo` -* `https://ambassador.example.com/resource2/bar` -* `https://ambassador.example.com/resource3/baz/zing` - -Note that the length of the prefix doesn't matter; a prefix like `/v1/this/is/my/very/long/resource/name/` is valid. - -Also note that $productName$ does not actually require the prefix to start and end with `/` -- however, in practice, it's a good idea. Specifying a prefix of `/man` would match all of the following, which probably is not what was intended: - -* `https://ambassador.example.com/man/foo` -* `https://ambassador.example.com/mankind` -* `https://ambassador.example.com/man-it-is/really-hot-today` - -## Services - -$productName$ routes traffic to a service. A service is defined as `[scheme://]service[.namespace][:port]`. Everything except for the service is optional. - -- `scheme` can be either `http` or `https`; if not present, the default is `http`. -- `service` is the name of a service (typically the service name in Kubernetes or Consul); it is not allowed to contain the `.` character. -- `namespace` is the namespace in which the service is running. Starting with $productName$ 1.0.0, if not supplied, it defaults to the namespace in which the Mapping resource is defined. The default behavior can be configured using the [Module resource](../../topics/running/ambassador). When using a Consul resolver, `namespace` is not allowed. -- `port` is the port to which a request should be sent. If not specified, it defaults to `80` when the scheme is `http` or `443` when the scheme is `https`. Note that the [resolver](../../topics/running/resolvers) may return a port in which case the `port` setting is ignored. - -While using service.namespace.svc.cluster.local may work for Kubernetes resolvers, the preferred syntax is service.namespace. - - -## Extending Mappings - -Mapping resources support a rich set of annotations to customize the specific routing behavior. Here's an example service for implementing the [CQRS pattern](https://docs.microsoft.com/en-us/azure/architecture/patterns/cqrs) (using HTTP): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-get -spec: - prefix: /cqrs/ - method: GET - service: getcqrs - hostname: '*' ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-put -spec: - prefix: /cqrs/ - method: PUT - service: putcqrs - hostname: '*' -``` - -## Best Practices - -$productName$'s configuration is assembled from multiple YAML blocks which are managed by independent application teams. This implies that certain best practices should be followed. - -#### $productName$'s configuration should be under version control. - -While you can always read back the $productName$'s configuration from Kubernetes or its diagnostic service, the $productName$ will not do versioning for you. - -#### $productName$ tries to not start with a broken configuration, but it's not perfect. - -Gross errors will result in the $productName$ refusing to start, in which case `kubectl logs` will be helpful. However, it's always possible to map a resource to the wrong service, or use the wrong `rewrite` rules. $productName$ can't detect that on its own, although its [diagnostic service](../../topics/running/diagnostics/) can help you figure it out. - -#### Be careful of mapping collisions. - -If two different developers try to map `/myservice/` to something, this can lead to unexpected behavior. $productName$'s [canary deployment](../../topics/using/canary/) logic means that it's more likely that traffic will be split between them than that it will throw an error -- again, the diagnostic service can help you here. - -#### Unless specified, mapping attributes cannot be applied to any other resource type. - -## 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/content/en/docs/3.3/howtos/tls-termination.md b/content/en/docs/3.3/howtos/tls-termination.md deleted file mode 100644 index b8af151b..00000000 --- a/content/en/docs/3.3/howtos/tls-termination.md +++ /dev/null @@ -1,181 +0,0 @@ -# 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 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 - selector: - matchLabels: - hostname: wildcard-host -``` - -**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. - -With $productName$, this can be simply done by requesting a -certificate using the built in [ACME support -](../../topics/running/host-crd#acme-support) - -For the Open-Source API Gateway, 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/content/en/docs/3.3/howtos/tracing-datadog.md b/content/en/docs/3.3/howtos/tracing-datadog.md deleted file mode 100644 index d627e29f..00000000 --- a/content/en/docs/3.3/howtos/tracing-datadog.md +++ /dev/null @@ -1,63 +0,0 @@ -# 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/content/en/docs/3.3/howtos/tracing-zipkin.md b/content/en/docs/3.3/howtos/tracing-zipkin.md deleted file mode 100644 index 37ddc902..00000000 --- a/content/en/docs/3.3/howtos/tracing-zipkin.md +++ /dev/null @@ -1,129 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Distributed tracing with Zipkin - -In this tutorial, we'll configure $productName$ to initiate a trace on some sample requests, and use Zipkin 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. Deploy Zipkin - -In this tutorial, you will use a simple deployment of the open-source [Zipkin](https://github.com/openzipkin/zipkin/wiki) distributed tracing system to store and visualize $productName$-generated traces. The trace data will be stored in memory within the Zipkin container, and you will be able to explore the traces via the Zipkin web UI. - -First, add the following YAML to a file named `zipkin.yaml`. This configuration will create a Zipkin Deployment that uses the [openzipkin/zipkin](https://hub.docker.com/r/openzipkin/zipkin/) container image and also an associated Service. We will also include a `TracingService` that configures $productName$ to use the Zipkin service (running on the default port of 9411) to provide tracing support. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TracingService -metadata: - name: tracing -spec: - service: "zipkin:9411" - driver: zipkin - config: {} ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: zipkin -spec: - replicas: 1 - selector: - matchLabels: - app: zipkin - template: - metadata: - labels: - app: zipkin - spec: - containers: - - name: zipkin - image: openzipkin/zipkin - env: - # note: in-memory storage holds all data in memory, purging older data upon a span limit. - # you should use a proper storage in production environments - - name: STORAGE_TYPE - value: mem ---- -apiVersion: v1 -kind: Service -metadata: - labels: - name: zipkin - name: zipkin -spec: - ports: - - port: 9411 - targetPort: 9411 - selector: - app: zipkin -``` - -Next, deploy this configuration into your cluster: - -``` -$ kubectl apply -f zipkin.yaml -``` - -As a final step we want to restart $productName$ as this is necessary to add the tracing header. This command will restart all the Pods (assuming $productName$ is installed in the ambassador namespace): - -``` -$ kubectl -n ambassador rollout restart deploy -``` - - Restarting $productName$ is required after deploying a Tracing Service for changes to take effect. - - -## 2. 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/backend/ -``` - -## 3. Test traces - -To test things out, we'll need to access the Zipkin UI. If you're on Kubernetes, get the name of the Zipkin pod: - -``` -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -ambassador-5ffcfc798-c25dc 2/2 Running 0 1d -prometheus-prometheus-0 2/2 Running 0 113d -zipkin-868b97667c-58v4r 1/1 Running 0 2h -``` - -And then use `kubectl port-forward` to access the pod: - -``` -$ kubectl port-forward zipkin-868b97667c-58v4r 9411 -``` - -Open your web browser to `http://localhost:9411` for the Zipkin UI. - -If you're on `minikube` you can access the `NodePort` directly, and this ports number can be obtained via the `minikube services list` command. If you are using `Docker for Mac/Windows`, you can use the `kubectl get svc` command to get the same information. - -``` -$ minikube service list -|-------------|----------------------|-----------------------------| -| NAMESPACE | NAME | URL | -|-------------|----------------------|-----------------------------| -| default | ambassador-admin | http://192.168.99.107:30319 | -| default | ambassador | http://192.168.99.107:31893 | -| default | zipkin | http://192.168.99.107:31043 | -|-------------|----------------------|-----------------------------| -``` - -Open your web browser to the Zipkin dashboard `http://192.168.99.107:31043/zipkin/`. - -In the Zipkin UI, click on the "Find Traces" button to get a listing instrumented traces. Each of the traces that are displayed can be clicked on, which provides further information about each span and associated metadata. - -## Learn more - -For more details about configuring the external tracing service, read the documentation on [external tracing](../../topics/running/services/tracing-service). diff --git a/content/en/docs/3.3/howtos/websockets.md b/content/en/docs/3.3/howtos/websockets.md deleted file mode 100644 index 25cac7da..00000000 --- a/content/en/docs/3.3/howtos/websockets.md +++ /dev/null @@ -1,43 +0,0 @@ -# WebSocket connections - -$productName$ makes it easy to access your services from outside your -application, and this includes services that use WebSockets. Only a -small amount of additional configuration is required, which is as -simple as telling the Mapping to allow "upgrading" from the HTTP protocol to -the "websocket" protocol: - -```yaml -allow_upgrade: -- websocket -``` - -## Example WebSocket service - -The example configuration below demonstrates the addition of the `allow_upgrade:` attribute to support websockets. The use of `use_websocket` is now deprecated. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: my-service-mapping -spec: - hostname: "*" - prefix: /my-service/ - service: my-service - allow_upgrade: - - websocket - ---- -kind: Service -apiVersion: v1 -metadata: - name: my-service -spec: - selector: - app: MyApp - ports: - - protocol: TCP - port: 80 - targetPort: 9376 -``` diff --git a/content/en/docs/3.3/images/Auth0_JWT.png b/content/en/docs/3.3/images/Auth0_JWT.png deleted file mode 100644 index e18155f5..00000000 Binary files a/content/en/docs/3.3/images/Auth0_JWT.png and /dev/null differ diff --git a/content/en/docs/3.3/images/Auth0_domain_clientID.png b/content/en/docs/3.3/images/Auth0_domain_clientID.png deleted file mode 100644 index a7f8edf6..00000000 Binary files a/content/en/docs/3.3/images/Auth0_domain_clientID.png and /dev/null differ diff --git a/content/en/docs/3.3/images/Auth0_method_callback_origins.png b/content/en/docs/3.3/images/Auth0_method_callback_origins.png deleted file mode 100644 index 8d31138e..00000000 Binary files a/content/en/docs/3.3/images/Auth0_method_callback_origins.png and /dev/null differ diff --git a/content/en/docs/3.3/images/aes-success.png b/content/en/docs/3.3/images/aes-success.png deleted file mode 100644 index 66f28d3f..00000000 Binary files a/content/en/docs/3.3/images/aes-success.png and /dev/null differ diff --git a/content/en/docs/3.3/images/ambassador-arch.png b/content/en/docs/3.3/images/ambassador-arch.png deleted file mode 100644 index 5a5cb652..00000000 Binary files a/content/en/docs/3.3/images/ambassador-arch.png and /dev/null differ diff --git a/content/en/docs/3.3/images/ambassador-logo.svg b/content/en/docs/3.3/images/ambassador-logo.svg deleted file mode 100644 index 1f0e06a8..00000000 --- a/content/en/docs/3.3/images/ambassador-logo.svg +++ /dev/null @@ -1,49 +0,0 @@ - - - - ambassador logo@1x - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.3/images/ambassador_oidc_flow.jpg b/content/en/docs/3.3/images/ambassador_oidc_flow.jpg deleted file mode 100644 index 4f1c0c7e..00000000 Binary files a/content/en/docs/3.3/images/ambassador_oidc_flow.jpg and /dev/null differ diff --git a/content/en/docs/3.3/images/apple.png b/content/en/docs/3.3/images/apple.png deleted file mode 100644 index 8b8277f1..00000000 Binary files a/content/en/docs/3.3/images/apple.png and /dev/null differ diff --git a/content/en/docs/3.3/images/auth-flow.png b/content/en/docs/3.3/images/auth-flow.png deleted file mode 100644 index e1ba4387..00000000 Binary files a/content/en/docs/3.3/images/auth-flow.png and /dev/null differ diff --git a/content/en/docs/3.3/images/authentication-icon.svg b/content/en/docs/3.3/images/authentication-icon.svg deleted file mode 100644 index 342e8a3d..00000000 --- a/content/en/docs/3.3/images/authentication-icon.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_897228_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.3/images/blackbird.png b/content/en/docs/3.3/images/blackbird.png deleted file mode 100644 index 1f10e5cc..00000000 Binary files a/content/en/docs/3.3/images/blackbird.png and /dev/null differ diff --git a/content/en/docs/3.3/images/canary-release-overview.png b/content/en/docs/3.3/images/canary-release-overview.png deleted file mode 100644 index c683a23d..00000000 Binary files a/content/en/docs/3.3/images/canary-release-overview.png and /dev/null differ diff --git a/content/en/docs/3.3/images/configure-icon.svg b/content/en/docs/3.3/images/configure-icon.svg deleted file mode 100644 index 0f556840..00000000 --- a/content/en/docs/3.3/images/configure-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_858572_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.3/images/consul-ambassador.png b/content/en/docs/3.3/images/consul-ambassador.png deleted file mode 100644 index c4911624..00000000 Binary files a/content/en/docs/3.3/images/consul-ambassador.png and /dev/null differ diff --git a/content/en/docs/3.3/images/container-inner-dev-loop.png b/content/en/docs/3.3/images/container-inner-dev-loop.png deleted file mode 100644 index 06586cd6..00000000 Binary files a/content/en/docs/3.3/images/container-inner-dev-loop.png and /dev/null differ diff --git a/content/en/docs/3.3/images/datawire-logo.svg b/content/en/docs/3.3/images/datawire-logo.svg deleted file mode 100644 index fb45872c..00000000 --- a/content/en/docs/3.3/images/datawire-logo.svg +++ /dev/null @@ -1,27 +0,0 @@ - - - - Group 3 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.3/images/diagnostics-example.png b/content/en/docs/3.3/images/diagnostics-example.png deleted file mode 100644 index 6c825b0c..00000000 Binary files a/content/en/docs/3.3/images/diagnostics-example.png and /dev/null differ diff --git a/content/en/docs/3.3/images/diagnostics.png b/content/en/docs/3.3/images/diagnostics.png deleted file mode 100644 index 29248703..00000000 Binary files a/content/en/docs/3.3/images/diagnostics.png and /dev/null differ diff --git a/content/en/docs/3.3/images/docker-compose.png b/content/en/docs/3.3/images/docker-compose.png deleted file mode 100644 index b8829521..00000000 Binary files a/content/en/docs/3.3/images/docker-compose.png and /dev/null differ diff --git a/content/en/docs/3.3/images/docker.png b/content/en/docs/3.3/images/docker.png deleted file mode 100644 index 1f35e5ea..00000000 Binary files a/content/en/docs/3.3/images/docker.png and /dev/null differ diff --git a/content/en/docs/3.3/images/edge-stack-1.13.4.png b/content/en/docs/3.3/images/edge-stack-1.13.4.png deleted file mode 100644 index 954ac1a9..00000000 Binary files a/content/en/docs/3.3/images/edge-stack-1.13.4.png and /dev/null differ diff --git a/content/en/docs/3.3/images/edge-stack-1.13.7-json-logging.png b/content/en/docs/3.3/images/edge-stack-1.13.7-json-logging.png deleted file mode 100644 index 4a47cbdf..00000000 Binary files a/content/en/docs/3.3/images/edge-stack-1.13.7-json-logging.png and /dev/null differ diff --git a/content/en/docs/3.3/images/edge-stack-1.13.7-memory.png b/content/en/docs/3.3/images/edge-stack-1.13.7-memory.png deleted file mode 100644 index 9c415ba3..00000000 Binary files a/content/en/docs/3.3/images/edge-stack-1.13.7-memory.png and /dev/null differ diff --git a/content/en/docs/3.3/images/edge-stack-1.13.7-tcpmapping-consul.png b/content/en/docs/3.3/images/edge-stack-1.13.7-tcpmapping-consul.png deleted file mode 100644 index c455a47f..00000000 Binary files a/content/en/docs/3.3/images/edge-stack-1.13.7-tcpmapping-consul.png and /dev/null differ diff --git a/content/en/docs/3.3/images/edge-stack-1.13.8-cloud-bugfix.png b/content/en/docs/3.3/images/edge-stack-1.13.8-cloud-bugfix.png deleted file mode 100644 index 6beaf653..00000000 Binary files a/content/en/docs/3.3/images/edge-stack-1.13.8-cloud-bugfix.png and /dev/null differ diff --git a/content/en/docs/3.3/images/emissary-1.13.10-cors-origin.png b/content/en/docs/3.3/images/emissary-1.13.10-cors-origin.png deleted file mode 100644 index b7538e5f..00000000 Binary files a/content/en/docs/3.3/images/emissary-1.13.10-cors-origin.png and /dev/null differ diff --git a/content/en/docs/3.3/images/fast-icon.svg b/content/en/docs/3.3/images/fast-icon.svg deleted file mode 100644 index 354542ee..00000000 --- a/content/en/docs/3.3/images/fast-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1187990_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.3/images/features-icons/basic-authentication.svg b/content/en/docs/3.3/images/features-icons/basic-authentication.svg deleted file mode 100644 index 2bd19edf..00000000 --- a/content/en/docs/3.3/images/features-icons/basic-authentication.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_897228_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.3/images/features-icons/canary-release.svg b/content/en/docs/3.3/images/features-icons/canary-release.svg deleted file mode 100644 index f8de57d9..00000000 --- a/content/en/docs/3.3/images/features-icons/canary-release.svg +++ /dev/null @@ -1,27 +0,0 @@ - - - - Group 25 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.3/images/features-icons/cors.svg b/content/en/docs/3.3/images/features-icons/cors.svg deleted file mode 100644 index e559d924..00000000 --- a/content/en/docs/3.3/images/features-icons/cors.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_111967_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.3/images/features-icons/datadog.png b/content/en/docs/3.3/images/features-icons/datadog.png deleted file mode 100644 index eea05f8c..00000000 Binary files a/content/en/docs/3.3/images/features-icons/datadog.png and /dev/null differ diff --git a/content/en/docs/3.3/images/features-icons/datadog.svg b/content/en/docs/3.3/images/features-icons/datadog.svg deleted file mode 100644 index e46e8118..00000000 --- a/content/en/docs/3.3/images/features-icons/datadog.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Screen Shot 2018-04-05 at 8.22.25 AM - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.3/images/features-icons/diagnostics.svg b/content/en/docs/3.3/images/features-icons/diagnostics.svg deleted file mode 100644 index 940e1bc2..00000000 --- a/content/en/docs/3.3/images/features-icons/diagnostics.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_196445_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.3/images/features-icons/distributed-tracing.png b/content/en/docs/3.3/images/features-icons/distributed-tracing.png deleted file mode 100644 index 6b69e28c..00000000 Binary files a/content/en/docs/3.3/images/features-icons/distributed-tracing.png and /dev/null differ diff --git a/content/en/docs/3.3/images/features-icons/grpc.png b/content/en/docs/3.3/images/features-icons/grpc.png deleted file mode 100644 index b2f5a0d9..00000000 Binary files a/content/en/docs/3.3/images/features-icons/grpc.png and /dev/null differ diff --git a/content/en/docs/3.3/images/features-icons/prometheus.svg b/content/en/docs/3.3/images/features-icons/prometheus.svg deleted file mode 100644 index d5252a66..00000000 --- a/content/en/docs/3.3/images/features-icons/prometheus.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - prometheus_logo_grey - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.3/images/features-icons/rate-limiting.svg b/content/en/docs/3.3/images/features-icons/rate-limiting.svg deleted file mode 100644 index f1b6eacb..00000000 --- a/content/en/docs/3.3/images/features-icons/rate-limiting.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - Group 10 - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.3/images/features-icons/regex-routing.svg b/content/en/docs/3.3/images/features-icons/regex-routing.svg deleted file mode 100644 index 113b53b5..00000000 --- a/content/en/docs/3.3/images/features-icons/regex-routing.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_699774_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.3/images/features-icons/request-transformers.svg b/content/en/docs/3.3/images/features-icons/request-transformers.svg deleted file mode 100644 index 0b13e2dc..00000000 --- a/content/en/docs/3.3/images/features-icons/request-transformers.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_96239_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.3/images/features-icons/shadowing.svg b/content/en/docs/3.3/images/features-icons/shadowing.svg deleted file mode 100644 index 9e85eee1..00000000 --- a/content/en/docs/3.3/images/features-icons/shadowing.svg +++ /dev/null @@ -1,15 +0,0 @@ - - - - shadow - Created with Sketch. - - - - - - - - - - diff --git a/content/en/docs/3.3/images/features-icons/statsd.png b/content/en/docs/3.3/images/features-icons/statsd.png deleted file mode 100644 index 28374438..00000000 Binary files a/content/en/docs/3.3/images/features-icons/statsd.png and /dev/null differ diff --git a/content/en/docs/3.3/images/features-icons/statsd.svg b/content/en/docs/3.3/images/features-icons/statsd.svg deleted file mode 100644 index cabc90db..00000000 --- a/content/en/docs/3.3/images/features-icons/statsd.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - 88eb31f74479e422e4e9abfc6c2b00ee - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.3/images/features-icons/third-party-auth.svg b/content/en/docs/3.3/images/features-icons/third-party-auth.svg deleted file mode 100644 index 5359a24a..00000000 --- a/content/en/docs/3.3/images/features-icons/third-party-auth.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_511233_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.3/images/features-icons/timeouts.svg b/content/en/docs/3.3/images/features-icons/timeouts.svg deleted file mode 100644 index 47f63056..00000000 --- a/content/en/docs/3.3/images/features-icons/timeouts.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_587034_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.3/images/features-icons/tls-termination.svg b/content/en/docs/3.3/images/features-icons/tls-termination.svg deleted file mode 100644 index 6a631a96..00000000 --- a/content/en/docs/3.3/images/features-icons/tls-termination.svg +++ /dev/null @@ -1,17 +0,0 @@ - - - - noun_63544_cc - Created with Sketch. - - - - - - - - - - - - diff --git a/content/en/docs/3.3/images/features-icons/url-rewrite.svg b/content/en/docs/3.3/images/features-icons/url-rewrite.svg deleted file mode 100644 index 023e2e05..00000000 --- a/content/en/docs/3.3/images/features-icons/url-rewrite.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1295942_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.3/images/features-icons/websockets.svg b/content/en/docs/3.3/images/features-icons/websockets.svg deleted file mode 100644 index af17b9c0..00000000 --- a/content/en/docs/3.3/images/features-icons/websockets.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - noun_50814_cc - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.3/images/features-table.jpg b/content/en/docs/3.3/images/features-table.jpg deleted file mode 100644 index 3de2eb4f..00000000 Binary files a/content/en/docs/3.3/images/features-table.jpg and /dev/null differ diff --git a/content/en/docs/3.3/images/gRPC-TLS-Ambassador.png b/content/en/docs/3.3/images/gRPC-TLS-Ambassador.png deleted file mode 100644 index 0189253e..00000000 Binary files a/content/en/docs/3.3/images/gRPC-TLS-Ambassador.png and /dev/null differ diff --git a/content/en/docs/3.3/images/gRPC-TLS-Originate.png b/content/en/docs/3.3/images/gRPC-TLS-Originate.png deleted file mode 100644 index 1b62010d..00000000 Binary files a/content/en/docs/3.3/images/gRPC-TLS-Originate.png and /dev/null differ diff --git a/content/en/docs/3.3/images/github-login.png b/content/en/docs/3.3/images/github-login.png deleted file mode 100644 index cfd4d4bf..00000000 Binary files a/content/en/docs/3.3/images/github-login.png and /dev/null differ diff --git a/content/en/docs/3.3/images/global-features-bg.svg b/content/en/docs/3.3/images/global-features-bg.svg deleted file mode 100644 index a39c5232..00000000 --- a/content/en/docs/3.3/images/global-features-bg.svg +++ /dev/null @@ -1,34 +0,0 @@ - - - - ambassador_logo@2x - Created with Sketch. - - - - - - - - diff --git a/content/en/docs/3.3/images/grafana.png b/content/en/docs/3.3/images/grafana.png deleted file mode 100644 index befe3377..00000000 Binary files a/content/en/docs/3.3/images/grafana.png and /dev/null differ diff --git a/content/en/docs/3.3/images/grpc-tls.png b/content/en/docs/3.3/images/grpc-tls.png deleted file mode 100644 index 4d705ff0..00000000 Binary files a/content/en/docs/3.3/images/grpc-tls.png and /dev/null differ diff --git a/content/en/docs/3.3/images/helm-navy.png b/content/en/docs/3.3/images/helm-navy.png deleted file mode 100644 index a9710143..00000000 Binary files a/content/en/docs/3.3/images/helm-navy.png and /dev/null differ diff --git a/content/en/docs/3.3/images/helm.png b/content/en/docs/3.3/images/helm.png deleted file mode 100644 index 1c5af71b..00000000 Binary files a/content/en/docs/3.3/images/helm.png and /dev/null differ diff --git a/content/en/docs/3.3/images/highly-available-icon.svg b/content/en/docs/3.3/images/highly-available-icon.svg deleted file mode 100644 index 9cb3eff9..00000000 --- a/content/en/docs/3.3/images/highly-available-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1205522_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.3/images/jaeger.png b/content/en/docs/3.3/images/jaeger.png deleted file mode 100644 index 3b821c09..00000000 Binary files a/content/en/docs/3.3/images/jaeger.png and /dev/null differ diff --git a/content/en/docs/3.3/images/kubernetes.png b/content/en/docs/3.3/images/kubernetes.png deleted file mode 100644 index a392a886..00000000 Binary files a/content/en/docs/3.3/images/kubernetes.png and /dev/null differ diff --git a/content/en/docs/3.3/images/left-arrow.svg b/content/en/docs/3.3/images/left-arrow.svg deleted file mode 100644 index 75cdc7f1..00000000 --- a/content/en/docs/3.3/images/left-arrow.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Path 2 - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.3/images/linux.png b/content/en/docs/3.3/images/linux.png deleted file mode 100644 index 1832c594..00000000 Binary files a/content/en/docs/3.3/images/linux.png and /dev/null differ diff --git a/content/en/docs/3.3/images/logo.png b/content/en/docs/3.3/images/logo.png deleted file mode 100644 index 701f63ba..00000000 Binary files a/content/en/docs/3.3/images/logo.png and /dev/null differ diff --git a/content/en/docs/3.3/images/mapping-editor.png b/content/en/docs/3.3/images/mapping-editor.png deleted file mode 100644 index f8b751a1..00000000 Binary files a/content/en/docs/3.3/images/mapping-editor.png and /dev/null differ diff --git a/content/en/docs/3.3/images/network-architecture.png b/content/en/docs/3.3/images/network-architecture.png deleted file mode 100644 index 3217b3e1..00000000 Binary files a/content/en/docs/3.3/images/network-architecture.png and /dev/null differ diff --git a/content/en/docs/3.3/images/penguin-background.svg b/content/en/docs/3.3/images/penguin-background.svg deleted file mode 100644 index 7affc0d5..00000000 --- a/content/en/docs/3.3/images/penguin-background.svg +++ /dev/null @@ -1,102 +0,0 @@ - - - - @2xambassador_logo - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.3/images/pro-iap.png b/content/en/docs/3.3/images/pro-iap.png deleted file mode 100644 index 787265d8..00000000 Binary files a/content/en/docs/3.3/images/pro-iap.png and /dev/null differ diff --git a/content/en/docs/3.3/images/quote.svg b/content/en/docs/3.3/images/quote.svg deleted file mode 100644 index bab6e871..00000000 --- a/content/en/docs/3.3/images/quote.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - “ - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.3/images/right-arrow.svg b/content/en/docs/3.3/images/right-arrow.svg deleted file mode 100644 index 627144c6..00000000 --- a/content/en/docs/3.3/images/right-arrow.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Path 2 Copy - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.3/images/routing-icon.svg b/content/en/docs/3.3/images/routing-icon.svg deleted file mode 100644 index bd860b13..00000000 --- a/content/en/docs/3.3/images/routing-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1062254_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.3/images/self-service-features-bg.svg b/content/en/docs/3.3/images/self-service-features-bg.svg deleted file mode 100644 index 40bc400a..00000000 --- a/content/en/docs/3.3/images/self-service-features-bg.svg +++ /dev/null @@ -1,93 +0,0 @@ - - - - Group 8 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - SELF-SERVICE FEATURES - - - - diff --git a/content/en/docs/3.3/images/shadowing.png b/content/en/docs/3.3/images/shadowing.png deleted file mode 100644 index 097ecbd5..00000000 Binary files a/content/en/docs/3.3/images/shadowing.png and /dev/null differ diff --git a/content/en/docs/3.3/images/speedometers.png b/content/en/docs/3.3/images/speedometers.png deleted file mode 100644 index 7ce2c2a2..00000000 Binary files a/content/en/docs/3.3/images/speedometers.png and /dev/null differ diff --git a/content/en/docs/3.3/images/tp-architecture.png b/content/en/docs/3.3/images/tp-architecture.png deleted file mode 100644 index 20ae3589..00000000 Binary files a/content/en/docs/3.3/images/tp-architecture.png and /dev/null differ diff --git a/content/en/docs/3.3/images/tp-tutorial-1.png b/content/en/docs/3.3/images/tp-tutorial-1.png deleted file mode 100644 index ee68dc7d..00000000 Binary files a/content/en/docs/3.3/images/tp-tutorial-1.png and /dev/null differ diff --git a/content/en/docs/3.3/images/tp-tutorial-2.png b/content/en/docs/3.3/images/tp-tutorial-2.png deleted file mode 100644 index 129dc6ee..00000000 Binary files a/content/en/docs/3.3/images/tp-tutorial-2.png and /dev/null differ diff --git a/content/en/docs/3.3/images/tp-tutorial-3.png b/content/en/docs/3.3/images/tp-tutorial-3.png deleted file mode 100644 index 946629fc..00000000 Binary files a/content/en/docs/3.3/images/tp-tutorial-3.png and /dev/null differ diff --git a/content/en/docs/3.3/images/tp-tutorial-4.png b/content/en/docs/3.3/images/tp-tutorial-4.png deleted file mode 100644 index cb6e7a9d..00000000 Binary files a/content/en/docs/3.3/images/tp-tutorial-4.png and /dev/null differ diff --git a/content/en/docs/3.3/images/trad-inner-dev-loop.png b/content/en/docs/3.3/images/trad-inner-dev-loop.png deleted file mode 100644 index 618b674f..00000000 Binary files a/content/en/docs/3.3/images/trad-inner-dev-loop.png and /dev/null differ diff --git a/content/en/docs/3.3/images/windows.png b/content/en/docs/3.3/images/windows.png deleted file mode 100644 index a065dc17..00000000 Binary files a/content/en/docs/3.3/images/windows.png and /dev/null differ diff --git a/content/en/docs/3.3/images/xkcd.png b/content/en/docs/3.3/images/xkcd.png deleted file mode 100644 index ed0d5c33..00000000 Binary files a/content/en/docs/3.3/images/xkcd.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/edge-stack-1.13.4.png b/content/en/docs/3.3/release-notes/edge-stack-1.13.4.png deleted file mode 100644 index 954ac1a9..00000000 Binary files a/content/en/docs/3.3/release-notes/edge-stack-1.13.4.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/edge-stack-1.13.7-json-logging.png b/content/en/docs/3.3/release-notes/edge-stack-1.13.7-json-logging.png deleted file mode 100644 index 4a47cbdf..00000000 Binary files a/content/en/docs/3.3/release-notes/edge-stack-1.13.7-json-logging.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/edge-stack-1.13.7-memory.png b/content/en/docs/3.3/release-notes/edge-stack-1.13.7-memory.png deleted file mode 100644 index 9c415ba3..00000000 Binary files a/content/en/docs/3.3/release-notes/edge-stack-1.13.7-memory.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/edge-stack-1.13.7-tcpmapping-consul.png b/content/en/docs/3.3/release-notes/edge-stack-1.13.7-tcpmapping-consul.png deleted file mode 100644 index c455a47f..00000000 Binary files a/content/en/docs/3.3/release-notes/edge-stack-1.13.7-tcpmapping-consul.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/edge-stack-1.13.8-cloud-bugfix.png b/content/en/docs/3.3/release-notes/edge-stack-1.13.8-cloud-bugfix.png deleted file mode 100644 index 6beaf653..00000000 Binary files a/content/en/docs/3.3/release-notes/edge-stack-1.13.8-cloud-bugfix.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/edge-stack-2.0.0-host_crd.png b/content/en/docs/3.3/release-notes/edge-stack-2.0.0-host_crd.png deleted file mode 100644 index c77ef528..00000000 Binary files a/content/en/docs/3.3/release-notes/edge-stack-2.0.0-host_crd.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/edge-stack-2.0.0-ingressstatus.png b/content/en/docs/3.3/release-notes/edge-stack-2.0.0-ingressstatus.png deleted file mode 100644 index 6856d308..00000000 Binary files a/content/en/docs/3.3/release-notes/edge-stack-2.0.0-ingressstatus.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/edge-stack-2.0.0-insecure_action_hosts.png b/content/en/docs/3.3/release-notes/edge-stack-2.0.0-insecure_action_hosts.png deleted file mode 100644 index 79c20bad..00000000 Binary files a/content/en/docs/3.3/release-notes/edge-stack-2.0.0-insecure_action_hosts.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/edge-stack-2.0.0-listener.png b/content/en/docs/3.3/release-notes/edge-stack-2.0.0-listener.png deleted file mode 100644 index ea45a02b..00000000 Binary files a/content/en/docs/3.3/release-notes/edge-stack-2.0.0-listener.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/edge-stack-2.0.0-prune_routes.png b/content/en/docs/3.3/release-notes/edge-stack-2.0.0-prune_routes.png deleted file mode 100644 index bc43229f..00000000 Binary files a/content/en/docs/3.3/release-notes/edge-stack-2.0.0-prune_routes.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/edge-stack-2.0.0-tlscontext.png b/content/en/docs/3.3/release-notes/edge-stack-2.0.0-tlscontext.png deleted file mode 100644 index 68dbad80..00000000 Binary files a/content/en/docs/3.3/release-notes/edge-stack-2.0.0-tlscontext.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/edge-stack-2.0.0-v3alpha1.png b/content/en/docs/3.3/release-notes/edge-stack-2.0.0-v3alpha1.png deleted file mode 100644 index c0ac3596..00000000 Binary files a/content/en/docs/3.3/release-notes/edge-stack-2.0.0-v3alpha1.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/emissary-1.13.10-cors-origin.png b/content/en/docs/3.3/release-notes/emissary-1.13.10-cors-origin.png deleted file mode 100644 index b7538e5f..00000000 Binary files a/content/en/docs/3.3/release-notes/emissary-1.13.10-cors-origin.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/emissary-ga.png b/content/en/docs/3.3/release-notes/emissary-ga.png deleted file mode 100644 index 062f043a..00000000 Binary files a/content/en/docs/3.3/release-notes/emissary-ga.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/tada.png b/content/en/docs/3.3/release-notes/tada.png deleted file mode 100644 index c8832e8e..00000000 Binary files a/content/en/docs/3.3/release-notes/tada.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/v2.0.4-k8s-1.22.png b/content/en/docs/3.3/release-notes/v2.0.4-k8s-1.22.png deleted file mode 100644 index ed9b0415..00000000 Binary files a/content/en/docs/3.3/release-notes/v2.0.4-k8s-1.22.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/v2.0.4-l7depth.png b/content/en/docs/3.3/release-notes/v2.0.4-l7depth.png deleted file mode 100644 index 9314324c..00000000 Binary files a/content/en/docs/3.3/release-notes/v2.0.4-l7depth.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/v2.0.4-mapping-dns-type.png b/content/en/docs/3.3/release-notes/v2.0.4-mapping-dns-type.png deleted file mode 100644 index 7770c77d..00000000 Binary files a/content/en/docs/3.3/release-notes/v2.0.4-mapping-dns-type.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/v2.0.4-v3alpha1.png b/content/en/docs/3.3/release-notes/v2.0.4-v3alpha1.png deleted file mode 100644 index 9c50b8fb..00000000 Binary files a/content/en/docs/3.3/release-notes/v2.0.4-v3alpha1.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/v2.0.4-version.png b/content/en/docs/3.3/release-notes/v2.0.4-version.png deleted file mode 100644 index 9481b7db..00000000 Binary files a/content/en/docs/3.3/release-notes/v2.0.4-version.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/v2.0.5-auth-circuit-breaker.png b/content/en/docs/3.3/release-notes/v2.0.5-auth-circuit-breaker.png deleted file mode 100644 index cac8cf7b..00000000 Binary files a/content/en/docs/3.3/release-notes/v2.0.5-auth-circuit-breaker.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/v2.0.5-mappingselector.png b/content/en/docs/3.3/release-notes/v2.0.5-mappingselector.png deleted file mode 100644 index 31942ede..00000000 Binary files a/content/en/docs/3.3/release-notes/v2.0.5-mappingselector.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/v2.1.0-canary.png b/content/en/docs/3.3/release-notes/v2.1.0-canary.png deleted file mode 100644 index 39d3bbbf..00000000 Binary files a/content/en/docs/3.3/release-notes/v2.1.0-canary.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/v2.1.0-gzip-enabled.png b/content/en/docs/3.3/release-notes/v2.1.0-gzip-enabled.png deleted file mode 100644 index 061fcbc9..00000000 Binary files a/content/en/docs/3.3/release-notes/v2.1.0-gzip-enabled.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/v2.1.0-smoother-migration.png b/content/en/docs/3.3/release-notes/v2.1.0-smoother-migration.png deleted file mode 100644 index ebd77497..00000000 Binary files a/content/en/docs/3.3/release-notes/v2.1.0-smoother-migration.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/v2.1.2-annotations.png b/content/en/docs/3.3/release-notes/v2.1.2-annotations.png deleted file mode 100644 index b5498c3c..00000000 Binary files a/content/en/docs/3.3/release-notes/v2.1.2-annotations.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/v2.1.2-host-mapping-matching.png b/content/en/docs/3.3/release-notes/v2.1.2-host-mapping-matching.png deleted file mode 100644 index 1cfba5ed..00000000 Binary files a/content/en/docs/3.3/release-notes/v2.1.2-host-mapping-matching.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/v2.1.2-mapping-cors.png b/content/en/docs/3.3/release-notes/v2.1.2-mapping-cors.png deleted file mode 100644 index f76ea01c..00000000 Binary files a/content/en/docs/3.3/release-notes/v2.1.2-mapping-cors.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/v2.1.2-mapping-less-weighted.png b/content/en/docs/3.3/release-notes/v2.1.2-mapping-less-weighted.png deleted file mode 100644 index 7e299062..00000000 Binary files a/content/en/docs/3.3/release-notes/v2.1.2-mapping-less-weighted.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/v2.1.2-mapping-no-rewrite.png b/content/en/docs/3.3/release-notes/v2.1.2-mapping-no-rewrite.png deleted file mode 100644 index 5d3d5a29..00000000 Binary files a/content/en/docs/3.3/release-notes/v2.1.2-mapping-no-rewrite.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/v2.2.0-cloud.png b/content/en/docs/3.3/release-notes/v2.2.0-cloud.png deleted file mode 100644 index 5923fcb4..00000000 Binary files a/content/en/docs/3.3/release-notes/v2.2.0-cloud.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/v2.2.0-percent-escape.png b/content/en/docs/3.3/release-notes/v2.2.0-percent-escape.png deleted file mode 100644 index df4d81b9..00000000 Binary files a/content/en/docs/3.3/release-notes/v2.2.0-percent-escape.png and /dev/null differ diff --git a/content/en/docs/3.3/release-notes/v2.2.0-tls-cert-validation.png b/content/en/docs/3.3/release-notes/v2.2.0-tls-cert-validation.png deleted file mode 100644 index f8635b5a..00000000 Binary files a/content/en/docs/3.3/release-notes/v2.2.0-tls-cert-validation.png and /dev/null differ diff --git a/content/en/docs/3.3/releaseNotes.yml b/content/en/docs/3.3/releaseNotes.yml deleted file mode 100644 index 8f083994..00000000 --- a/content/en/docs/3.3/releaseNotes.yml +++ /dev/null @@ -1,1389 +0,0 @@ -# -*- fill-column: 100 -*- - -# This file should be placed in the folder for the version of the -# product that's meant to be documented. A `/release-notes` page will -# be automatically generated and populated at build time. -# -# Note that an entry needs to be added to the `doc-links.yml` file in -# order to surface the release notes in the table of contents. -# -# The YAML in this file should contain: -# -# changelog: An (optional) URL to the CHANGELOG for the product. -# items: An array of releases with the following attributes: -# - version: The (optional) version number of the release, if applicable. -# - date: The date of the release in the format YYYY-MM-DD. -# - notes: An array of noteworthy changes included in the release, each having the following attributes: -# - type: The type of change, one of `bugfix`, `feature`, `security` or `change`. -# - title: A short title of the noteworthy change. -# - body: >- -# Two or three sentences describing the change and why it -# is noteworthy. This is HTML, not plain text or -# markdown. It is handy to use YAML's ">-" feature to -# allow line-wrapping. -# - image: >- -# The URL of an image that visually represents the -# noteworthy change. This path is relative to the -# `release-notes` directory; if this file is -# `FOO/releaseNotes.yml`, then the image paths are -# relative to `FOO/release-notes/`. -# - docs: The path to the documentation page where additional information can be found. -# - href: A path from the root to a resource on the getambassador website, takes precedence over a docs link. - -changelog: https://github.com/emissary-ingress/emissary/blob/$branch$/CHANGELOG.md -items: - - 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. $productName$ does not expose any of these golang servers to external clients directly. - - - 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: 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 - - - 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 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: 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/content/en/docs/3.3/topics/concepts/architecture.md b/content/en/docs/3.3/topics/concepts/architecture.md deleted file mode 100644 index fe9e0bd3..00000000 --- a/content/en/docs/3.3/topics/concepts/architecture.md +++ /dev/null @@ -1,27 +0,0 @@ -# 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). - -![Architecture](../../images/ambassador-arch.png) - -## 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/content/en/docs/3.3/topics/concepts/gitops-continuous-delivery.md b/content/en/docs/3.3/topics/concepts/gitops-continuous-delivery.md deleted file mode 100644 index 336a1c66..00000000 --- a/content/en/docs/3.3/topics/concepts/gitops-continuous-delivery.md +++ /dev/null @@ -1,66 +0,0 @@ -# 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/content/en/docs/3.3/topics/concepts/index.md b/content/en/docs/3.3/topics/concepts/index.md deleted file mode 100644 index 2d02a027..00000000 --- a/content/en/docs/3.3/topics/concepts/index.md +++ /dev/null @@ -1,10 +0,0 @@ -# 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/content/en/docs/3.3/topics/concepts/kubernetes-network-architecture.md b/content/en/docs/3.3/topics/concepts/kubernetes-network-architecture.md deleted file mode 100644 index 6650aa60..00000000 --- a/content/en/docs/3.3/topics/concepts/kubernetes-network-architecture.md +++ /dev/null @@ -1,52 +0,0 @@ -# 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: - -
- -![Kubernetes Network Architecture](../../../../../../images/documentation/kubernetes-network.inline.svg) - -
- -Each of the components in this topology is discussed in further detail below. - -### Load balancer - -The load balancer is deployed outside of the Kubernetes cluster. Typically, the load balancer also has one or more static IP addresses assigned to it. A DNS entry is then created to map a domain name (e.g., example.com) to the static IP address. - -Cloud infrastructure providers such as Amazon Web Services, Azure, Digital Ocean, and Google make it easy to create these load balancers directly from Kubernetes. This is done by creating a Kubernetes service of `type: LoadBalancer`. When this service is created, the cloud provider will use the metadata contained in the Kubernetes service definition to provision a load balancer. - -If the Kubernetes cluster is deployed in a private data center, an external load balancer is still generally used. Provisioning of this load balancer usually requires the involvement of the data center operations team. - -In both the private data center and cloud infrastructure case, the external load balancer should be configured to point to the edge proxy. - -### Edge Proxy / ingress controller - -The Edge Proxy is typically a Layer 7 proxy that is deployed directly in the cluster. The core function of the edge proxy is to accept incoming traffic from the external load balancer and route the traffic to Kubernetes services. The edge proxy should be configured using Kubernetes manifests. This enables a common management workflow for both the edge proxy and Kubernetes services. - -The most popular approach to configuring edge proxies is with the Kubernetes ingress resource. When an edge proxy can process ingress resources, it is called an ingress controller. Not all edge proxies are ingress controllers (because they can't process ingress resources), but all ingress controllers are edge proxies. - -The ingress resource is a Kubernetes standard. As such, it is a lowest common denominator resource. In practice, users find that the ingress resource is insufficient in scope to address the requirements for edge routing. Semantics such as TLS termination, redirecting to TLS, timeouts, rate limiting, and authentication are all beyond the scope of the ingress resource. - -$productName$ can function as an ingress controller (i.e., it reads ingress resources), although it also includes many other capabilities that are beyond the scope of the ingress specification. Most $productName$ users find that the various additional capabilities of $productName$ are essential, and end up using $productName$'s extensions to the ingress resource, instead of using ingress resources themselves. - -### Kubernetes services and Pods - -Each instance of your application is deployed in a Kubernetes pod. As the workload on your application increases or decreases, Kubernetes can automatically add or remove pods. A Kubernetes _service_ represents a group of pods that comprise the same version of a given application. Traffic can be routed to the pods via a Kubernetes service, or it can be routed directly to the pods. - -When traffic is routed to the pods via a Kubernetes service, Kubernetes uses a built-in mechanism called `kube-proxy` to load balance traffic between the pods. Due to its implementation, `kube-proxy` is a Layer 4 proxy, i.e., it load balances at a connection level. For particular types of traffic such as HTTP/2 and gRPC, this form of load balancing is particularly problematic as it can easily result in a very uneven load balancing configuration. - -Traffic can also be routed directly to pods, bypassing the Kubernetes service. Since pods are much more ephemeral than Kubernetes services, this approach requires an edge proxy that is optimized for this use case. In particular, the edge proxy needs to support real-time discovery of pods, and be able to dynamically update pod locations without downtime. - -$productName$ supports routing both to Kubernetes services and directly to pods. - -## Further reading - -* [Kubernetes Ingress 101](https://blog.getambassador.io/kubernetes-ingress-nodeport-load-balancers-and-ingress-controllers-6e29f1c44f2d) -* [Envoy Proxy Performance on Kubernetes](/resources/envoyproxy-performance-on-k8s/) diff --git a/content/en/docs/3.3/topics/concepts/microservices-api-gateways.md b/content/en/docs/3.3/topics/concepts/microservices-api-gateways.md deleted file mode 100644 index ba95b8fc..00000000 --- a/content/en/docs/3.3/topics/concepts/microservices-api-gateways.md +++ /dev/null @@ -1,60 +0,0 @@ -# Microservices API gateways - -A microservices API gateway is an API gateway designed to accelerate the development workflow of independent services teams. A microservices API gateway provides all the functionality for a team to independently publish, monitor, and update a microservice. - -This focus on accelerating the development workflow is distinct from the purpose of traditional API gateways, which focus on the challenges of managing APIs. Over the past decade, organizations have worked to expose internal systems through well-defined APIs. The challenge of safely exposing hundreds or thousands of APIs to end-users (both internal and external) led to the emergence of API gateways. Over time, API gateways have become centralized, mission critical pieces of infrastructure that control access to these APIs. - -In this article, we'll discuss how the difference in business objective (productivity vs management) results in a very different API gateway. - -## Microservices organization - -In a microservices organization, small teams of developers work independently from each other to rapidly deliver functionality to the customer. In order for each service team to work independently, with a productive workflow, a services team needs to be able to: - -1. Publish their service, so that others can use the service -2. Monitor their service, to see how well it's working -3. Test and update their service, so they can keep on improving the service - -The team needs to do all of this *without* requiring assistance from another operations or platform team--as soon as a services team requires another team, they're no longer working independently, and this can lead to bottlenecks. - -For service publication, a microservices API gateway provides a static address for consumers, and dynamically route requests to the appropriate service address. In addition, providing authentication and TLS termination for security are typical considerations in exposing a service to other consumers. - -Understanding the end-user experience of a service is crucial to improving the service. For example, a software update could inadvertently impact the latency of certain requests. A microservices API gateway is well situated to collect key observability metrics on end-user traffic as it routes traffic to the end service. - -A microservices API gateway also supports dynamically routing user requests to different service versions for canary testing. By routing a small fraction of end-user requests to a new version of a service, service teams can safely test the impact of new updates to a small subset of users. - -## Microservices API Gateways vs. enterprise API Gateways - -At first glance, the use case described above may be fulfilled with an enterprise-focused API gateway. While this may be true, the actual emphasis of enterprise API gateways and microservices API gateways are somewhat different: - -| Use case | Traditional Enterprise API gateway | Microservices API gateway | -|---------------|-------------------|------------------------------| -| Primary Purpose | Expose, compose, and manage internal business APIs | Expose and observe internal business services | -| Publishing Functionality | API management team or service team registers / updates gateway via admin API | Service team registers / updates gateway via declarative code as part of the deployment process | -| Monitoring | Admin and operations focused e.g. meter API calls per consumer, report errors (e.g. internal 5XX). | Developer focused e.g. latency, traffic, errors, saturation | -| Handling and Debugging Issues | L7 error-handling (e.g. custom error page or payload). Run gateway/API with additional logging. Troubleshoot issue in staging environment | Configure more detailed monitoring. Enable traffic shadowing and / or canarying | -| Testing | Operate multiple environments for QA, Staging, and Production. Automated integration testing, and gated API deployment. Use client-driven API versioning for compatibility and stability (e.g. semver) | Facilitate canary routing for dynamic testing (taking care with data mutation side effects). Use developer-driven service versioning for upgrade management | -| Local Development | Deploy gateway locally (via installation script, Vagrant or Docker), and attempt to mitigate infrastructure differences with production. Use language-specific gateway mocking and stubbing frameworks | Deploy gateway locally via service orchestration platform (e.g. Kubernetes) | - -## Self-service publishing - -A team needs to be able to publish a new service to customers without requiring an operations or API management team. This ability to self-service for deployment and publication enables the team to keep the feature release velocity high. While a traditional enterprise API gateway may provide a simple mechanism (e.g., REST API) for publishing a new service, in practice, the usage is often limited to the use of a dedicated team that is responsible for the gateway. The primary reason for limiting publication to a single team is to provide an additional (human) safety mechanism: an errant API call could have potentially disastrous effects on production. - -Microservices API gateways utilize mechanisms that enable service teams to easily *and* safely publish new services, with the inherent understanding that the producing team are responsible for their service, and will fix an issue if one occurs. A microservices gateway provides configurable monitoring for issue detection, and provides hooks for debugging, such as inspecting traffic or traffic shifting/duplication. - -## Monitoring and rate limiting - -A common business model for APIs is metering, where a consumer is charged different fees depending on API usage. Traditional enterprise API gateways excel in this use case: they provide functionality for monitoring per-client usage of an API, and the ability to limit usage when the client exceeds their quota. - -A microservice gateway also requires monitoring and rate limiting, but for different reasons. Monitoring user-visible metrics such as throughput, latency, and availability, are important to ensure that new updates don't impact the end-user. Robust end-user metrics are critical to allowing rapid, incremental updates. Rate limiting is used to improve the overall resilience of a service. When a service is not responding as expected, an API gateway can throttle incoming requests to allow a service to recover and prevent a cascade failure. - -## Testing and updates - -A microservices application has multiple services, each of which is being independently updated. Automated pre-production testing of a moving target is necessary but not sufficient for microservices. Canary testing, where a small percentage of production traffic is routed to a new service version, is an important tool to help test an update. By limiting a new service version to a small percentage of users, the impact of a service failure is limited. - -In a traditional enterprise API gateway, routing is used to isolate or compose/aggregate changing API versions. Automated pre-production testing and manual post-production verification and exploration are required. - -## Summary - -Traditional enterprise API gateways are designed to solve the challenges of API management. While they may appear to solve some of the challenges of adopting microservices, the reality is that a microservices workflow creates a different set of requirements. Integrating a microservices API gateway into your development workflow empowers service teams to self-publish, monitor, and update their service, quickly and safely. This will enable your organization to ship software more rapidly, and with more reliability than ever before. - -For further reading on how an API Gateway can accelerate continuous delivery, read [this blog post](https://blog.getambassador.io/continuous-delivery-how-can-an-api-gateway-help-or-hinder-1ff15224ec4d). diff --git a/content/en/docs/3.3/topics/concepts/progressive-delivery.md b/content/en/docs/3.3/topics/concepts/progressive-delivery.md deleted file mode 100644 index f2ade27f..00000000 --- a/content/en/docs/3.3/topics/concepts/progressive-delivery.md +++ /dev/null @@ -1,47 +0,0 @@ -# Progressive delivery - -Today's cloud-native applications may consist of hundreds of services, each of which are being updated at any time. Thus, many cloud-native organizations augment regression test strategies with testing in production using progressive delivery techniques. - -Progressive Delivery is an approach for releasing software to production users. In the progressive delivery model, software is released to ever growing subsets of production users. This approach reduces the blast radius in the event of a failure. - -## Why test in production? - -Modern cloud applications are continuously deployed, as different teams rapidly update their respective services. Deploying and testing updates in a pre-production staging environment introduces a bottleneck to the speed of iteration. More importantly, staging environments are not representative of what will be running in production when the deployment actually occurs given the velocity of service updates and changes in production. Testing in production addresses both of these challenges: developers evaluate their changes in the real-world environment, enabling rapid iteration. - -## Progressive delivery strategies - -There are a number of different strategies for progressive delivery. These include: - -* Feature flags, where specific features are made available to specific user groups -* Canary releases, where a (small) percentage of traffic is routed to a new version of a service before the service is full production -* Traffic shadowing, where real user traffic is copied, or shadowed, from production to the service under test - -Observability is a critical requirement for testing in production. Regardless of progressive delivery strategy, collecting key metrics around latency, traffic, errors, and saturation (the [“Four Golden Signals of Monitoring”](https://landing.google.com/sre/sre-book/chapters/monitoring-distributed-systems/#xref_monitoring_golden-signals)) provides valuable insight into the stability and performance of a new version of the service. Moreover, application developers can compare the metrics (e.g., latency) between the production version and an updated version. If the metrics are similar, then updates can proceed with much greater confidence. - -$productName$ supports a variety of strategies for progressive delivery. These strategies are discussed in further detail below. - -### Canary releases - -Canary releases shifts a small amount of real user traffic from production to the service under test. - -The user will see the direct response from the canary version of the service from any traffic that is shifted to the canary release, and they will not trigger or see the response from the current production released version of the service. The canary results can also be verified (both the downstream response and associated upstream side effects), but it is key to understand that any side effects will be persisted. - -In addition to allowing verification that the service is not crashing or otherwise behaving badly from an operational perspective when dealing with real user traffic and behavior, canary releasing allows user validation. For example, if a business KPI performs worse for all canaried requests, then this most likely indicates that the canaried service should not be fully released in its current form. - -Canary tests can be automated, and are typically run after testing in a pre-production environment has been completed. The canary release is only visible to a fraction of actual users, and any bugs or negative changes can be reversed quickly by either routing traffic away from the canary or by rolling-back the canary deployment. - -![Canary release process overview](../../images/canary-release-overview.png) - -Canary releases are not a panacea. In particular, many services may not receive sufficient traffic in order for canary releases to provide useful information in an actionable timeframe. - -### Traffic shadowing - -This approach “shadows” or mirrors a small amount of real user traffic from production to the service under test. - -Although the shadowed results can be verified (both the downstream response and associated upstream side effects) they are not returned to the user -- the user only sees the results from the currently released service. Typically any side effects are not persisted or are executed as a no-op and verified (much like setting up a mock, and verifying that a method/function was called with the correct parameters). - -This allows verification that the service is not crashing or otherwise behaving badly from an operational perspective when dealing with real user traffic and behavior (and the larger the percentage of traffic shadowed, the higher the probability of confidence). - -## Further reading - -* [Canary release pattern](https://blog.getambassador.io/cloud-native-patterns-canary-release-1cb8f82d371a) diff --git a/content/en/docs/3.3/topics/concepts/rate-limiting-at-the-edge.md b/content/en/docs/3.3/topics/concepts/rate-limiting-at-the-edge.md deleted file mode 100644 index c5acc88a..00000000 --- a/content/en/docs/3.3/topics/concepts/rate-limiting-at-the-edge.md +++ /dev/null @@ -1,35 +0,0 @@ ---- - description: Rate limiting concepts at the edge is a technique used to prevent a sudden or sustained increase in user traffic fr… | $productName$ ---- - -# Rate limiting concepts at the edge - -Rate limiting at the edge is a technique that is used to prevent a sudden or sustained increase in user traffic from breaking an API or underlying service. On the Internet, users can do whatever they want to your APIs, as you have no direct control over these end-users. Whether it’s intentional or not, these users can impact the availability, responsiveness, and scalability of your service. - -## Two approaches: Rate limiting and load shedding - -Rate limiting use cases that fall into this scenario range from implementing functional requirements related to a business scenario -- for example, where requests from paying customers is prioritized over requests from non-paying trial users -- to implementing cross-functional requirements, such as resilience from a malicious actor attempting to issue a denial-of-service (DoS) attack. - -A closely related technique to rate limiting is load shedding, and this can be used to selectively prioritize traffic (by dropping requests) based on the state of the entire system. For example, if a backend data store has become overloaded and slow to respond, it may be appropriate to drop (or “shed”) low priority requests or requests that are not time sensitive. - -## Use cases and scenarios - -The table below outlines several scenarios where rate limiting and load shedding can provide an effective solution to a range of functional and cross-functional requirements. The “Type of Rate Limiter” column provides a summary of the category of rate limiting that would be most appropriate for the scenario, and the “Specifics” column outlines what business or system properties would be involved in computing rate limiting decisions. - -| Scenario | Type of Rate Limiter |                            Specifics                        -| --- | --- | --- | -**Fairness.** One or more users are sending large volumes of requests, and thus impacting other users of the API | **User request rate limiting -** restricts each user to a predetermined number of requests per time unit.

**Concurrent user request limiting -** limits the number of concurrent user requests that can be inflight at any given point in time. |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
  • Geographic rate limiter
  • Time-based rate limiter
-**Prioritisation.** The business model depends on handling high priority requests over others | **User request rate limiting** |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device, free vs non-free user etc)
-**Resilience.** The API backend cannot scale rapidly enough to meet request demand due to a technical issue. | **Backend utilisation load shedder -** rate limit based upon utilisation of aggregate backend instances.

**Node/server utilisation load shedder -** rate limit based upon utilisation of individual or isolated groups of compute nodes/servers. |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
-**Security.** Prevent bad actors from using a DoS attack to overwhelm services, fuzzing, or brute force attacks |**User request rate limiting**

**Node/server utilisation load shedder** |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
  • Service identifier load shedder e.g. login service, audit service
-**Responsiveness.** As per the Reactive Manifesto, responsive systems focus on providing rapid and consistent response times, establishing reliable upper bounds so they deliver a consistent quality of service | **Concurrent user request limiting**

**Backend utilisation load shedder**

**Node/server utilisation load shedder** |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
  • Service identifier load shedder e.g. login service, audit service
- -## Avoiding contention with rate limiting configuration: Decoupling Dev and Ops - -One of the core features of $productName$ is the decentralization of configuration, allowing operations and development teams to independently control $productName$, as well as individual application development teams to minimize collaboration when configuring independently deployable services. This same approach applies to rate limiting configuration. - -## Benefits of applying a rate limiter to the edge - -Modern applications and APIs can experience floods of traffic over a short time period (e.g. from achieving a HackerNews front page link), and increasingly bad actors and cyber criminals are targeting public-facing services. - -By implementing rate limiting and load shedding capabilities at the edge, a large amount of scenarios that are bad for business can be mitigated. These capabilities also make the life of the operations and development team that much easier, as the need to constantly firefight ingress traffic is reduced. diff --git a/content/en/docs/3.3/topics/install/ambassador-oss-community.md b/content/en/docs/3.3/topics/install/ambassador-oss-community.md deleted file mode 100644 index b53d1407..00000000 --- a/content/en/docs/3.3/topics/install/ambassador-oss-community.md +++ /dev/null @@ -1,14 +0,0 @@ -# Integration in community projects - -import Table from "../../../../../src/components/CommunityTable"; - -**$AESproductName$ is now available and includes additional functionality beyond the current $OSSproductName$.** -These features include automatic HTTPS, OAuth/OpenID Connect authentication support, integrated rate -limiting, a developer portal, and [more](/edge-stack-faq/). - -## $OSSproductName$ integrations - -If you still want to use just $OSSproductName$, don't worry! $OSSproductName$ -is currently available out-of-the-box in some Kubernetes installers and local environments. - -
\ No newline at end of file diff --git a/content/en/docs/3.3/topics/install/bare-metal.md b/content/en/docs/3.3/topics/install/bare-metal.md deleted file mode 100644 index 84ac1c8d..00000000 --- a/content/en/docs/3.3/topics/install/bare-metal.md +++ /dev/null @@ -1,93 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Install with bare metal - -In cloud environments, provisioning a readily available network load balancer with $productName$ is the best option for handling ingress into your Kubernetes cluster. When running Kubernetes on a bare metal setup, where network load balancers are not available by default, we need to consider different options for exposing $productName$. - -## Exposing $productName$ via NodePort - -The simplest way to expose an application in Kubernetes is via a `NodePort` service. In this configuration, we create the $productName$ service] and identify `type: NodePort` instead of `LoadBalancer`. Kubernetes will then create a service and assign that service a port to be exposed externally and direct traffic to $productName$ via the defined `port`. - -```yaml ---- -apiVersion: v1 -kind: Service -metadata: - name: ambassador -spec: - type: NodePort - ports: - - name: http - port: 8088 - targetPort: 8080 - nodePort: 30036 # Optional: Define the port you would like exposed - protocol: TCP - selector: - service: ambassador -``` - -Using a `NodePort` leaves $productName$ isolated from the host network, allowing the Kubernetes service to handle routing to $productName$ pods. You can drop-in this YAML to replace the `LoadBalancer` service in the [YAML installation guide](../yaml-install) and use `http://:/` as the host for requests. - -## Exposing $productName$ via host network - -When running $productName$ on a bare metal install of Kubernetes, you have the option to configure $productName$ pods to use the network of the host they are running on. This method allows you to bind $productName$ directly to port 80 or 443 so you won't need to identify the port in requests. - -i.e `http://:/` becomes `http:///` - -This can be configured by setting `hostNetwork: true` in the $productName$ deployment. `dnsPolicy: ClusterFirstWithHostNet` will also need to set to tell $productName$ to use *KubeDNS* when attempting to resolve mappings. - -```diff ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: ambassador -spec: - replicas: 1 - selector: - matchLabels: - service: ambassador - template: - metadata: - annotations: - sidecar.istio.io/inject: "false" - labels: - service: ambassador - app.kubernetes.io/managed-by: getambassador.io - spec: -+ hostNetwork: true -+ dnsPolicy: ClusterFirstWithHostNet - serviceAccountName: ambassador - containers: - - name: ambassador - image: docker.io/datawire/ambassador:$version$ - resources: - limits: - cpu: 1 - memory: 400Mi - requests: - cpu: 200m - memory: 100Mi - env: - - name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace - livenessProbe: - httpGet: - path: /ambassador/v0/check_alive - port: 8877 - initialDelaySeconds: 30 - periodSeconds: 3 - readinessProbe: - httpGet: - path: /ambassador/v0/check_ready - port: 8877 - initialDelaySeconds: 30 - periodSeconds: 3 - restartPolicy: Always -``` - -This configuration does not require a defined $productName$ service, so you can remove that service if you have defined one. - -**Note:** Before configuring $productName$ with this method, consider some of the functionality that is lost by bypassing the Kubernetes service including only having one $productName$ able to bind to port 8080 or 8443 per node and losing any load balancing that is typically performed by Kubernetes services. diff --git a/content/en/docs/3.3/topics/install/convert-to-v3alpha1.md b/content/en/docs/3.3/topics/install/convert-to-v3alpha1.md deleted file mode 100644 index 2d8dfb79..00000000 --- a/content/en/docs/3.3/topics/install/convert-to-v3alpha1.md +++ /dev/null @@ -1,275 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Convert Configuration to `getambassador.io/v3alpha1` - -Once your $productName$ $version$ installation is running, it is **strongly recommended** that -you convert your existing configuration resources from `getambassador.io/v2` to -`getambassador.io/v3alpha1`. - - - While it is not necessary to convert all your resources to getambassador.io/v3alpha1 - immediately, you should ultimately update them all for full functionality with $productName$ - - -In general, the best way to convert any resource is to start with `kubectl get`: using -`kubectl get -o yaml` on any `getambassador.io/v2` resource will cause $productName$ to -translate it to a `getambassador.io/v3alpha1` resource. You can then verify that the -`getambassador.io/v3alpha1` resource looks correct and re-apply it, which will convert the -stored copy to `getambassador.io/v3alpha1`. - -As you do the conversion, here are the things to bear in mind: - -## 1. `ambassador_id` must be an array, not a simple string. - -`getambassador.io/v2` allowed `ambassador_id` to be either an array of strings, or a simple -string. In `getambassador.io/v3alpha1`, only the array form is supported: instead of -`ambassador_id: "foo"`, use `ambassador_id: [ "foo" ]`. This applies to all $productName$ -resources, and is supported by all versions of Ambassador 1.X. - -## 2. You must have a `Listener` for each port on which $productName$ should listen. - - - Learn more about Listener - - -`Listener` is **mandatory**. Defining your own `Listener`(s) allows you to carefully -tailor the set of ports you actually need to use, and exactly which `Host` resources -are matched with them (see below). - -## 3. `Listener`, `Host`, and `Mapping` must be explicit about how they associate. - -You need to have `Listener`s, `Host`s, and `Mapping`s correctly associated with each other for $productName$ 2.X configuration. - -### 3.1. `Listener` and `Host` are associated through `Listener.hostBinding` - - - Learn more about Listener
- Learn more about Host - - -In a `Listener`, the `hostBinding` controls whether a given `Host` is associated with that `Listener`, as discussed in the [`Listener`](../../running/listener) documentation. -**The recommended setting is using `hostBinding.selector`** to choose only `Host`s that have a defined -Kubernetes label: - -```yaml -hostBinding: - selector: - matchLabels: - my-listener: listener-8080 -``` - -The above example shows a `Listener` configured to associate only with `Host`s that have a `my-listener: listener-8080` label. - -For migration purposes, it is possible to have a `Listener` associate with all of the `Host`s. This is not recommended for production environments, however, as it can resulting confusing behavior with large numbers of `Host`s, and it -can also result in larger Envoy configurations that slow reconfiguration. - -```yaml -hostBinding: - namespace: - from: ALL -``` - -but **this is not recommended in production**. Allowing every `Host` to associate -with every `Listener` can result in confusing behavior with large numbers of `Host`s, and it -can also result in larger Envoy configurations that slow reconfiguration. - -### 3.2. `Host` and `Mapping` are associated through `Host.mappingSelector` - - -In $productName$ 1.X, `Mapping`s were nearly always associated with every `Host`. Since this -tends to result in larger Envoy configurations that slow down reconfiguration, $productName$ 2.X -inverts this behavior: **`Host` and `Mapping` will not associate without explicit selection**. - -To have a `Mapping` associate with a `Host`, at least one of the following must hold: - -- Recommended: The `Host` must define a `mappingSelector` that matches a `label` on the `Mapping`. -- Alternately, the `Mapping` must define `hostname` that matches the `hostname` of the `Host`. - (Note that the `hostname` of both `Host` and `AmbasssadorMapping` is a DNS glob.) - -If the `Host` defines a `mappingSelector` and the `Mapping` also defines a `hostname`, both must match. - -As a migration aid: - -- A `Mapping` with a `hostname` of `"*"` will associate with any `Host` that -has no `mappingSelector`, and -- A `v3alpha1` `Mapping` will honor `host` if `hostname` is not present. - - - Learn more about Host
- Learn more about Mapping - - - - A Mapping that specifies host_regex: true is associated with  - all Hosts. This is generally far less desirable than using hostname - with a DNS glob. - - - - Support for host and host_regex will be removed before - v3alpha1 is promoted to v3. - - -## 4. Use `Host` to terminate TLS - - - Learn more about Host
- Learn more about TLSContext - - -In $productName$ 1.X, simply creating a `TLSContext` is sufficient to terminate TLS, but in -2.X you _must_ use a `Host`. The minimal setup to terminate TLS is now something like this: - -```yaml ---- -apiVersion: v1 -kind: Secret -metadata: - name: my-secret -type: kubernetes.io/tls -data: - tls.crt: base64-PEM - tls.key: base64-PEM ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: my-host -spec: - hostname: host.example.com - tlsSecret: my-secret -``` - -In the example above, TLS is terminated for `host.example.com`. A `TLSContext` is still right way to share data -about TLS configuration across `Host`s: set both `tlsSecret` and `tlsContext` in the `Host`. - -## 5. `Mapping` should use `hostname` if possible - - - Learn more about Mapping - - -The `getambassador.io/v3alpha1` `Mapping` introduces the new `hostname` element, which is always -a DNS glob. Using `hostname` instead of `host` is **strongly recommended** unless you absolutely -require regular expression matching: - -- if `host` is being used for an exact match, simply rename `host` to `hostname`. -- if `host` is being used for a regex that effects a prefix or suffix match, rename it - to `hostname` and rewrite the regex into a DNS glob, e.g. `host: .*\.example\.com` would become - `hostname: *.example.com`. - -Additionally, when `hostname` is used, the `Mapping` will be associated with a `Host` only -if `hostname` matches the hostname of the `Host`. If the `Host`'s `selector` is also set, -both the `selector` and the hostname must line up. - - - An 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. - - -## 6. `Mapping` added headers must not be simple strings - - - Learn more about Mapping - - -The `getambassador.io/v2` `Mapping` supported strings and dictionaries for `add_request_headers` and -`add_response_headers`, for example: - -```yaml -add_request_headers: - X-Add-String: bar - X-Add-Dict: - value: bar -``` - -In `getambassador.io/v2`, both `X-Add-String` and `X-Add-Dict` will be added with the value `bar`. - -The string form - shown with `X-Add-String` - is not supported in `getambassador.io/v3alpha1`. Use the -dictionary form instead (which works in both `getambassador.io/v2` and `getambassador.io/v3alpha1`). - -## 7. `Mapping` `headers` and `query_parameters` must not be `true` - - - Learn more about Mapping - - -`headers` and `query_parameters` in a `Mapping` control header matches and query-parameter matches. In -`getambassador.io/v2`, they support both strings and dictionaries, and each has a `_regex` variant. -For example: - - ```yaml - headers: - x-exact-match: foo - x-existence-match: true - headers_regex: - x-regex-match: "fo.*o" - ``` - -In this example, the `Mapping` requires the `x-exact-match` header to have the value `foo`, the -`x-regex-match` whose value starts with `fo` and ends with `o`. However, `x-existence-match` requires -simply that the `x-existence-match` header exists. - -In `getambassador.io/v3alpha1`, the `true` value for an existence match is not supported. Instead, -use `headers_regex` for the same header with value of `.*`. This is fully supported in 1.k) - -`query_parameters` and `query_parameters_regex` work exactly like `headers` and `headers_reex`. - -## 8. `Mapping` `labels` must be converted to new syntax - - - Learn more about Mapping - - -In `getambassador.io/v2`, the `labels` element in a `Mapping` supported several different types of -data. In `getambassador.io/v3alpha1`, all labels must have the same type, so labels must be converted -to the new syntax: - -| `getambassador.io/v2` | `getambassador.io/v3alpha1` | -| -------------------------------- | ----------------------------------------------------------- | -| `source_cluster` | `{ source_cluster: { key: source_cluster } }` | -| `destination_cluster` | `{ destination_cluster: { key: destination_cluster }` } | -| `remote_address` | `{ remote_address: { key: remote_address } }` | -| `{ my_key: { header: my_hdr } }` | `{ generic_key: { value: my_val } }` | -| `{ my_val }` | `{ generic_key: { value: my_val } }` | -| `{ my_key: { header: my_hdr } }` | `{ request_headers: { key: my_key, header_name: my_hdr } }` | - -You can check the [Rate Limiting Labels documentation](../../using/rate-limits#attaching-labels-to-requests) -for more examples. - -## 9. `tls` cannot be `true` in `AuthService`, `Mapping`, `RateLimitService`, and `TCPMapping` - - - Learn more about AuthService
- Learn more about Mapping
- Learn more about RateLimitService
- Learn more about TCPMapping - - -The `tls` element in `AuthService`, `Mapping`, `RateLimitService`, and `TCPMapping` controls TLS -origination. In `getambassador.io/v2`, it may be a string naming a `TLSContext` to use to determine -which client certificate is sent, or the boolean value `true` to request TLS origination with no -cluent certificate being sent. - -In `getambassador.io/v3alpha1`, only the string form is supported. To originate TLS with no client -certificate (the semantic of `tls: true`), omit the `tls` element and prefix the `service` with -`https://`. Note that `TCPMapping` in `getambassador.io/v2` does not support the `https://prefix`. - -## 10. Some `Module` settings have moved or changed - - - Learn more about Listener - - -A few settings have moved from the `Module` in 2.0. Make sure you review the following settings -and move them to their new locations if you are using them in a `Module`: - -- Configuration for the `PROXY` protocol is part of the `Listener` resource in $productName$ 2.0, -so the `use_proxy_protocol` element of the `ambassador` `Module` is no longer supported. - -- `xff_num_trusted_hops` has been removed from the `Module`, and its functionality has been moved -to the `l7Depth` setting in the `Listener` resource. - -- It is no longer possible to configure TLS using the `tls` element of the `Module`. Its -functionality is fully covered by the `TLSContext` resource. diff --git a/content/en/docs/3.3/topics/install/docker.md b/content/en/docs/3.3/topics/install/docker.md deleted file mode 100644 index e430a55c..00000000 --- a/content/en/docs/3.3/topics/install/docker.md +++ /dev/null @@ -1,73 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Run the demo with Docker - -In this Docker quickstart guide, we'll get $productName$ running locally -with a demo configuration. In the next section, we'll then walk through how to -deploy $productName$ in Kubernetes with a custom configuration. - -## 1. Running the demo configuration - -By default, $productName$ uses a demo configuration to show some of its basic features. Get it running with Docker, and expose $productName$ on port 8080: - -``` -docker run -it -p 8080:8080 --name=$productDeploymentName$ --rm docker.io/emissaryingress/emissary:$version$ --demo -``` - -## 2. $productName$'s diagnostics - -$productName$ provides live diagnostics viewable with a web browser. While this would normally not be exposed to the public network, the Docker demo publishes the diagnostics service at the following URL: - -`http://localhost:8080/ambassador/v0/diag/` - -You'll have to authenticate to view this page: use the username `admin`, -password `admin` (obviously this would be a poor choice in the real world!). -We'll talk more about authentication shortly. - -To access the Diagnostics page with authentication, use `curl http://localhost:8080/ambassador/v0/diag/ -u admin:admin` - -Some of the most important information - your $productName$ version, how recently $productName$'s configuration was updated, and how recently Envoy last reported status to $productName$ - is right at the top. The diagnostics overview can show you what it sees in your configuration map, and which Envoy objects were created based on your configuration. - -## 3. The Quote service - -Since $productName$ is a comprehensive, self-service edge stack, its primary purpose is to provide access and control to microservices for the teams that manage them. The demo is preconfigured with a mapping that connects the `/qotm/` resource to the "Quote" service -- a demo service that supplies quotations. You can try it out by opening - -`http://localhost:8080/qotm/` - -in your browser, or from the command line as - -``` -curl -L 'http://localhost:8080/qotm/?json=true' -``` - -This request will route to the `qotm` service at `demo.getambassador.io`, and return a random quote. - -You can see details of the mapping by clicking the blue `http://localhost:8080/qotm/` link at the very bottom of the `Ambassador Route Table` in the diagnostics overview. - -## 4. Authentication - -On the diagnostic overview, you can also see that $productName$ is configured to do authentication -- in the middle of the overview page, you'll see the `Ambassador Services In Use` section, and you can click the `tcp://127.0.0.1:5050` link for details on the `AuthService` configuration. This demo auth service is running inside the Docker container with $productName$ and the Quote service, and $productName$ uses it to mediate access to everything behind $productName$. - -You saw above that access to the diagnostic overview required you to authenticate as an administrator. Getting a random quote does not require authentication, but to get a specific quote, you'll have to authenticate as a demo user. To see this in action, open - -`http://localhost:8080/qotm/quote/5` - -in your browser. From the command line, you can see that: - -``` -curl -Lv 'http://localhost:8080/qotm/quote/5?json=true' -``` - -will return a 401, but - -``` -curl -Lv -u username:password 'http://localhost:8080/qotm/quote/5?json=true' -``` - -will succeed. (Note that that's literally "username" and "password" -- the demo auth service is deliberately not very secure!) - -Note that it's up to the auth service to decide what needs authentication -- teaming $productName$ with an authentication service can be as flexible or strict as you need it to be. - -## Next steps - -We've just walked through some of the core features of $productName$ in a local configuration. To see $productName$ in action on Kubernetes, check out the [Installation Guide](../). diff --git a/content/en/docs/3.3/topics/install/helm.md b/content/en/docs/3.3/topics/install/helm.md deleted file mode 100644 index 4c8a9836..00000000 --- a/content/en/docs/3.3/topics/install/helm.md +++ /dev/null @@ -1,102 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Install with Helm - - - - To migrate from $productName$ 1.X to $productName$ 2.X, see the - [$productName$ migration matrix](../migration-matrix/). This guide - **will not work** for that, due to changes to the configuration - resources used for $productName$ 2.X. - - - -[Helm](https://helm.sh) is a package manager for Kubernetes that automates the release and management of software on Kubernetes. $productName$ can be installed via a Helm chart with a few simple steps, depending on if you are deploying for the first time, upgrading $productName$ from an existing installation, or migrating from $productName$. - -## Before you begin - -The $productName$ Helm chart is hosted by Datawire and published at `https://app.getambassador.io`. - -Start by adding this repo to your helm client with the following command: - -``` -helm repo add datawire https://app.getambassador.io -helm repo update -``` - -## Install with Helm - -When you run the Helm chart, it installs $productName$. - -1. Install the $productName$ CRDs. - - Before installing $productName$ $version$ itself, you must configure your - Kubernetes cluster to support the `getambassador.io/v3alpha1` and `getambassador.io/v2` - configuration resources. This is required. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. Install the $productName$ Chart with the following command: - - ``` - helm install -n $productNamespace$ --create-namespace \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - -3. Next Steps - - $productName$ shold now be successfully installed and running, but in order to get started deploying Services and test routing to them you need to configure a few more resources. - - - [The `Listener` Resource](../../running/listener/) is required to configure which ports the $productName$ pods listen on so that they can begin responding to requests. - - [The `Mapping` Resouce](../../using/intro-mappings/) is used to configure routing requests to services in your cluster. - - [The `Host` Resource](../../running/host-crd/) configures TLS termination for enablin HTTPS communication. - - Explore how $productName$ [configures communication with clients](../../../howtos/configure-communications) - - - We strongly recommend following along with our Quickstart Guide to get started by creating a Listener, deploying a simple service to test with, and setting up a Mapping to route requests from $productName$ to the demo service. - - - - $productName$ $version$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - -For more advanced configuration and details about helm values, -[please see the helm chart.](https://artifacthub.io/packages/helm/datawire/emissary-ingress/) - -## Upgrading an existing installation - -See the [migration matrix](../migration-matrix) for instructions about upgrading -$productName$. diff --git a/content/en/docs/3.3/topics/install/index.less b/content/en/docs/3.3/topics/install/index.less deleted file mode 100644 index bc649e7c..00000000 --- a/content/en/docs/3.3/topics/install/index.less +++ /dev/null @@ -1,57 +0,0 @@ -@media (max-width: 769px) { - #index-installContainer { - flex-direction: column; - } - .index-dropdown { - width: auto; - } - .index-dropBtn { - width: 100%; - } -} - -.index-dropBtn { - background-color: #8e77ff; - color: white; - padding: 10px; - font-size: 16px; - border: none; - margin-top: -20px; -} - -.index-dropdown { - position: relative; - display: inline-block; -} - -.index-dropdownContent { - display: none; - position: absolute; - background-color: #f1f1f1; - width: 100%; - box-shadow: 0px 8px 16px 0px rgba(0, 0, 0, 0.2); - z-index: 1; -} - -.index-dropdownContent a { - color: black; - padding: 12px 16px; - text-decoration: none; - display: block; -} - -.index-dropdownContent a:hover { - background-color: #ddd; -} - -.index-dropdown:hover .index-dropdownContent { - display: block; -} - -.index-dropdown:hover .index-dropBtn { - background-color: #5f3eff; -} - -#index-installContainer { - display: flex; -} diff --git a/content/en/docs/3.3/topics/install/index.md b/content/en/docs/3.3/topics/install/index.md deleted file mode 100644 index 40fa95fd..00000000 --- a/content/en/docs/3.3/topics/install/index.md +++ /dev/null @@ -1,47 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; -import './index.less' - -# Installing $productName$ - -## 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/content/en/docs/3.3/topics/install/migrate-to-2-alternate.md b/content/en/docs/3.3/topics/install/migrate-to-2-alternate.md deleted file mode 100644 index 1ca8f7c3..00000000 --- a/content/en/docs/3.3/topics/install/migrate-to-2-alternate.md +++ /dev/null @@ -1,40 +0,0 @@ ---- - 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$ 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/content/en/docs/3.3/topics/install/migrate-to-3-alternate.md b/content/en/docs/3.3/topics/install/migrate-to-3-alternate.md deleted file mode 100644 index d0b791a1..00000000 --- a/content/en/docs/3.3/topics/install/migrate-to-3-alternate.md +++ /dev/null @@ -1,36 +0,0 @@ -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/content/en/docs/3.3/topics/install/migration-matrix.md b/content/en/docs/3.3/topics/install/migration-matrix.md deleted file mode 100644 index 978e038e..00000000 --- a/content/en/docs/3.3/topics/install/migration-matrix.md +++ /dev/null @@ -1,46 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrading $productName$ - - - Read the instructions below before making any changes to your cluster! - - -There are currently multiple paths for upgrading $productName$, depending on what version you're currently -running, what you want to be running, and whether you installed $productName$ using [Helm](../helm) or -YAML. - -(To check out if you installed $productName$ using Helm, run `helm list --all` and see if -$productName$ is listed. If so, you installed using Helm.) - - - Read the instructions below before making any changes to your cluster! - - -## If you are currently running $AESproductName$ - -See the [instructions on updating $AESproductName$](/docs/edge-stack/$aesDocsVersion$/topics/install/migration-matrix/). - -## If you installed $OSSproductName$ using Helm - -| If you're running. | You can upgrade to | -|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------| -| $OSSproductName$ $version$ | [$AESproductName$ $aesVersion$](/docs/edge-stack/$aesDocsVersion$/topics/install/upgrade/helm/emissary-3.3/edge-stack-3.3/) | -| $OSSproductName$ $versionTwoX$ | [$OSSproductName$ $version$](../upgrade/helm/emissary-2.5/emissary-3.3) | -| $OSSproductName$ 2.4.X | [$OSSproductName$ $versionTwoX$](../upgrade/helm/emissary-2.4/emissary-2.X) | -| $OSSproductName$ 2.3.X | [$OSSproductName$ $versionTwoX$](../upgrade/helm/emissary-2.3/emissary-2.X) | -| $OSSproductName$ 2.0.5 | [$OSSproductName$ $versionTwoX$](../upgrade/helm/emissary-2.0/emissary-2.X) | -| $OSSproductName$ $versionOneX$ | [$OSSproductName$ $versionTwoX$](../upgrade/helm/emissary-1.14/emissary-2.X) | -| $OSSproductName$ prior to $versionOneX$ | [$OSSproductName$ $versionOneX$](../../../../1.14/topics/install/upgrading) | - -## If you installed $OSSproductName$ manually by applying YAML - -| If you're running. | You can upgrade to | -|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------| -| $OSSproductName$ $version$ | [$AESproductName$ $aesVersion$](/docs/edge-stack/$aesDocsVersion$/topics/install/upgrade/yaml/emissary-3.3/edge-stack-3.3/) | -| $OSSproductName$ $versionTwoX$ | [$OSSproductName$ $version$](../upgrade/yaml/emissary-2.5/emissary-3.3) | -| $OSSproductName$ 2.4.X | [$OSSproductName$ $versionTwoX$](../upgrade/yaml/emissary-2.4/emissary-2.X) | -| $OSSproductName$ 2.3.X | [$OSSproductName$ $versionTwoX$](../upgrade/yaml/emissary-2.3/emissary-2.X) | -| $OSSproductName$ 2.0.5 | [$OSSproductName$ $versionTwoX$](../upgrade/yaml/emissary-2.0/emissary-2.X) | -| $OSSproductName$ $versionOneX$ | [$OSSproductName$ $versionTwoX$](../upgrade/yaml/emissary-1.14/emissary-2.X) | -| $OSSproductName$ prior to $versionOneX$ | [$OSSproductName$ $versionOneX$](../../../../1.14/topics/install/upgrading) | diff --git a/content/en/docs/3.3/topics/install/upgrade/helm/emissary-1.14/emissary-2.X.md b/content/en/docs/3.3/topics/install/upgrade/helm/emissary-1.14/emissary-2.X.md deleted file mode 100644 index bd61fafc..00000000 --- a/content/en/docs/3.3/topics/install/upgrade/helm/emissary-1.14/emissary-2.X.md +++ /dev/null @@ -1,312 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 1.14.X (Helm) - - - This guide covers migrating from $productName$ 1.14.X to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -We're pleased to introduce $productName$ $versionTwoX$! The 2.X family introduces a number of -changes to allow $productName$ to more gracefully handle larger installations (including -multitenant or multiorganizational installations), reduce memory footprint, and improve -performance. In keeping with [SemVer](https://semver.org), $productName$ 2.X introduces -some changes that aren't backward-compatible with 1.X. These changes are detailed in -[Major Changes in $productName$ 2.X](../../../../../../about/changes-2.x/). - -## Migration Overview - - - Read the migration instructions below before making any changes to your - cluster! - - -The recommended strategy for migration is to run $productName$ 1.14 and $productName$ -$versionTwoX$ side-by-side in the same cluster. This gives $productName$ $versionTwoX$ -and $productName$ 1.14 access to all the same configuration resources, with some -important caveats: - -1. **$productName$ 1.14 will not see any `getambassador.io/v3alpha1` resources.** - - This is intentional; it provides a way to apply configuration only to - $productName$ $versionTwoX$, while not interfering with the operation of your - $productName$ 1.14 installation. - -2. **If needed, you can use labels to further isolate configurations.** - - If you need to prevent your $productName$ $versionTwoX$ installation from - seeing a particular bit of $productName$ 1.14 configuration, you can apply - a Kubernetes label to the configuration resources that should be seen by - your $productName$ $versionTwoX$ installation, then set its - `AMBASSADOR_LABEL_SELECTOR` environment variable to restrict its 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$ $versionTwoX$, then set - `AMBASSADOR_LABEL_SELECTOR=version-two=true` in its Deployment. - -3. **Be careful about label selectors on Kubernetes Services!** - - If you have services in $productName$ 1.14 that use selectors that will match - Pods from $productName$ $versionTwoX$, traffic will be erroneously split between - $productName$ 1.14 and $productName$ $versionTwoX$. The labels used by $productName$ - $versionTwoX$ include: - - ```yaml - app.kubernetes.io/name: emissary-ingress - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/part-of: emissary-ingress - app.kubernetes.io/managed-by: getambassador.io - product: aes - profile: main - ``` - -4. **Be careful to only have one $productName$ Agent running at a time.** - - The $productName$ Agent is responsible for communications between - $productName$ and Ambassador Cloud. If multiple versions of the Agent are - running simultaneously, Ambassador Cloud could see conflicting information - about your cluster. - - The best way to avoid multiple agents when installing with Helm is to use - `--set agent.enabled=false` to tell Helm not to install a new Agent with - $productName$ $versionTwoX$. Once testing is done, you can switch Agents safely. - -You can also migrate by [installing $productName$ $versionTwoX$ in a separate cluster](../../../../migrate-to-2-alternate). -This permits absolute certainty that your $productName$ 1.14 configuration will not be -affected by changes meant for $productName$ $versionTwoX$, and it eliminates concerns about -ACME, but it is more effort. - -## Side-by-Side Migration Steps - -Migration is a seven-step process: - -1. **Make sure that older configuration resources are not present.** - - $productName$ 2.X does not support `getambassador.io/v0` or `getambassador.io/v1` - resources, and Kubernetes will not permit removing support for CRD versions that are - still in use for stored resources. To verify that no resources older than - `getambassador.io/v2` are active, run - - ``` - kubectl get crds -o 'go-template={{range .items}}{{.metadata.name}}={{.status.storedVersions}}{{"\n"}}{{end}}' | fgrep getambassador.io - ``` - - If `v1` is present in the output, **do not begin migration.** The old resources must be - converted to `getambassador.io/v2` and the `storedVersion` information in the cluster - must be updated. If necessary, contact Ambassador Labs on [Slack](http://a8r.io/slack) - for more information. - -2. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you must configure your - Kubernetes cluster to support its new `getambassador.io/v3alpha1` configuration - resources. Note that `getambassador.io/v2` resources are still supported, but **you - must install support for `getambassador.io/v3alpha1`** to run $productName$ $versionTwoX$, - even if you intend to continue using only `getambassador.io/v2` resources for some - time. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -3. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, you need to install $productName$ $versionTwoX$ itself - **in the same namespace as your existing $productName$ 1.14 installation**. It's important - to use the same namespace so that the two installations can see the same secrets, etc. - - Start by making sure that your `emissary` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Typically, $productName$ 1.14 was installed in the `ambassador` namespace. If you installed - $productName$ 1.14 in a different namespace, change the namespace in the commands below. - - - If you do not need to set `AMBASSADOR_LABEL_SELECTOR`: - - ```bash - helm install -n ambassador \ - --set agent.enabled=false \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - - - If you do need to set `AMBASSADOR_LABEL_SELECTOR`, use `--set`, for example: - - ```bash - helm install -n ambassador \ - --set agent.enabled=false \ - --set env.AMBASSADOR_LABEL_SELECTOR="version-two=true" \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 2.X. - Do not use the ambassador Helm chart. - - - - $productName$ $versionTwoX$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - -4. **Install `Listener`s and `Host`s as needed.** - - An important difference between $productName$ 1.14 and $productName$ $versionTwoX$ is the - new **mandatory** `Listener` CRD. Also, when running both installations side by side, - you will need to make sure that a `Host` is present for the new $productName$ $versionTwoX$ - Service. For example: - - ```bash - kubectl apply -f - < - Kubernetes will not allow you to have a 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.
-
- If you find that your $productName$ $versionTwoX$ installation and your $productName$ 1.14 - installation absolutely must have resources that are only seen by one version or the - other way, see overview section 2, "If needed, you can use labels to further isolate configurations". - - - **If you find that you need to roll back**, just reinstall your 1.14 CRDs and delete your - installation of $productName$ $versionTwoX$. - -6. **When ready, switch over to $productName$ $versionTwoX$.** - - You can run $productName$ 1.14 and $productName$ $versionTwoX$ side-by-side as long as you care - to. However, taking full advantage of $productName$ 2.X's capabilities **requires** - [updating your configuration to use `getambassador.io/v3alpha1` configuration resources](../../../../convert-to-v3alpha1), - since some useful features in $productName$ $versionTwoX$ are only available using - `getambassador.io/v3alpha1` resources. - - When you're ready to have $productName$ $versionTwoX$ handle traffic on its own, switch - your original $productName$ 1.14 Service to point to $productName$ $versionTwoX$. Use - `kubectl edit service ambassador` and change the `selectors` to: - - ``` - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/name: emissary-ingress - profile: main - ``` - - Repeat using `kubectl edit service ambassador-admin` for the `ambassador-admin` - Service. - -7. **Finally, install the $productName$ $versionTwoX$ Ambassador Agent.** - - First, scale the 1.14 agent to 0: - - ``` - kubectl scale -n ambassador deployment/ambassador-agent --replicas=0 - ``` - - Once that's done, install the new Agent. **Note that if you needed to set - `AMBASSADOR_LABEL_SELECTOR`, you must add that to this `helm upgrade` command.** - - ```bash - helm upgrade -n ambassador \ - --set agent.enabled=true \ - $productHelmName$ datawire/$productHelmName$ \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - -Congratulations! At this point, $productName$ $versionTwoX$ is fully running and it's safe to remove the `ambassador` and `ambassador-agent` Deployments: - -``` -kubectl delete deployment/ambassador deployment/ambassador-agent -``` - -Once $productName$ 1.14 is no longer running, you may [convert](../../../../convert-to-v3alpha1) -any remaining `getambassador.io/v2` resources to `getambassador.io/v3alpha1`. -You may also want to redirect DNS to the `edge-stack` Service and remove the -`ambassador` Service. diff --git a/content/en/docs/3.3/topics/install/upgrade/helm/emissary-2.0/emissary-2.X.md b/content/en/docs/3.3/topics/install/upgrade/helm/emissary-2.0/emissary-2.X.md deleted file mode 100644 index c0a392f1..00000000 --- a/content/en/docs/3.3/topics/install/upgrade/helm/emissary-2.0/emissary-2.X.md +++ /dev/null @@ -1,75 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.0.5 (Helm) - - - This guide covers migrating from $productName$ 2.0.5 to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster; Helm will not do this for you. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, use Helm to install $productName$ $versionTwoX$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 2.X. - Do not use the ambassador Helm chart. - diff --git a/content/en/docs/3.3/topics/install/upgrade/helm/emissary-2.3/emissary-2.X.md b/content/en/docs/3.3/topics/install/upgrade/helm/emissary-2.3/emissary-2.X.md deleted file mode 100644 index d51f73db..00000000 --- a/content/en/docs/3.3/topics/install/upgrade/helm/emissary-2.3/emissary-2.X.md +++ /dev/null @@ -1,75 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.3.Z (Helm) - - - This guide covers migrating from $productName$ 2.3.Z to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster; Helm will not do this for you. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, use Helm to install $productName$ $versionTwoX$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 2.X. - Do not use the ambassador Helm chart. - diff --git a/content/en/docs/3.3/topics/install/upgrade/helm/emissary-2.4/emissary-2.X.md b/content/en/docs/3.3/topics/install/upgrade/helm/emissary-2.4/emissary-2.X.md deleted file mode 100644 index 3e44b511..00000000 --- a/content/en/docs/3.3/topics/install/upgrade/helm/emissary-2.4/emissary-2.X.md +++ /dev/null @@ -1,75 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.4.Z (Helm) - - - This guide covers migrating from $productName$ 2.4.Z to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster; Helm will not do this for you. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, use Helm to install $productName$ $versionTwoX$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 2.X. - Do not use the ambassador Helm chart. - diff --git a/content/en/docs/3.3/topics/install/upgrade/helm/emissary-2.5/emissary-3.3.md b/content/en/docs/3.3/topics/install/upgrade/helm/emissary-2.5/emissary-3.3.md deleted file mode 100644 index a0f019e9..00000000 --- a/content/en/docs/3.3/topics/install/upgrade/helm/emissary-2.5/emissary-3.3.md +++ /dev/null @@ -1,141 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.5.Z (Helm) - - - This guide covers migrating from $productName$ 2.5.Z to $productName$ $version$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - - - Make sure that you have updated any 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$. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -$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. - -### Resources to check before migrating to $version$. - -$productName$ 3.X has been upgraded from Envoy 1.17.X to Envoy 1.22 which removed support for the Envoy V2 Transport Protocol. This means all `AuthService`, `RatelimitService`, and `LogServices` must be updated to use the V3 Protocol. Additionally support for some of the runtime bootstrap flags has been removed. - -You can refer to the [Major changes in $productName$ 3.x](../../../../../../about/changes-3.y/) guide for an overview of the changes. - -1. $productName$ 3.2 fixed a bug with `Host.spec.selector\mappingSelector` and `Listener.spec.selector` not being properly enforced. - In previous versions, if only a single label from the selector was present on the resource then they would be associated. Additionally, when associating `Hosts` with `Mappings`, if the `Mapping` configured a `hostname` that matched the `hostname` of the `Host` then they would be associated regardless of the configuration of the `selector\mappingSelector` on the `Host`. - - Before upgrading, review your Ambassador resources, and if you make use of the selectors, ensure that every other resource you want it to be associated with contains all the required labels. - - The environment variable `DISABLE_STRICT_LABEL_SELECTORS` can be set to `"true"` on the $productName$ deployment to revert to the - old incorrect behavior to help prevent any configuration issues after upgrading in the event that not all manifests making use of the selectors have been corrected yet. - - For more information on `DISABLE_STRICT_LABEL_SELECTORS` see the [Environment Variables page](../../../../../running/environment). - -2. Check Transport Protocol usage on all resources before migrating. - - The `AuthService`, `RatelimitService`, and `LogServices` 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. - - `protocol_version` should be updated to `v3` for all of the above resources while still running $productName$ $versionTwoX$. As of version `2.3.z`+, support for `protocol_version` `v2` and `v3` is supported in order to allow migration from `protocol_version` `v2` to `v3` before upgrading to $productName$ $version$ where support for `v2` is removed. - - Upgrading any application code for your own implementations of these services is very straightforward. - - The following imports simply need to be updated to switch from Envoy's Transport Protocol `v2` to `v3`, and then the configuration for these resources can be updated to add the `protocl_version: "v3"` when the updated service is deployed. - - `v2` Imports: - ``` - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" - ``` - - `v3` Imports: - ``` - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" - ``` - -3. Check removed runtime changes - - ``` - # 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, - - # Developers 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, - ``` - -4. **Install new CRDs.** - - After reviewing the changes in 3.x and confirming that you are ready to upgrade, the process is the same as upgrading minor versions - in previous version of $productName$ and does not require the complex migration steps that the migration from 1.x tto 2.x required. - - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -5. **Install $productName$ $version$.** - - After installing the new CRDs, use Helm to install $productName$ $version$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 3.Y. - diff --git a/content/en/docs/3.3/topics/install/upgrade/yaml/emissary-1.14/emissary-2.X.md b/content/en/docs/3.3/topics/install/upgrade/yaml/emissary-1.14/emissary-2.X.md deleted file mode 100644 index eb1dcf6c..00000000 --- a/content/en/docs/3.3/topics/install/upgrade/yaml/emissary-1.14/emissary-2.X.md +++ /dev/null @@ -1,282 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 1.14.X (YAML) - - - This guide covers migrating from $productName$ 1.14.X to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -We're pleased to introduce $productName$ $versionTwoX$! The 2.X family introduces a number of -changes to allow $productName$ to more gracefully handle larger installations (including -multitenant or multiorganizational installations), reduce memory footprint, and improve -performance. In keeping with [SemVer](https://semver.org), $productName$ 2.X introduces -some changes that aren't backward-compatible with 1.X. These changes are detailed in -[Major Changes in $productName$ 2.X](../../../../../../about/changes-2.x/). - -## Migration Overview - - - Read the migration instructions below before making any changes to your - cluster! - - -The recommended strategy for migration is to run $productName$ 1.14 and $productName$ -$versionTwoX$ side-by-side in the same cluster. This gives $productName$ $versionTwoX$ -and $productName$ 1.14 access to all the same configuration resources, with some -important caveats: - -1. **$productName$ 1.14 will not see any `getambassador.io/v3alpha1` resources.** - - This is intentional; it provides a way to apply configuration only to - $productName$ $versionTwoX$, while not interfering with the operation of your - $productName$ 1.14 installation. - -2. **If needed, you can use labels to further isolate configurations.** - - If you need to prevent your $productName$ $versionTwoX$ installation from - seeing a particular bit of $productName$ 1.14 configuration, you can apply - a Kubernetes label to the configuration resources that should be seen by - your $productName$ $versionTwoX$ installation, then set its - `AMBASSADOR_LABEL_SELECTOR` environment variable to restrict its 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$ $versionTwoX$, then set - `AMBASSADOR_LABEL_SELECTOR=version-two=true` in its Deployment. - -3. **Be careful about label selectors on Kubernetes Services!** - - If you have services in $productName$ 1.14 that use selectors that will match - Pods from $productName$ $versionTwoX$, traffic will be erroneously split between - $productName$ 1.14 and $productName$ $versionTwoX$. The labels used by $productName$ - $versionTwoX$ include: - - ```yaml - app.kubernetes.io/name: emissary-ingress - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/part-of: emissary-ingress - app.kubernetes.io/managed-by: getambassador.io - product: aes - profile: main - ``` - -4. **Be careful to only have one $productName$ Agent running at a time.** - - The $productName$ Agent is responsible for communications between - $productName$ and Ambassador Cloud. If multiple versions of the Agent are - running simultaneously, Ambassador Cloud could see conflicting information - about your cluster. - - The migration YAML used below to install $productName$ $versionTwoX$ will not - install a duplicate agent. If you are building your own YAML, make sure not - to include a duplicate agent. - -You can also migrate by [installing $productName$ $versionTwoX$ in a separate cluster](../../../../migrate-to-2-alternate). -This permits absolute certainty that your $productName$ 1.14 configuration will not be -affected by changes meant for $productName$ $versionTwoX$, and it eliminates concerns about -ACME, but it is more effort. - -## Side-by-Side Migration Steps - -Migration is a seven-step process: - -1. **Make sure that older configuration resources are not present.** - - $productName$ 2.X does not support `getambassador.io/v0` or `getambassador.io/v1` - resources, and Kubernetes will not permit removing support for CRD versions that are - still in use for stored resources. To verify that no resources older than - `getambassador.io/v2` are active, run - - ``` - kubectl get crds -o 'go-template={{range .items}}{{.metadata.name}}={{.status.storedVersions}}{{"\n"}}{{end}}' | fgrep getambassador.io - ``` - - If `v1` is present in the output, **do not begin migration.** The old resources must be - converted to `getambassador.io/v2` and the `storedVersion` information in the cluster - must be updated. If necessary, contact Ambassador Labs on [Slack](http://a8r.io/slack) - for more information. - -2. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you must configure your - Kubernetes cluster to support its new `getambassador.io/v3alpha1` configuration - resources. Note that `getambassador.io/v2` resources are still supported, but **you - must install support for `getambassador.io/v3alpha1`** to run $productName$ $versionTwoX$, - even if you intend to continue using only `getambassador.io/v2` resources for some - time. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -3. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, you need to install $productName$ $versionTwoX$ itself - **in the same namespace as your existing $productName$ 1.14 installation**. It's important - to use the same namespace so that the two installations can see the same secrets, etc. - - We publish two manifests for different namespaces. Use only the one that - matches the namespace into which you installed $productName$ 1.14: - - - [`emissary-emissaryns.yaml`] for the `emissary` namespace; or - - [`emissary-defaultns.yaml`] for the `default` namespace. - - If you installed $productName$ 1.14 into some other namespace, you'll need to - download one of the files and edit it to match your namespace. - - [`emissary-emissaryns.yaml`]: https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-emissaryns.yaml - [`emissary-defaultns.yaml`]: https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-defaultns.yaml - - **If you need to set `AMBASSADOR_LABEL_SELECTOR`**, you'll need to download - your chosen file and and edit it to do so. - - Assuming that you're using the `default` namespace: - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-defaultns.yaml && \ - kubectl rollout status -n default deployment/edge-stack -w - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - -4. **Install `Listener`s and `Host`s as needed.** - - An important difference between $productName$ 1.14 and $productName$ $versionTwoX$ is the - new **mandatory** `Listener` CRD. Also, when running both installations side by side, - you will need to make sure that a `Host` is present for the new $productName$ $versionTwoX$ - Service. For example: - - ```bash - kubectl apply -f - < - Kubernetes will not allow you to have a 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.
-
- If you find that your $productName$ $versionTwoX$ installation and your $productName$ 1.14 - installation absolutely must have resources that are only seen by one version or the - other way, see overview section 2, "If needed, you can use labels to further isolate configurations". - - - **If you find that you need to roll back**, just reinstall your 1.14 CRDs and delete your - installation of $productName$ $versionTwoX$. - -6. **When ready, switch over to $productName$ $versionTwoX$.** - - You can run $productName$ 1.14 and $productName$ $versionTwoX$ side-by-side as long as you care - to. However, taking full advantage of $productName$ 2.X's capabilities **requires** - [updating your configuration to use `getambassador.io/v3alpha1` configuration resources](../../../../convert-to-v3alpha1), - since some useful features in $productName$ $versionTwoX$ are only available using - `getambassador.io/v3alpha1` resources. - - When you're ready to have $productName$ $versionTwoX$ handle traffic on its own, switch - your original $productName$ 1.14 Service to point to $productName$ $versionTwoX$. Use - `kubectl edit service ambassador` and change the `selectors` to: - - ``` - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/name: emissary-ingress - profile: main - ``` - - Repeat using `kubectl edit service ambassador-admin` for the `ambassador-admin` - Service. - - -Congratulations! At this point, $productName$ $versionTwoX$ is fully running and it's safe to remove the `ambassador` and `ambassador-agent` Deployments: - -``` -kubectl delete deployment/ambassador deployment/ambassador-agent -``` - -Once $productName$ 1.14 is no longer running, you may [convert](../../../../convert-to-v3alpha1) -any remaining `getambassador.io/v2` resources to `getambassador.io/v3alpha1`. -You may also want to redirect DNS to the `edge-stack` Service and remove the -`ambassador` Service. diff --git a/content/en/docs/3.3/topics/install/upgrade/yaml/emissary-2.0/emissary-2.X.md b/content/en/docs/3.3/topics/install/upgrade/yaml/emissary-2.0/emissary-2.X.md deleted file mode 100644 index b16d046f..00000000 --- a/content/en/docs/3.3/topics/install/upgrade/yaml/emissary-2.0/emissary-2.X.md +++ /dev/null @@ -1,65 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.0.5 (YAML) - - - This guide covers migrating from $productName$ 2.0.5 to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, upgrade $productName$ $versionTwoX$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/3.3/topics/install/upgrade/yaml/emissary-2.3/emissary-2.X.md b/content/en/docs/3.3/topics/install/upgrade/yaml/emissary-2.3/emissary-2.X.md deleted file mode 100644 index 0bfa7e4a..00000000 --- a/content/en/docs/3.3/topics/install/upgrade/yaml/emissary-2.3/emissary-2.X.md +++ /dev/null @@ -1,65 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.3.Z (YAML) - - - This guide covers migrating from $productName$ 2.3.Z to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, upgrade $productName$ $versionTwoX$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/3.3/topics/install/upgrade/yaml/emissary-2.4/emissary-2.X.md b/content/en/docs/3.3/topics/install/upgrade/yaml/emissary-2.4/emissary-2.X.md deleted file mode 100644 index 69a69b92..00000000 --- a/content/en/docs/3.3/topics/install/upgrade/yaml/emissary-2.4/emissary-2.X.md +++ /dev/null @@ -1,65 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.4.Z (YAML) - - - This guide covers migrating from $productName$ 2.4.Z to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, upgrade $productName$ $versionTwoX$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/3.3/topics/install/upgrade/yaml/emissary-2.5/emissary-3.3.md b/content/en/docs/3.3/topics/install/upgrade/yaml/emissary-2.5/emissary-3.3.md deleted file mode 100644 index 65e14cb8..00000000 --- a/content/en/docs/3.3/topics/install/upgrade/yaml/emissary-2.5/emissary-3.3.md +++ /dev/null @@ -1,132 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.5.Z (YAML) - - - This guide covers migrating from $productName$ 2.5.Z to $productName$ $version$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - - - Make sure that you have updated any 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$. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading -between versions is straightforward. - -$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. - -### Resources to check before migrating to $version$. - -$productName$ 3.X has been upgraded from Envoy 1.17.X to Envoy 1.22 which removed support for the Envoy V2 Transport Protocol. This means all `AuthService`, `RatelimitService`, and `LogServices` must be updated to use the V3 Protocol. Additionally support for some of the runtime bootstrap flags has been removed. - -You can refer to the [Major changes in $productName$ 3.x](../../../../../../about/changes-3.y/) guide for an overview of the changes. - -1. $productName$ 3.2 fixed a bug with `Host.spec.selector\mappingSelector` and `Listener.spec.selector` not being properly enforced. - In previous versions, if only a single label from the selector was present on the resource then they would be associated. Additionally, when associating `Hosts` with `Mappings`, if the `Mapping` configured a `hostname` that matched the `hostname` of the `Host` then they would be associated regardless of the configuration of the `selector\mappingSelector` on the `Host`. - - Before upgrading, review your Ambassador resources, and if you make use of the selectors, ensure that every other resource you want it to be associated with contains all the required labels. - - The environment variable `DISABLE_STRICT_LABEL_SELECTORS` can be set to `"true"` on the $productName$ deployment to revert to the - old incorrect behavior to help prevent any configuration issues after upgrading in the event that not all manifests making use of the selectors have been corrected yet. - - For more information on `DISABLE_STRICT_LABEL_SELECTORS` see the [Environment Variables page](../../../../../running/environment#disable_strict_label_selectors). - -2. Check Transport Protocol usage on all resources before migrating. - - The `AuthService`, `RatelimitService`, and `LogServices` 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. - - `protocol_version` should be updated to `v3` for all of the above resources while still running $productName$ $versionTwoX$. As of version `2.3.z`+, support for `protocol_version` `v2` and `v3` is supported in order to allow migration from `protocol_version` `v2` to `v3` before upgrading to $productName$ $version$ where support for `v2` is removed. - - Upgrading any application code for your own implementations of these services is very straightforward. - - The following imports simply need to be updated to switch from Envoy's Transport Protocol `v2` to `v3`, and then the configuration for these resources can be updated to add the `protocl_version: "v3"` when the updated service is deployed. - - `v2` Imports: - ``` - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" - ``` - - `v3` Imports: - ``` - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" - ``` - -3. Check removed runtime changes - - ``` - # 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, - - # Developers 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, - ``` - -4. **Install new CRDs.** - - After reviewing the changes in 3.x and confirming that you are ready to upgrade, the process is the same as upgrading minor versions - in previous version of $productName$ and does not require the complex migration steps that the migration from 1.x tto 2.x required. - - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -5. **Install $productName$ $version$.** - - After installing the new CRDs, upgrade $productName$ $version$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/3.3/topics/install/yaml-install.md b/content/en/docs/3.3/topics/install/yaml-install.md deleted file mode 100644 index b28e6265..00000000 --- a/content/en/docs/3.3/topics/install/yaml-install.md +++ /dev/null @@ -1,87 +0,0 @@ ---- - description: In this guide, we'll walk through the process of deploying $productName$ in Kubernetes for ingress routing. ---- - -import Alert from '@material-ui/lab/Alert'; - -# Install manually - - - - To migrate from $productName$ 1.X to $productName$ 2.X, see the - [$productName$ migration matrix](../migration-matrix/). This guide - **will not work** for that, due to changes to the configuration - resources used for $productName$ 2.X. - - - -In this guide, we'll walk you through installing $productName$ in your Kubernetes cluster. - -The manual install process does not allow for as much control over configuration -as the [Helm install method](../helm), so if you need more control over your $productName$ -installation, it is recommended that you use helm. - -## Before you begin - -$productName$ is designed to run in Kubernetes for production. The most essential requirements are: - -* Kubernetes 1.11 or later -* The `kubectl` command-line tool - -## Install with YAML - -$productName$ is typically deployed to Kubernetes from the command line. If you don't have Kubernetes, you should use our [Docker](../docker) image to deploy $productName$ locally. - -1. In your terminal, run the following command: - - ``` - kubectl create namespace $productNamespace$ || true - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml && \ - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-emissaryns.yaml && \ - kubectl -n $productNamespace$ wait --for condition=available --timeout=90s deploy $productDeploymentName$ - ``` - - - $productName$ $version$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. Determine the IP address or hostname of your cluster by running the following command: - - ``` - kubectl get -n $productNamespace$ service $productDeploymentName$ -o "go-template={{range .status.loadBalancer.ingress}}{{or .ip .hostname}}{{end}}" - ``` - - Your load balancer may take several minutes to provision your IP address. Repeat the provided command until you get an IP address. - -3. Next Steps - - $productName$ shold now be successfully installed and running, but in order to get started deploying Services and test routing to them you need to configure a few more resources. - - - [The `Listener` Resource](../../running/listener/) is required to configure which ports the $productName$ pods listen on so that they can begin responding to requests. - - [The `Mapping` Resouce](../../using/intro-mappings/) is used to configure routing requests to services in your cluster. - - [The `Host` Resource](../../running/host-crd/) configures TLS termination for enablin HTTPS communication. - - Explore how $productName$ [configures communication with clients](../../../howtos/configure-communications) - - - We strongly recommend following along with our Quickstart Guide to get started by creating a Listener, deploying a simple service to test with, and setting up a Mapping to route requests from $productName$ to the demo service. - - -## Upgrading an existing installation - -See the [migration matrix](../migration-matrix) for instructions about upgrading -$productName$. diff --git a/content/en/docs/3.3/topics/running/ambassador-deployment.md b/content/en/docs/3.3/topics/running/ambassador-deployment.md deleted file mode 100644 index d870f32c..00000000 --- a/content/en/docs/3.3/topics/running/ambassador-deployment.md +++ /dev/null @@ -1,21 +0,0 @@ -# Deployment architecture - -$productName$ can be deployed in a variety of configurations. The specific configuration depends on your data center. - -## Public cloud - -If you're using a public cloud provider such as Amazon, Azure, or Google, $productName$ can be deployed directly to a Kubernetes cluster running in the data center. Traffic is routed to $productName$ via a cloud-managed load balancer such as an Amazon Elastic Load Balancer or Google Cloud Load Balancer. Typically, this load balancer is transparently managed by Kubernetes in the form of the `LoadBalancer` service type. $productName$ then routes traffic to your services running in Kubernetes. - -## On-Premise data center - -In an on-premise data center, $productName$ is deployed on the Kubernetes cluster. Instead of exposing it via the `LoadBalancer` service type, $productName$ is exposed as a `NodePort`. Traffic is sent to a specific port on any of the nodes in the cluster, which route the traffic to $productName$, which then routes the traffic to your services running in Kubernetes. You'll also need to deploy a separate load balancer to route traffic from your core routers to $productName$. [MetalLB](https://metallb.universe.tf/) is an open-source external load balancer for Kubernetes designed for this problem. Other options are traditional TCP load balancers such as F5 or Citrix Netscaler. - -## Hybrid data center - -Many data centers include services that are running outside of Kubernetes on virtual machines. For $productName$ to route to services both inside and outside of Kubernetes, it needs the real-time network location of all services. This problem is known as "[service discovery](https://www.datawire.io/guide/traffic/service-discovery-microservices/)" and $productName$ supports using [Consul](https://www.consul.io). Services in your data center register themselves with Consul, and $productName$ uses Consul-supplied data to dynamically route requests to available services. - -## Hybrid on-premise data center - -The diagram below details a common network architecture for a hybrid on-premise data center. Traffic flows from core routers to MetalLB, which routes to $productName$ running in Kubernetes. $productName$ routes traffic to individual services running on both Kubernetes and VMs. Consul tracks the real-time network location of the services, which $productName$ uses to route to the given services. - -![Architecture](../../images/consul-ambassador.png) diff --git a/content/en/docs/3.3/topics/running/ambassador-with-aws.md b/content/en/docs/3.3/topics/running/ambassador-with-aws.md deleted file mode 100644 index b321543a..00000000 --- a/content/en/docs/3.3/topics/running/ambassador-with-aws.md +++ /dev/null @@ -1,364 +0,0 @@ -# $productName$ with AWS - -$productName$ is a platform agnostic Kubernetes API gateway. It will run in any distribution of Kubernetes whether it is managed by a cloud provider or on homegrown bare-metal servers. - -This document serves as a reference for different configuration options available when running Kubernetes in AWS. See [Installing $productName$](../../install) for the various installation methods available. - -## Recommended configuration - -There are lot of configuration options available to you when running $productName$ in AWS. While you should read this entire document to understand what is best for you, the following is the recommended configuration when running $productName$ in AWS: - -It is recommended to terminate TLS at $productName$ so you can take advantage of all the TLS configuration options available in $productName$ including setting the allowed TLS versions, setting `alpn_protocol` options, enforcing HTTP -> HTTPS redirection, and [automatic certificate management](../host-crd) in the $productName$. - -When terminating TLS at $productName$, you should deploy a L4 [Network Load Balancer (NLB)](#network-load-balancer-nlb) with the proxy protocol enabled to get the best performance out of your load balancer while still preserving the client IP address. - -The following `Service` should be configured to deploy an NLB with cross zone load balancing enabled (see [NLB notes](#network-load-balancer-nlb) for caveat on the cross-zone-load-balancing annotation). You will need to configure the proxy protocol in the NLB manually in the AWS Console. - -```yaml -apiVersion: v1 -kind: Service -metadata: - name: ambassador - namespace: ambassador - annotations: - service.beta.kubernetes.io/aws-load-balancer-type: "nlb" - service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: "true" -spec: - type: LoadBalancer - ports: - - name: HTTP - port: 80 - targetPort: 8080 - - name: HTTPS - port: 443 - targetPort: 8443 - selector: - service: ambassador -``` - - After deploying the `Service` above and manually enabling the proxy protocol you will need to deploy the following [Ambassador `Module`](../ambassador) to tell $productName$ to use the proxy protocol and then restart $productName$ for the configuration to take effect. - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - use_proxy_proto: true - ``` - - $productName$ will now expect traffic from the load balancer to be wrapped with the proxy protocol so it can read the client IP address. - -## AWS load balancer notes - -AWS provides three types of load balancers: - -### "Classic" Elastic Load Balancer (ELB) - -The ELB is the first generation AWS Elastic Load Balancer. It is the default type of load balancer ensured by a `type: LoadBalancer` `Service` and routes directly to individual EC2 instances. It can be configured to run at layer 4 or layer 7 of the OSI model. See [What is a Classic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/introduction.html) for more details. - -* Ensured by default for a `type: LoadBalancer` `Service` -* Layer 4: TCP, TCP/SSL - * Protocol support - * HTTP(S) - * Websockets - * HTTP/2 - * Connection based load balancing - * Cannot modify the request -* Layer 7: HTTP, HTTPS - * Protocol support - * HTTP(S) - * Request based load balancing - * Can modify the request (append to `X-Forwarded-*` headers) -* Can perform TLS termination - -**Notes:** -- While it has been superseded by the `Network Load Balancer` and `Application Load Balancer` the ELB offers the simplest way of provisioning an L4 or L7 load balancer in Kubernetes. -- All of the [load balancer annotations](#load-balancer-annotations) are respected by the ELB. -- If using the ELB for TLS termination, it is recommended to run in L7 mode so it can modify `X-Forwarded-Proto` correctly. - -### Network Load Balancer (NLB) - -The NLB is a second generation AWS Elastic Load Balancer. It can be ensure by a `type: LoadBalancer` `Service` using an annotation. It can only run at layer 4 of the OSI model and load balances based on connection allowing it to handle millions of requests per second. See [What is a Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/introduction.html) for more details. - -* Can be ensured by a `type: LoadBalancer` `Service` -* Layer 4: TCP, TCP/SSL - * Protocol support - * HTTP(S) - * Websockets - * HTTP/2 - * Connection based load balacing - * Cannot modify the request -* Can perform TLS termination - -**Notes:** -- The NLB is the most efficient load balancer capable of handling millions of requests per second. It is recommended for streaming connections since it will maintain the connection stream between the client and $productName$. -- Most of the [load balancer annotations](#load-balancer-annotations) are respected by the NLB. You will need to manually configure the proxy protocol and take an extra step to enable cross zone load balancing. -- Since it operates at L4 and cannot modify the request, you will need to tell $productName$ if it is terminating TLS or not (see [TLS termination](#tls-termination) notes below). - -### Application Load Balancer (ALB) - -The ALB is a second generation AWS Elastic Load Balancer. It cannot be ensured by a `type: LoadBalancer` `Service` and must be deployed and configured manually. It can only run at layer 7 of the OSI model and load balances based on request information allowing it to perform fine-grained routing to applications. See [What is a Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/introduction.html) for more details. - -* Cannot be configured by a `type: LoadBalancer` `Service` -* Layer 7: HTTP, HTTPS - * Protocol support - * HTTP(S) - * Request based load balancing - * Can modify the request (append to `X-Forwarded-*` headers) -* Can perform TLS termination - -**Notes:** - -- The ALB can perform routing based on the path, headers, host, etc.. Since $productName$ performs this kind of routing in your cluster, unless you are using the same load balancer to route to services outside of Kubernetes, the overhead of provisioning an ALB is often not worth the benefits. -- If you would like to use an ALB, you will need to expose $productName$ with a `type: NodePort` service and manually configure the ALB to forward to the correct ports. -- None of the [load balancer annotations](#load-balancer-annotations) are respected by the ALB. You will need to manually configure all options. -- The ALB will properly set the `X-Forward-Proto` header if terminating TLS. See (see [TLS termination](#tls-termination) notes below). - -## Load balancer annotations - -Kubernetes on AWS exposes a mechanism to request certain load balancer configurations by annotating the `type: LoadBalancer` `Service`. The most complete set and explanations of these annotations can be found in this [Kubernetes document](https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer). This document will go over the subset that is most relevant when deploying $productName$. - -- `service.beta.kubernetes.io/aws-load-balancer-ssl-cert`: - - Configures the load balancer to use a valid certificate ARN to terminate TLS at the Load Balancer. - - Traffic from the client into the load balancer is encrypted but, since TLS is being terminated at the load balancer, traffic from the load balancer to $productName$ will be cleartext. You will need to configure $productName$ differently depending on whether the load balancer is running in L4 or L7 (see [TLS termination](#tls-termination) notes below). - -- `service.beta.kubernetes.io/aws-load-balancer-ssl-ports`: - - Configures which port the load balancer will be listening for SSL traffic on. Defaults to `"*"`. - - If you want to enable cleartext redirection, make sure to set this to `"443"` so traffic on port 80 will come in over cleartext. - -- `service.beta.kubernetes.io/aws-load-balancer-backend-protocol`: - - Configures the ELB to operate in L4 or L7 mode. Can be set to `"tcp"`/`"ssl"` for an L4 listener or `"http"`/`"https"` for an L7 listener. Defaults to `"tcp"` or `"ssl"` if `aws-load-balancer-ssl-cert` is set. - -- `service.beta.kubernetes.io/aws-load-balancer-type: "nlb"`: - - When this annotation is set it will launch a [Network Load Balancer (NLB)](#network-load-balancer-nlb) instead of a classic ELB. - -- `service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled`: - - Configures the load balancer to load balance across zones. For high availability, it is typical to deploy nodes across availability zones so this should be set to `"true"`. - - **Note:** You cannot configure this annotation and `service.beta.kubernetes.io/aws-load-balancer-type: "nlb"` at the same time. You must first deploy the `Service` with an NLB and then update it with the cross zone load balancing configuration. - -- `service.beta.kubernetes.io/aws-load-balancer-proxy-protocol`: - - Configures the ELB to enable the proxy protocol. `"*"`, which enables the proxy protocol on all ELB backends, is the only acceptable value. - - The proxy protocol can be used to preserve the client IP address. - - If setting this value, you need to make sure $productName$ is configured to use the proxy protocol (see [preserving the client IP address](#preserving-the-client-ip-address) below). - - **Note:** This annotation will not be recognized if `aws-load-balancer-type: "nlb"` is configured. Proxy protocol must be manually enabled for NLBs. - -## TLS termination - -TLS termination is an important part of any modern web app. $productName$ exposes a lot of TLS termination configuration options that make it a powerful tool for managing encryption between your clients and microservices. Refer to the [TLS Termination](../tls) documentation for more information on how to configure TLS termination at $productName$. - -With AWS, the AWS Certificate Manager (ACM) makes it easy to configure TLS termination at an AWS load balancer using the annotations explained above. - -This means that, when running $productName$ in AWS, you have the choice between terminating TLS at the load balancer using a certificate from the ACM or at $productName$ using a certificate stored as a `Secret` in your cluster. - -The following documentation will cover the different options available to you and how to configure $productName$ and the load balancer to get the most of each. - -### TLS termination at $productName$ - -Terminating TLS at $productName$ will guarantee you to be able to use all of the TLS termination options that $productName$ exposes including enforcing the minimum TLS version, setting the `alpn_protocols`, and redirecting cleartext to HTTPS. - -If terminating TLS at $productName$, you can provision any AWS load balancer that you want with the following (default) port assignments: - -```yaml -spec: - ports: - - name: http - port: 80 - targetPort: 8080 - - name: https - port: 443 - targetPort: 8443 -``` - -While terminating TLS at $productName$ makes it easier to expose more advanced TLS configuration options, it does have the drawback of not being able to use the ACM to manage certificates. You will have to manage your TLS certificates yourself or use the [automatic certificate management](../host-crd) available in $productName$ to have $productName$ do it for you. - -### TLS termination at the load balancer - -If you choose to terminate TLS at your Amazon load balancer you will be able to use the ACM to manage TLS certificates. This option does add some complexity to your $productName$ configuration, depending on which load balancer you are using. - -Terminating TLS at the load balancer means that $productName$ will be receiving all traffic as un-encrypted cleartext traffic. Since $productName$ expects to be serving both encrypted and cleartext traffic by default, you will need to make the following configuration changes to $productName$ to support this: - -#### L4 load balancer (default ELB or NLB) - -* **Load Balancer Service Configuration:** - The following `Service` will deploy a L4 ELB with TLS termination configured at the load balancer: - ```yaml - apiVersion: v1 - kind: Service - metadata: - name: ambassador - namespace: ambassador - annotations: - service.beta.kubernetes.io/aws-load-balancer-ssl-cert: {{ACM_CERT_ARN}} - service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "443" - spec: - type: LoadBalancer - ports: - - name: HTTP - port: 80 - targetPort: 8080 - - name: HTTPS - port: 443 - targetPort: 8080 - selector: - service: ambassador - ``` - - Note that the `spec.ports` has been changed so both the HTTP and HTTPS ports forward to the cleartext port 8080 on $productName$. - -* **`Host`:** - - The `Host` configures how $productName$ handles encrypted and cleartext traffic. The following `Host` configuration will tell $productName$ to `Route` cleartext traffic that comes in from the load balancer: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Host - metadata: - name: ambassador - spec: - hostname: "*" - selector: - matchLabels: - hostname: wildcard - acmeProvider: - authority: none - requestPolicy: - insecure: - action: Route - ``` - -**Important:** - -Because L4 load balancers do not set `X-Forwarded` headers, $productName$ will not be able to distinguish between traffic that came in to the load balancer as encrypted or cleartext. Because of this, **HTTP -> HTTPS redirection is not possible when terminating TLS at a L4 load balancer**. - -#### L7 load balancer (ELB or ALB) - -* **Load Balancer Service Configuration (L7 ELB):** - - The following `Service` will deploy a L7 ELB with TLS termination configured at the load balancer: - ```yaml - apiVersion: v1 - kind: Service - metadata: - name: ambassador - namespace: ambassador - annotations: - service.beta.kubernetes.io/aws-load-balancer-ssl-cert: {{ACM_CERT_ARN}} - service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "443" - service.beta.kubernetes.io/aws-load-balancer-backend-protocol: "http" - spec: - type: LoadBalancer - ports: - - name: HTTP - port: 80 - targetPort: 8080 - - name: HTTPS - port: 443 - targetPort: 8080 - selector: - service: ambassador - ``` - - Note that the `spec.ports` has been changed so both the HTTP and HTTPS ports forward to the cleartext port 8080 on $productName$. - -* **`Host`:** - - The `Host` configures how $productName$ handles encrypted and cleartext traffic. The following `Host` configuration will tell $productName$ to `Redirect` cleartext traffic that comes in from the load balancer: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Host - metadata: - name: ambassador - spec: - hostname: "*" - selector: - matchLabels: - hostname: wildcard - acmeProvider: - authority: none - requestPolicy: - insecure: - action: Redirect - ``` - -* **Module:** - - Since a L7 load balancer will be able to append to `X-Forwarded` headers, we need to configure $productName$ to trust the value of these headers. The following `Module` will configure $productName$ to trust a single L7 proxy in front of $productName$: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - xff_num_trusted_hops: 1 - use_remote_address: false - ``` - -**Note:** - -$productName$ uses the value of `X-Forwarded-Proto` to know if the request originated as encrypted or cleartext. Unlike L4 load balancers, L7 load balancers will set this header so HTTP -> HTTPS redirection is possible when terminating TLS at a L7 load balancer. - -## Preserving the client IP address - -Many applications will want to know the IP address of the connecting client. In Kubernetes, this IP address is often obscured by the IP address of the `Node` that is forwarding the request to $productName$ so extra configuration must be done if you need to preserve the client IP address. - -In AWS, there are two options for preserving the client IP address. - -1. Use a L7 Load Balancer that sets `X-Forwarded-For` - - A L7 load balancer will populate the `X-Forwarded-For` header with the IP address of the downstream connecting client. If your clients are connecting directly to the load balancer, this will be the IP address of your client. - - When using L7 load balancers, you must configure $productName$ to trust the value of `X-Forwarded-For` and not append its own IP address to it by setting `xff_num_trusted_hops` and `use_remote_address: false` in the [Ambassador `Module`](../ambassador): - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - xff_num_trusted_hops: 1 - use_remote_address: false - ``` - - After configuring the above `Module`, you will need to restart $productName$ for the changes to take effect. - -2. Use the proxy protocol - - The [proxy protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) is a wrapper around an HTTP request that, like `X-Forwarded-For`, lists the IP address of the downstream connecting client but is able to be set by L4 load balancers as well. - - In AWS, you can configure ELBs to use the proxy protocol by setting the `service.beta.kubernetes.io/aws-load-balancer-proxy-protocol: "*"` annotation on the service. You must manually configure this on ALBs and NLBs. - - After configuring the load balancer to use the proxy protocol, you need to tell $productName$ to expect it on the request. - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - use_proxy_proto: true - ``` - - After configuring the above `Module`, you will need to restart $productName$ for the changes to take effect. diff --git a/content/en/docs/3.3/topics/running/ambassador-with-gke.md b/content/en/docs/3.3/topics/running/ambassador-with-gke.md deleted file mode 100644 index 2b90581d..00000000 --- a/content/en/docs/3.3/topics/running/ambassador-with-gke.md +++ /dev/null @@ -1,187 +0,0 @@ -# $productName$ with GKE - -Google offers a [L7 load balancer](https://cloud.google.com/kubernetes-engine/docs/concepts/ingress) to -leverage network services such as managed SSL certificates, SSL offloading or the Google content delivery network. -A L7 load balancer in front of $productName$ can be configured by hand or by using the Ingress-GCE resource. Using the -Ingress resource also allows you to create Google-managed SSL certificates through Kubernetes. - -With this setup, HTTPS will be terminated at the Google load balancer. The load balancer will be created and configured by -the Ingress-GCE resource. The load balancer consists of a set of -[forwarding rules](https://cloud.google.com/load-balancing/docs/forwarding-rule-concepts#https_lb) and a set of -[backend services](https://cloud.google.com/load-balancing/docs/backend-service). -In this setup, the ingress resource creates two forwarding rules, one for HTTP and one for HTTPS. The HTTPS -forwarding rule has the SSL certificates attached. Also, one backend service will be created to point to -a list of instance groups at a static port. This will be the NodePort of the $productName$ service. - -With this setup, the load balancer terminates HTTPS and then directs the traffic to the $productName$ service -via the `NodePort`. $productName$ is then doing all the routing to the other internal/external services. - -# Overview of steps - -1. Install and configure the ingress with the HTTP(S) load balancer -2. Install $productName$ -3. Configure and connect $productName$ to ingress -4. Create an SSL certificate and enable HTTPS -5. Create BackendConfig for health checks -6. Configure $productName$ to do HTTP -> HTTPS redirection - -`ambassador` will be running as a `NodePort` service. Health checks will be configured to go to a BackendConfig resource. - -## 0. $productName$ - -This guide will install $OSSproductName$. You can also install $AESproductName$. Please note: -- The ingress and the `ambassador` service need to run in the same namespace -- The `ambassador` service needs to be of type `NodePort` and not `LoadBalancer`. Also remove the line with `externalTrafficPolicy: Local` -- Ambassador-Admin needs to be of type `NodePort` instead of `ClusterIP` since it needs to be available for health checks - -## 1 . Install and configure ingress with the HTTP(S) load balancer - -Create a GKE cluster through the web console. Use the release channel. When the cluster -is up and running follow [this tutorial from Google](https://cloud.google.com/kubernetes-engine/docs/tutorials/http-balancer) to configure -an ingress and a L7 load balancer. After you have completed these steps you will have a running L7 load balancer -and one service. - -## 2. Install $productName$ - -Follow the first section of the [$OSSproductName$ installation guide](../../install/) to install $OSSproductName$. -Stop before defining the `ambassador` service. - -$productName$ needs to be deployed as `NodePort` instead of `LoadBalancer` to work with the L7 load balancer and the ingress. - -Save the YAML below in ambassador.yaml and apply with `kubectl apply -f ambassador.yaml` - -```yaml -apiVersion: v1 -kind: Service -metadata: - name: ambassador -spec: - type: NodePort - ports: - - port: 8080 - targetPort: 8080 - selector: - service: ambassador -``` - -You will now have an `ambassador` service running next to your ingress. - -## 3. Configure and connect `ambassador` to the ingress - -You need to change the ingress for it to send traffic to `ambassador`. Assuming you have followed the tutorial, you should -have a file named basic-ingress.yaml. Change it to point to `ambassador` instead of web: - -```yaml -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - name: basic-ingress -spec: - backend: - serviceName: ambassador - servicePort: 8080 -``` - -Now let's connect the other service from the tutorial to `ambassador` by specifying a Mapping: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: web - namespace: default -spec: - hostname: "*" - prefix: / - service: web:8080 -``` - -All traffic will now go to `ambassador` and from `ambassador` to the `web` service. You should be able to hit your load balancer and get the output. It may take some time until the load balancer infrastructure has rolled out all changes and you might see gateway errors during that time. -As a side note: right now all traffic will go to the `web` service, including the load balancer health check. - -## 4. Create an SSL certificate and enable HTTPS - -Read up on [managed certificates on GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/managed-certs). You need -a DNS name and point it to the external IP of the load balancer. - -certificate.yaml: -```yaml -apiVersion: networking.gke.io/v1beta1 -kind: ManagedCertificate -metadata: - name: www-example-com -spec: - domains: - - www.example.com -``` - -Modify the ingress from before: -```yaml -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - name: basic-ingress - annotations: - networking.gke.io/managed-certificates: www-example-com -spec: - backend: - serviceName: ambassador - servicePort: 8080 -``` - -Please wait (5-15 minutes) until the certificate is created and all edge servers have the certificates ready. -`kubectl describe ManagedCertificate` will show you the status or go to the web console to view the load balancer. - -You should now be able to access the web service via `https://www.example.com`. - -## 5. Configure BackendConfig for health checks - -Create and apply a BackendConfig resource with a [custom health check](https://cloud.google.com/kubernetes-engine/docs/how-to/ingress-features#direct_health) specified: - -```yaml -apiVersion: cloud.google.com/v1 -kind: BackendConfig -metadata: - name: ambassador-hc-config - namespace: ambassador -spec: - # https://cloud.google.com/kubernetes-engine/docs/how-to/ingress-features - timeoutSec: 30 - connectionDraining: - drainingTimeoutSec: 30 - logging: - enable: true - sampleRate: 1.0 - healthCheck: - checkIntervalSec: 10 - timeoutSec: 10 - port: 8877 - type: HTTP - requestPath: /ambassador/v0/check_alive -``` - -Then edit your previous `ambassador.yaml` file to add an annotation referencing the BackendConfig and apply the file: - -``` -apiVersion: v1 -kind: Service -metadata: - name: ambassador - annotations: - cloud.google.com/backend-config: '{"default": "ambassador-hc-config"}' -spec: - type: NodePort - ports: - - port: 8080 - targetPort: 8080 - selector: - service: ambassador -``` - -## 6. Configure $productName$ to do HTTP -> HTTPS redirection - -Configure $productName$ to [redirect traffic from HTTP to HTTPS](../tls/cleartext-redirection/#http-https-redirection). You will need to restart $productName$ to effect the changes with `kubectl rollout restart deployment ambassador`. - -The result should be that `http://www.example.com` will redirect to `https://www.example.com`. - -You can now add more services by specifying the hostname in the Mapping. diff --git a/content/en/docs/3.3/topics/running/ambassador.md b/content/en/docs/3.3/topics/running/ambassador.md deleted file mode 100644 index 3af41d93..00000000 --- a/content/en/docs/3.3/topics/running/ambassador.md +++ /dev/null @@ -1,558 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# The `Ambassador` `Module` Resource - -
-

Contents

- -* [Envoy](#envoy) -* [General](#general) -* [gRPC](#grpc) -* [Header behavior](#header-behavior) -* [Observability](#observability) -* [Protocols](#protocols) -* [Security](#security) -* [Service health / timeouts](#service-health--timeouts) -* [Traffic management](#traffic-management) - - -
- -If present, the `ambassador` `Module` defines system-wide configuration for $productName$. You won't need it unless you need to change one of the system-wide configuration settings below. - -To use the `ambassador` `Module` to configure $productName$, it MUST be named `ambassador`, otherwise it will be ignored. To create multiple `ambassador` `Module`s in the same Kubernetes namespace, you will need to apply them as annotations with separate `ambassador_id`s: you will not be able to use multiple CRDs. - -There are many items that can be configured on the `ambassador` `Module`. They are listed below with examples and grouped by category. - -## Envoy - -##### Content-Length headers - -* `allow_chunked_length: true` tells Envoy to allow requests or responses with both `Content-Length` and `Transfer-Encoding` headers set. The default is `false`. - -By default, messages with both `Content-Length` and `Content-Transfer-Encoding` are rejected. If `allow_chunked_length` is `true`, $productName$ will remove the `Content-Length` header and process the message. See the [Envoy documentation for more details](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto.html?highlight=allow_chunked_length#config-core-v3-http1protocoloptions). - -##### Envoy access logs - -* `envoy_log_path` defines the path of Envoy's access log. By default this is standard output. -* `envoy_log_type` defines the type of access log Envoy will use. Currently, only `json` or `text` are supported. -* `envoy_log_format` defines the Envoy access log line format. - -These logs can be formatted using [Envoy operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) to display specific information about an incoming request. The example below will show only the protocol and duration of a request: - -```yaml -envoy_log_path: /dev/fd/1 -envoy_log_type: json -envoy_log_format: - { - "protocol": "%PROTOCOL%", - "duration": "%DURATION%" - } -``` - -See the Envoy documentation for the [standard log format](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#default-format-string) and a [complete list of log format operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/access_log). - -##### Envoy validation timeout - -* `envoy_validation_timeout` defines the timeout, in seconds, for validating a new Envoy configuration. The default is 10. - -A value of 0 disables Envoy configuration validation. Most installations will not need to change this setting. - -For example: - -```yaml -envoy_validation_timeout: 30 -``` - -would allow 30 seconds to validate the generated Envoy configuration. - -##### Error response overrides - -* `error_response_overrides` permits changing the status code and body text for 4XX and 5XX response codes. The default is not to override any error responses. - -By default, $productName$ will pass through error responses without modification, and errors generated locally will use Envoy's default response body, if any. - -See [using error response overrides](../custom-error-responses) for usage details. For example, this configuration: - -```yaml -error_response_overrides: - - on_status_code: 404 - body: - text_format: "File not found" -``` - -would explicitly modify the body of 404s to say "File not found". - -##### Forwarding client cert details - -Two attributes allow providing information about the client's TLS certificate to upstream certificates: - -* `forward_client_cert_details: true` will tell Envoy to add the `X-Forwarded-Client-Cert` to upstream - requests. The default is `false`. -* `set_current_client_cert_details` will tell Envoy what information to include in the - `X-Forwarded-Client-Cert` header. The default is not to include the `X-Forwarded-Client-Cert` header at all. - -$productName$ will not forward information about a certificate that it cannot validate. - -See the Envoy documentation on [X-Forwarded-Client-Cert](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers.html?highlight=xfcc#x-forwarded-client-cert) and [SetCurrentClientCertDetails](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto.html#extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-setcurrentclientcertdetails) for more information. - -```yaml -forward_client_cert_details: true -set_current_client_cert_details: SANITIZE -``` - -##### Server name - -* `server_name` allows overriding the server name that Envoy sends with responses to clients. The default is `envoy`. - -##### Suppress Envoy headers - -* `suppress_envoy_headers: true` will prevent $productName$ from emitting certain additional - headers to HTTP requests and responses. The default is `false`. - -For the exact set of headers covered by this config, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter#config-http-filters-router-headers-set) - ---- -## General - -##### Ambassador ID - -* `ambassador_id` allows using multiple instances of $productName$ in the same cluster. The default is unset. - -We recommend _not_ setting `ambassador_id` if you are running only one instance of $productName$ in your cluster. For more information, see the [Running and Deployment documentation](../running/#ambassador_id). - -If used, the `ambassador_id` value must be an array, for example: - -```yaml -ambassador_id: [ "test_environment" ] -``` - -##### Defaults - -* `defaults` provides a dictionary of default values that will be applied to various $productName$ resources. The default is to have no defaults configured. - -See [Using `ambassador` `Module` Defaults](../../using/defaults) for more information. - ---- - -## gRPC - -##### Bridges - -* `enable_grpc_http11_bridge: true` will enable the gRPC-HTTP/1.1 bridge. The default is `false`. -* `enable_grpc_web: true` will enable the gRPC-Web bridge. The default is `false`. - -gRPC is a binary HTTP/2-based protocol. While this allows high performance, it can be problematic for clients that are unable to speak HTTP/2 (such as JavaScript in many browsers, or legacy clients in difficult-to-update environments). - -The gRPC-HTTP/1.1 bridge can translate HTTP/1.1 calls with `Content-Type: application/grpc` into gRPC calls: $productName$ will perform buffering and translation as necessary. For more details on the translation process, see the [Envoy gRPC HTTP/1.1 bridge documentation](https://www.envoyproxy.io/docs/envoy/v1.11.2/configuration/http_filters/grpc_http1_bridge_filter.html). - -Likewise, gRPC-Web is a JSON and HTTP-based protocol that allows browser-based clients to take advantage of gRPC protocols. The gRPC-Web specification requires a server-side proxy to translate between gRPC-Web requests and gRPC backend services, and $productName$ can fill this role when the gRPC-Web bridge is enabled. For more details on the translation process, see the [Envoy gRPC HTTP/1.1 bridge documentation](https://www.envoyproxy.io/docs/envoy/v1.11.2/configuration/http_filters/grpc_http1_bridge_filter.html); for more details on gRPC-Web itself, see the [gRPC-Web client GitHub repo](https://github.com/grpc/grpc-web). - -##### Statistics - -* `grpc_stats` allows enabling telemetry for gRPC calls using Envoy's [gRPC Statistics Filter](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/grpc_stats_filter). The default is disabled. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - grpc_stats: - upstream_stats: true - services: - - name: . - method_names: [] -``` - -Supported parameters: -* `all_methods` -* `services` -* `upstream_stats` - -Available metrics: -* `envoy_cluster_grpc__` -* `envoy_cluster_grpc__request_message_count` -* `envoy_cluster_grpc__response_message_count` -* `envoy_cluster_grpc__success` -* `envoy_cluster_grpc__total` -* `envoy_cluster_grpc_upstream_` - **only when `upstream_stats: true`** - -Please note that `` will only be present if `all_methods` is set or the service and the method are present under `services`. If `all_methods` is false or the method is not on the list, the available metrics will be in the format `envoy_cluster_grpc_`. - -* `all_methods`: If set to true, emit stats for all service/method names. -If set to false, emit stats for all service/message types to the same stats without including the service/method in the name. -**This option is only safe if all clients are trusted. If this option is enabled with untrusted clients, the clients could cause unbounded growth in the number -of stats in Envoy, using unbounded memory and potentially slowing down stats pipelines.** - -* `services`: If set, specifies an allow list of service/methods that will have individual stats emitted for them. Any call that does not match the allow list will be counted in a stat with no method specifier (generic metric). - - - If both all_methods and services are present, all_methods will be ignored. - - -* `upstream_stats`: If true, the filter will gather a histogram for the request time of the upstream. - ---- - -## Header behavior - -##### Header case - -* `proper_case: true` forces headers to have their "proper" case as shown in RFC7230. The default is `false`. -* `header_case_overrides` allows forcing certain headers to have specific casing. The default is to override no headers. - -proper_case and header_case_overrides are mutually exclusive. - -RFC7230 specifies that HTTP header names are case-insensitive, but always shows and refers to headers as starting with a capital letter, continuing in lowercase, then repeating the single capital letter after each non-alpha character. This has become an established convention when working with HTTP: - -- `Host`, not `host` or `HOST` -- `Content-Type`, not `content-type`, `Content-type`, or `cOnTeNt-TyPe` - -Internally, Envoy typically uses [all lowercase](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/header_casing) for header names. This is fully compliant with RFC7230, but some services and clients may require headers to follow the stricter casing rules implied by RFC7230 section headers: in that situation, setting `proper_case: true` will tell Envoy to force all headers to use the casing above. - -Alternately, it is also possible - although less common - for services or clients to require some other specific casing for specific headers. `header_case_overrides` specifies an array of header names: if a case-insensitive match for a header is found in the list, the matching header will be replaced with the one in the list. For example, the following configuration will force headers that match `X-MY-Header` and `X-EXPERIMENTAL` to use that exact casing, regardless of the original case used in flight: - -```yaml -header_case_overrides: -- X-MY-Header -- X-EXPERIMENTAL -``` - -If the upstream service responds with `x-my-header: 1`, $productName$ will return `X-MY-Header: 1` to the client. Similarly, if the client includes `x-ExperiMENTAL: yes` in its request, the request to the upstream service will include `X-EXPERIMENTAL: yes`. Other headers will not be altered; $productName$ will use its default lowercase header. - -Please see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto.html#config-core-v3-http1protocoloptions-headerkeyformat) for more information. Note that in general, we recommend updating clients and services rather than relying on `header_case_overrides`. - -##### Linkerd interoperability - -* `add_linkerd_headers: true` will force $productName$ to include the `l5d-dst-override` header for Linkerd. The default is `false`. - -When using older Linkerd installations, requests going to an upstream service may need to include the `l5d-dst-override` header to ensure that Linkerd will route them correctly. Setting `add_linkerd_headers` does this automatically. See the [Mapping](../../using/mappings#linkerd-interoperability-add_linkerd_headers) documentation for more details. - -##### Max request headers size - -* `max_request_headers_kb` sets the maximum allowed request header size in kilobytes. If not set, the default is 60 KB. - -See [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto.html) for more information. - -##### Preserve external request ID - -* `preserve_external_request_id: true` will preserve any `X-Request-Id` header presented by the client. The default is `false`, in which case Envoy will always generate a new `X-Request-Id` value. - -##### Strip matching host port - -* `strip_matching_host_port: true` will tell $productName$ to strip any port number from the host/authority header before processing and routing the request if that port number matches the port number of Envoy's listener. The default is `false`, which will preserve any port number. - -In the default installation of $productName$ the public port is 443, which then maps internally to 8443, so this only works in custom installations where the public Service port and Envoy listener port match. - -A common reason to try using this property is if you are using gRPC with TLS and your client library appends the port to the Host header (i.e. `myurl.com:443`). We have an alternative solution in our [gRPC guide](../../../howtos/grpc#working-with-host-headers-that-include-the-port) that uses a [Lua script](#lua-scripts) to remove all ports from every Host header for that use case. - ---- - -## Miscellaneous - - -##### Envoy's admin port - -* `admin_port` specifies the port where $productName$'s Envoy will listen for low-level admin requests. The default is 8001; it should almost never need changing. - -##### Lua scripts - -* `lua_scripts` allows defining a custom Lua script to run on every request. The default is to run no script. - -This is useful for simple use cases that mutate requests or responses, for example to add a custom header: - -```yaml -lua_scripts: | - function envoy_on_response(response_handle) - response_handle:headers():add("Lua-Scripts-Enabled", "Processed") - end -``` - -For more details on the Lua API, see the [Envoy Lua filter documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/lua_filter.html). - -Some caveats around the embedded scripts: - -* They run in-process, so any bugs in your Lua script can break every request. -* They're run on every request/response to every URL. -* They're inlined in the $productName$ YAML; as such, we do not recommend using Lua scripts for long, complex logic. - -If you need more flexible and configurable options, $AESproductName$ supports a [pluggable Filter system](/docs/edge-stack/latest/topics/using/filters/). - -##### Merge slashes - -* `merge_slashes: true` will cause $productName$ to merge adjacent slashes in incoming paths when doing route matching and request filtering. The default is `false`. - -For example, with `merge_slashes: true`, a request for `//foo///bar` would be matched to a `Mapping` with prefix `/foo/bar`. - -##### Modify Default Buffer Size - -By default, the Envoy that ships with $productName$ uses a defailt of 1MiB soft limit for an upstream service's read and write buffer limits. This setting allows you to configure that buffer limit. See the [Envoy docs](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto.html?highlight=per_connection_buffer_limit_bytes) for more information. - -```yaml -buffer_limit_bytes: 5242880 # Sets the default buffer limit to 5 MiB -``` - -##### Use $productName$ namespace for service resolution - -* `use_ambassador_namespace_for_service_resolution: true` tells $productName$ to assume that unqualified services are in the same namespace as $productName$. The default is `false`. - -By default, when $productName$ sees a service name without a namespace, it assumes that the namespace is the same as the resource referring to the service. For example, for this `Mapping`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-1 - namespace: foo -spec: - hostname: "*" - prefix: / - service: upstream -``` - -$productName$ would look for a Service named `upstream` in namespace `foo`. - -However, if `use_ambassador_namespace_for_service_resolution` is `true`, this `Mapping` would look for a Service named `foo` in the namespace in which $productName$ is installed instead. - ---- - -## Observability - -##### Diagnostics - -* `diagnostics` controls access to the diagnostics interface. - -By default, $productName$ creates a `Mapping` that allows access to the diagnostic interface at `/ambassador/v0/diag` from anywhere in the cluster. To disable the `Mapping` entirely, set `diagnostics.enabled` to `false`: - - -```yaml -diagnostics: - enabled: false -``` - -With diagnostics disabled, `/ambassador/v0/diag` will respond with 404; however, the service itself is still running, and `/ambassador/v0/diag/` is reachable from inside the $productName$ Pod at `https://localhost:8877`. You can use Kubernetes port forwarding to set up remote access to the diagnostics page temporarily: - -``` -kubectl port-forward -n ambassador deploy/ambassador 8877 -``` - -Alternately, to leave the `Mapping` intact but restrict access to only the local Pod, set `diagnostics.allow_non_local` to `false`: - -```yaml -diagnostics: - allow_non_local: true -``` - -See [Protecting Access to the Diagnostics Interface](../../../howtos/protecting-diag-access) for more information. - ---- -## Protocols - -##### Enable IPv4 and IPv6 - -* `enable_ipv4` determines whether IPv4 DNS lookups are enabled. The default is `true`. -* `enable_ipv6` determines whether IPv6 DNS lookups are enabled. The default is `false`. - -If both IPv4 and IPv6 are enabled, $productName$ will prefer IPv6. This can have strange effects if $productName$ receives `AAAA` records from a DNS lookup, but the underlying network of the pod doesn't actually support IPv6 traffic. For this reason, the default is IPv4 only. - -An [`Mapping`](../../using/mappings) can override both `enable_ipv4` and `enable_ipv6`, but if either is not stated explicitly in a `Mapping`, the values here are used. Most $productName$ installations will probably be able to avoid overriding these settings in Mappings. - -##### HTTP/1.0 support - -* `enable_http10: true` will enable handling incoming HTTP/1.0 and HTTP/0.9 requests. The default is `false`. - ---- -## Security - -##### Cross origin resource sharing (CORS) - -* `cors` sets the default CORS configuration for all mappings in the cluster. The default is that CORS is not configured. - -For example: - -```yaml -cors: - origins: http://foo.example,http://bar.example - methods: POST, GET, OPTIONS - ... -``` - -See the [CORS syntax](../../using/cors) for more information. - -##### IP allow and deny - -* `ip_allow` and `ip_deny` define HTTP source IP address ranges to allow or deny. The default is to allow all traffic. - -Only one of ip_allow and ip_deny may be specified. - -If `ip_allow` is specified, any traffic not matching a range to allow will be denied. If `ip_deny` is specified, any traffic not matching a range to deny will be allowed. A list of ranges to allow and a separate list to deny may not both be specified. - -Both take a list of IP address ranges with a keyword specifying how to interpret the address, for example: - -```yaml -ip_allow: -- peer: 127.0.0.1 -- remote: 99.99.0.0/16 -``` - -The keyword `peer` specifies that the match should happen using the IP address of the other end of the network connection carrying the request: `X-Forwarded-For` and the `PROXY` protocol are both ignored. Here, our example specifies that connections originating from the $productName$ pod itself should always be allowed. - -The keyword `remote` specifies that the match should happen using the IP address of the HTTP client, taking into account `X-Forwarded-For` and the `PROXY` protocol if they are allowed (if they are not allowed, or not present, the peer address will be used instead). This permits matches to behave correctly when, for example, $productName$ is behind a layer 7 load balancer. Here, our example specifies that HTTP clients from the IP address range `99.99.0.0` - `99.99.255.255` will be allowed. - -You may specify as many ranges for each kind of keyword as desired. - -##### Rejecting Client Requests With Escaped Slashes - -* `reject_requests_with_escaped_slashes: true` will tell $productName$ to reject requests containing escaped slashes. The default is `false`. - -When set to `true`, $productName$ will reject any client requests that contain escaped slashes (`%2F`, `%2f`, `%5C`, or `%5c`) in their URI path by returning HTTP 400. By default, $productName$ will forward these requests unmodified. - -In general, a request with an escaped slash will _not_ match a `Mapping` prefix with an unescaped slash. However, external authentication services and other upstream services may handle escaped slashes differently, which can lead to security issues if paths with escaped slashes are allowed. By setting `reject_requests_with_escaped_slashes: true`, this class of security concern can be largely avoided. - -##### Trust downstream client IP - -* `use_remote_address: false` tells $productName$ that it cannot trust the remote address of incoming connections, and must instead rely exclusively on the `X-Forwarded-For` header. The default is `true`. - -When `true` (the default), $productName$ will append its own IP address to the `X-Forwarded-For` header so that upstream services of $productName$ can get the full set of IP addresses that have propagated a request. You may also need to set `externalTrafficPolicy: Local` on your `LoadBalancer` to propagate the original source IP address. - -See the [Envoy documentation on the `X-Forwarded-For header` ](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers) and the [Kubernetes documentation on preserving the client source IP](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/#preserving-the-client-source-ip) for more details. - -##### `X-Forwarded-For` trusted hops - -* `xff_num_trusted_hops` sets the default value for [the `l7Depth` setting of a `Listener`](../listener/#securitymodel). The default is 0. - -See the [`Listener` documentation](../listener/#securitymodel) for more details. - ---- - -## Service health / timeouts - -##### Incoming connection idle timeout - -* `listener_idle_timeout_ms` sets the idle timeout for incoming connections. The default is no timeout, meaning that incoming connections may remain idle forever. - -If set, this specifies the length of time (in milliseconds) that an incoming connection is allowed to be idle before being dropped. This can useful if you have proxies and/or firewalls in front of $productName$ and need to control how $productName$ initiates closing an idle TCP connection. - -Please see the [Envoy documentation on HTTP protocol options](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#config-core-v3-httpprotocoloptions) for more information. - -##### Keepalive - -* `keepalive` sets the global TCP keepalive settings. - -$productName$ will use these settings for all `AmbasasdorMapping`s unless overridden in a `Mapping`'s configuration. Without `keepalive`, $productName$ follows the operating system defaults. - -For example, the following configuration: - -```yaml -keepalive: - time: 2 - interval: 2 - probes: 100 -``` - -would enable keepalives every two seconds (`interval`), starting after two seconds of idleness (`time`), with the connection being dropped if 100 keepalives are sent with no response (`probes`). For more information, see the [Envoy keepalive documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/address.proto.html#config-core-v3-tcpkeepalive). - -##### Upstream idle timeout - -* `cluster_idle_timeout_ms` sets the default idle timeout for upstream connections (by default, one hour). - -If set, this specifies the timeout (in milliseconds) after which an idle connection upstream is closed. The idle timeout can be completely disabled by setting `cluster_idle_timeout_ms: 0`, which risks idle upstream connections never getting closed. - -If not set, the default idle timeout is one hour. - -You can override this setting with [`idle_timeout_ms` on a `Mapping`](../../using/timeouts/). - -##### Upstream max lifetime - -* `cluster_max_connection_lifetime_ms` sets the default maximum lifetime of an upstream connection. - -If set, this specifies the maximum amount of time (in milliseconds) after which an upstream connection is drained and closed, regardless of whether it is idle or not. Connection recreation incurs additional overhead when processing requests. The overhead tends to be nominal for plaintext (HTTP) connections within the same cluster, but may be more significant for secure HTTPS connections or upstreams with high latency. For this reason, it is generally recommended to set this value to at least 10000 ms to minimize the amortized cost of connection recreation while providing a reasonable bound for connection lifetime. - -If not set (or set to zero), then upstream connections may remain open for arbitrarily long. - -You can override this setting with [`cluster_max_connection_lifetime_ms` on a `Mapping`](../../using/timeouts/). - -##### Request timeout - -* `cluster_request_timeout_ms` sets the default end-to-end timeout for a single request. - -If set, this specifies the default end-to-end timeout for every request. - -If not set, the default is three seconds. - -You can override this setting with [`timeout_ms` on a `Mapping`](../../using/timeouts/). - -##### Readiness and liveness probes - -* `readiness_probe` sets whether `/ambassador/v0/check_ready` is automatically mapped -* `liveness_probe` sets whether `/ambassador/v0/check_alive` is automatically mapped - -By default, $productName$ creates `Mapping`s that support readiness and liveness checks at `/ambassador/v0/check_ready` and `/ambassador/v0/check_alive`. To disable the readiness `Mapping` entirely, set `readiness_probe.enabled` to `false`: - - -```yaml -readiness_probe: - enabled: false -``` - -Likewise, to disable the liveness `Mapping` entirely, set `liveness_probe.enabled` to `false`: - - -```yaml -liveness_probe: - enabled: false -``` - -A disabled probe endpoint will respond with 404; however, the service is still running, and will be accessible on localhost port 8877 from inside the $productName$ Pod. - -You can change these to route requests to some other service. For example, to have the readiness probe map to the `quote` application's health check: - -```yaml -readiness_probe: - enabled: true - service: quote - rewrite: /backend/health -``` - -The liveness and readiness probes both support `prefix` and `rewrite`, with the same meanings as for [Mappings](../../using/mappings). - -##### Retry policy - -This lets you add resilience to your services in case of request failures by performing automatic retries. - -```yaml -retry_policy: - retry_on: "5xx" -``` - ---- - -## Traffic management - -##### Circuit breaking - -* `circuit_breakers` sets the global circuit breaking configuration defaults - -You can override the circuit breaker settings for individual `Mapping`s. By default, $productName$ does not configure any circuit breakers. For more information, see the [circuit breaking reference](../../using/circuit-breakers). - -##### Default label domain and labels - -* `default_labels` sets default domains and labels to apply to every request. - -For more on how to use the default labels, , see the [Rate Limit reference](../../using/rate-limits/#attaching-labels-to-requests). - -##### Default load balancer - -* `load_balancer` sets the default load balancing type and policy - -For example, to set the default load balancer to `least_request`: - -```yaml -load_balancer: - policy: least_request -``` - -If not set, the default is to use round-robin load balancing. For more information, see the [load balancer reference](../load-balancer). diff --git a/content/en/docs/3.3/topics/running/custom-error-responses.md b/content/en/docs/3.3/topics/running/custom-error-responses.md deleted file mode 100644 index b0ad9877..00000000 --- a/content/en/docs/3.3/topics/running/custom-error-responses.md +++ /dev/null @@ -1,217 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Custom error responses - -Custom error responses set overrides for HTTP response statuses generated either -by $productName$ or upstream services. - -They can be configured either on the $productName$ -[`Module`](../ambassador) -or on an [`Mapping`](../../using/intro-mappings/), the schema is identical. See -below for more information on [rule precedence](#rule-precedence). - -- `on_status_code`: HTTP status code to match for this rewrite - rule. Only 4xx and 5xx classes are supported. -- `body`: Describes the response body contents and format. - + `content_type`: A string that sets the content type of the - response. - + `text_format`: A string whose value will be used as the new - response body. `Content-Type` will default to `text/plain` if - unspecified. - + `json_format`: A config object whose keys and values will be - serialized as JSON and used as the new response body. - + `text_format_source`: Describes a file to be used as the - response. If used, `filename` must be set and the file must exist - on the $productName$ pod. - * `filename`: A file path on the $productName$ pod that will be used - as the new response body. - -Only one of `text_format`, `json_format`, or `text_format_source` may be provided. - -Custom response bodies are subject to Envoy's AccessLog substitution syntax -and variables, see [Envoy's documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#config-access-log-format-strings) for more information. - -Note that the AccessLog substitutions use `%` as a delimiter (for example, -`%RESPONSE_CODE%`). To include a literal `%` in a custom response body, use `%%`. -For example, - -``` -%%RESPONSE_CODE%% %RESPONSE_CODE% -``` - -would render as - -``` -%RESPONSE_CODE% 401 -``` - -for a request that resulted in a response code of 401. - - - If the % 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. - - -## Simple response bodies - -Simple responses can be be added quickly for convenience. They are inserted into -the manifest as either text or JSON: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador - namespace: ambassador -spec: - config: - error_response_overrides: - - on_status_code: 404 - body: - text_format: "File not found" - - on_status_code: 500 - body: - json_format: - error: "Application error" - status: "%RESPONSE_CODE%" - cluster: "%UPSTREAM_CLUSTER%" -``` -## File response bodies - -For more complex response bodies a file can be returned as the response. -This could be used for a customer friendly HTML document for example. Use -`text_format_source` with a `filename` set as a path on the $productName$ pod. -`content_type` should be used set the specific file type, such as `text/html`. - -First configure the $productName$ module: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador - namespace: ambassador -spec: - config: - error_response_overrides: - - on_status_code: 404 - body: - content_type: "text/html" - text_format_source: - filename: '/ambassador/ambassador-errorpages/404.html' -``` - -Then create the config map containing the HTML file: - -```yaml ---- -apiVersion: v1 -kind: ConfigMap -metadata: - name: ambassador-errorpages - namespace: ambassador -data: - 404.html: | - -

File not found

-

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/content/en/docs/3.3/topics/running/debugging.md b/content/en/docs/3.3/topics/running/debugging.md deleted file mode 100644 index bd376483..00000000 --- a/content/en/docs/3.3/topics/running/debugging.md +++ /dev/null @@ -1,192 +0,0 @@ -# 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. - - - Enabling debug-level logging can produce a lot of log output — enough to - potentially impact the performance of $productName$. We don't recommend running with debug - logging enabled as a matter of course; it's usually better to enable it only when needed, - then reset logging to normal once you're finished debugging. - - -### $productName$ debug logging - -Much of $productName$'s logging is concerned with the business of noticing changes to -Kubernetes resources that specify the $productName$ configuration, and generating new -Envoy configuration in response to those changes. Enabling debug logging for this part -of the system is under the control of two environment variables: - -- Set `AES_LOG_LEVEL=debug` to debug the early boot sequence and $productName$'s interactions - with the Kubernetes cluster (finding changed resources, etc.). -- Set `AMBASSADOR_DEBUG=diagd` to debug the process of generating an Envoy configuration from - the input resources. - -### $productName$ Envoy logging - -Envoy logging is concerned with the actions Envoy is taking for incoming requests. -Typically, Envoy will only output access logs, and certain errors, but enabling Envoy -debug logging will show very verbose information about the actions Envoy is actually -taking. It can be useful for understanding why connections are being closed, or whether -an error status is coming from Envoy or from the upstream service. - -It is possible to enable Envoy logging at boot, but for the most part, it's safer to -enable it at runtime, right before sending a request that is known to have problems. -To enable Envoy debug logging, use `kubectl exec` to get a shell on the $productName$ -pod, then: - - ``` - curl -XPOST http://localhost:8001/logging?level=trace && \ - sleep 10 && \ - curl -XPOST http://localhost:8001/logging?level=warning - ``` - -This will turn on Envoy debug logging for ten seconds, then turn it off again. - -### Viewing logs - -To view the logs from $productName$: - -1. Use the following command to target an individual $productName$ Pod: `kubectl get pods -n $productNamespace$` - - The terminal will print something similar to the following: - - ``` - $ kubectl get pods -n $productNamespace$ - NAME READY STATUS RESTARTS AGE - $productDeploymentName$-85c4cf67b-4pfj2 1/1 Running 0 3m - ``` - -2. Then, run the following: `kubectl logs -n $productNamespace$ <$productDeploymentName$-pod-name>` - -The terminal will print something similar to the following: - - ``` - $ kubectl logs -n $productNamespace$ $productDeploymentName$-85c4cf67b-4pfj2 - 2018-10-10 12:26:50 kubewatch 0.40.0 INFO: generating config with gencount 1 (0 changes) - /usr/lib/python3.6/site-packages/pkg_resources/__init__.py:1235: UserWarning: /ambassador is writable by group/others and vulnerable to attack when used with get_resource_filename. Consider a more secure location (set with .set_extraction_path or the PYTHON_EGG_CACHE environment variable). - warnings.warn(msg, UserWarning) - 2018-10-10 12:26:51 kubewatch 0.40.0 INFO: Scout reports {"latest_version": "0.40.0", "application": "ambassador", "notices": [], "cached": false, "timestamp": 1539606411.061929} - - 2018-10-10 12:26:54 diagd 0.40.0 [P15TMainThread] INFO: thread count 3, listening on 0.0.0.0:8877 - [2018-10-10 12:26:54 +0000] [15] [INFO] Starting gunicorn 19.8.1 - [2018-10-10 12:26:54 +0000] [15] [INFO] Listening at: http://0.0.0.0:8877 (15) - [2018-10-10 12:26:54 +0000] [15] [INFO] Using worker: threads - [2018-10-10 12:26:54 +0000] [42] [INFO] Booting worker with pid: 42 - 2018-10-10 12:26:54 diagd 0.40.0 [P42TMainThread] INFO: Starting periodic updates - [2018-10-10 12:27:01.977][21][info][main] source/server/drain_manager_impl.cc:63] shutting down parent after drain - ``` - -Note that many deployments will have multiple logs, and the logs are independent for each Pod. - -## Examine Pod and container contents - -You can examine the contents of the $productName$ Pod for issues, such as if volume mounts are correct and TLS certificates are present in the required directory, to determine if the Pod has the latest $productName$ configuration, or if the generated Envoy configuration is correct or as expected. In these instructions, we will look for problems related to the Envoy configuration. - -1. To look into an $productName$ Pod, get a shell on the Pod using `kubectl exec`. For example, - - ``` - kubectl exec -it -n $productNamespace$ <$productDeploymentName$-pod-name> -- bash - ``` - -2. Determine the latest configuration. If you haven't overridden the configuration directory, the latest configuration will be in `/ambassador/snapshots`. If you have overridden it, $productName$ saves configurations in `$AMBASSADOR_CONFIG_BASE_DIR/snapshots`. - - In the snapshots directory: - - * `snapshot.yaml` contains the full input configuration that $productName$ has found; - * `aconf.json` contains the $productName$ configuration extracted from the snapshot; - * `ir.json` contains the IR constructed from the $productName$ configuration; and - * `econf.json` contains the Envoy configuration generated from the IR. - - In the snapshots directory, the current configuration will be stored in files with no digit suffix, and older configurations have increasing numbers. For example, `ir.json` is current, `ir-1.json` is the next oldest, then `ir-2.json`, etc. - -3. If something is wrong with `snapshot` or `aconf`, there is an issue with your configuration. If something is wrong with `ir` or `econf`, you should [open an issue on Github](https://github.com/emissary-ingress/emissary/issues/new/choose). - -4. The actual input provided to Envoy is split into `$AMBASSADOR_CONFIG_BASE_DIR/bootstrap-ads.json` and `$AMBASSADOR_CONFIG_BASE_DIR/envoy/envoy.json`. - - - The `bootstrap-ads.json` file contains details about Envoy statistics, logging, authentication, etc. - - The `envoy.json` file contains information about request routing. - - You may generally find it simplest to just look at the `econf.json` files in the `snapshot` - directory, which includes both kinds of configuration. diff --git a/content/en/docs/3.3/topics/running/diagnostics.md b/content/en/docs/3.3/topics/running/diagnostics.md deleted file mode 100644 index 85c4d228..00000000 --- a/content/en/docs/3.3/topics/running/diagnostics.md +++ /dev/null @@ -1,41 +0,0 @@ -# Diagnostics - -If you're experiencing issues with $productName$, log in to your Edge Policy Console and choose from the left menu whether you want to: - -* Debug issues from the Debugging tab -* Check the health status of your services from the Mappings tab - -## Debugging - -If $productName$ is not routing your services as you'd expect, your first step should be $productName$ Diagnostics in the Edge Policy Console. Login to your Edge Policy Console and select the "Debugging" tab from the left menu. - -Some of the most important information (your $productName$ version, how recently $productName$'s configuration was updated, and how recently Envoy last reported status to $productName$) is right at the top. See [Debugging](../debugging) for more information. - -## Health status - -$productName$ displays the health of your services on the Dashboard of your Edge Policy Console. Health is computed as successful requests / total requests and expressed as a percentage. The "total requests" comes from Envoy `upstream_rq_pending_total` stat. "Successful requests" is calculated by substracting `upstream_rq_4xx` and `upstream_rq_5xx` from the total. - -* Red is used when the success rate ranges from 0% - 70%. -* Yellow is used when the success rate ranges from 70% - 90%. -* Green is used when the success rate is > 90%. -* Grey is used when a service is "waiting". This means the success rate cannot be determined because the service has not recieved any requests yet. - -![](../../images/diagnostics-example.png) - -The LEFT image shows what a list of services under the `Debugging tab` in the Edge Policy Consul will look like for each level of health. - -The RIGHT image shows the dial on the hompage of the Edge Policy Console, this will display the ratio of services that are healthy according to these measurements. - - -## Troubleshooting - -If the diagnostics service does not provide sufficient information, Kubernetes and Envoy provide additional debugging information. - -If $productName$ isn't working at all, start by looking at the data from the following: - -* `kubectl describe pod ` will give you a list of all events on the $productName$ pod -* `kubectl logs ambassador` will give you a log from $productName$ itself - -If you need additional help, feel free to join our [Slack channel](http://a8r.io/slack) with the above information (along with your Kubernetes manifest). - -You can also increase the debug of Envoy through the button in the diagnostics panel. Turn on debug logging, issue a request, and capture the log output from the $productName$ pod using `kubectl logs` as described above. diff --git a/content/en/docs/3.3/topics/running/environment.md b/content/en/docs/3.3/topics/running/environment.md deleted file mode 100644 index 807a6ba1..00000000 --- a/content/en/docs/3.3/topics/running/environment.md +++ /dev/null @@ -1,340 +0,0 @@ -# $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_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_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_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_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/content/en/docs/3.3/topics/running/gzip.md b/content/en/docs/3.3/topics/running/gzip.md deleted file mode 100644 index e3005c83..00000000 --- a/content/en/docs/3.3/topics/running/gzip.md +++ /dev/null @@ -1,55 +0,0 @@ -# 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/content/en/docs/3.3/topics/running/host-crd.md b/content/en/docs/3.3/topics/running/host-crd.md deleted file mode 100644 index cd187ebe..00000000 --- a/content/en/docs/3.3/topics/running/host-crd.md +++ /dev/null @@ -1,279 +0,0 @@ -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` - - - Remember that Listener resources are required for a functioning - $productName$ installation!
- Learn more about Listener. - - - - Remember than $productName$ does not make sure that a wildcard Host exists! If the - wildcard behavior is needed, a Host with a hostname of "*" - must be defined by the user. - - -A minimal `Host` resource, assuming no TLS configuration, would be: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: minimal-host -spec: - hostname: host.example.com -``` - -This `Host` tells $productName$ to expect to be reached at `host.example.com`, -with no TLS termination, and only associating with `Mapping`s that also set a -`hostname` that matches `host.example.com`. - -Remember that a 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/content/en/docs/3.3/topics/running/http3.md b/content/en/docs/3.3/topics/running/http3.md deleted file mode 100644 index 9aeb6cac..00000000 --- a/content/en/docs/3.3/topics/running/http3.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -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`. - - -The protocolStack elements need to be entered in the specific order of TLS, HTTP, UDP. - - -The `Listener` configured for HTTP/3 can be bound to the same address and port (`0.0.0.0:8443`) as the `Listener` that supports HTTP/2 and HTTP/1.1. This is not required, but it allows $productName$ to inject the default `alt-svc: h3=":443"; ma=86400, h3-29=":443"; ma=86400` header into the responses returned over the TCP connection with no additional configuration needed. **Most clients such as browsers require the `alt-svc` header to upgrade to HTTP/3**. - - -The current default of 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. - - -```yaml -# This is a standard Listener that leverages TCP to serve HTTP/2 and HTTP/1.1 traffic. -# It is bound to the same address and port (0.0.0.0:8443) as the UDP listener. -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: $productDeploymentName$-https-listener - namespace: $productNamespace$ -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: - namespace: - from: ALL ---- -# This is a Listener that leverages UDP and HTTP to serve HTTP/3 traffic. -# NOTE: Raw UDP traffic is not supported. UDP and HTTP must be used together. -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: $productDeploymentName$-https-listener-udp - namespace: $productNamespace$ -spec: - port: 8443 - # Order is important here. HTTP is required. - protocolStack: - - TLS - - HTTP - - UDP - securityModel: XFP - hostBinding: - namespace: - from: ALL -``` - -### Configuring the Host resource - -Because the QUIC network requires TLS, the certificate needs to be valid so the client can upgrade a connection to HTTP/3. See the [Host documentation](./host-crd.md) for more information on how to configure TLS for a `Host`. - -### Certificate verification - -Clients can only upgrade to an HTTP/3 connection with a valid certificate. If the client won’t upgrade to HTTP/3, verify that you have a valid TLS certificate and that your client can speak **TLS v1.3**. Your `Host` resource should be configured similar to the following: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: my-domain-host -spec: - hostname: your-hostname - # acme isn't required but just shown as an example of how to manage a valid TLS cert - acmeProvider: - email: your-email@example.com - authority: https://acme-v02.api.letsencrypt.org/directory - tls: - # QUIC requires TLS v1.3 version. Verify your client supports it. - min_tls_version: v1.3 - # Either protocol can be upgraded, but http/2 is recommended. - alpn_protocols: h2,http/1.1 -``` - -### External load balancers - -The two most common service types to expose traffic outside of a Kubernetes cluster are: - -- `LoadBalancer`: A load balancer controller generates and manages the cloud provider-specific external load balancer. -- `NodePort`: The platform administrator has to manually set up things like the external load balancer, firewall rules, and health checks. - -#### LoadBalancer setup - -The ideal setup would be to configure a single service of type `LoadBalancer`, but this comes with some current restrictions: -- You need version 1.24 or later of Kubernetes with the [`MixedProtocolLBService` feature enabled](https://kubernetes.io/docs/concepts/services-networking/service/#load-balancers-with-mixed-protocol-types). -- Your cloud service provider needs to support the creation of an external load balancer with mixed protocol types (TCP/UDP), port reuse, and port forwarding. Support for Kubernetes feature flags may vary between cloud service providers. Refer to your provider’s documentation to see if they support this scenario. - -An example `LoadBalancer` configuration that fits the criteria listed above: - -```yaml - -# note: extra fields such as labels and selectors removed for clarity -apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$ - namespace: $productNamespace$ -spec: - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - - name: http3 - port: 443 - targetPort: 8443 - protocol: UDP - type: LoadBalancer -``` - -## Cloud service provider setup - -Once you've completed the steps above, you need to configure HTTP/3 support through your cloud service provider. The configuration processes for each provider can be found here: - -- HTTP/3 setup for [Amazon Elastic Kubernetes Service (EKS)](../../../howtos/http3-eks) -- HTTP/3 setup for [Azure Kubernetes Service (AKS)](../../../howtos/http3-aks) -- HTTP/3 setup for [Google Kubernetes Engine (GKE)](../../../howtos/http3-gke) diff --git a/content/en/docs/3.3/topics/running/index.md b/content/en/docs/3.3/topics/running/index.md deleted file mode 100644 index 6eb7af94..00000000 --- a/content/en/docs/3.3/topics/running/index.md +++ /dev/null @@ -1,16 +0,0 @@ -# Running $productName$ in production - -This section of the documentation is designed for operators and site reliability engineers who are managing the deployment of $productName$. Learn more below: - -* *Global Configuration:* The [Ambassador module](ambassador) is used to set system-wide configuration. -* *Exposing $productName$ to the Internet:* The [`Listener` CRD](listener) defines which ports are exposed, including their protocols and security models. The [`Host` CRD](host-crd) defines how $productName$ manages TLS, domains, and such. -* *Load Balancing:* $productName$ supports a number of different [load balancing strategies](load-balancer) as well as different ways to configure [service discovery](resolvers) -* [Gzip Compression](gzip) -* *Deploying $productName$:* On [Amazon Web Services](ambassador-with-aws) | [Google Cloud](ambassador-with-gke) | [general security and operational notes](running), including running multiple $productNamePlural$ on a cluster -* *TLS/SSL:* [Simultaneously Routing HTTP and HTTPS](tls/cleartext-redirection#cleartext-routing) | [HTTP -> HTTPS Redirection](tls/cleartext-redirection#http-https-redirection) | [Mutual TLS](tls/mtls) | [TLS origination](tls/origination) -* *Statistics and Monitoring:* [Integrating with Prometheus, DataDog, and other monitoring systems](statistics) -* *Extending $productName$* $productName$ can be extended with custom plug-ins that connect via HTTP/gRPC interfaces. [Custom Authentication](services/auth-service) | [The External Auth protocol](services/ext-authz) | [Custom Logging](services/log-service) | [Rate Limiting](services/rate-limit-service) | [Distributed Tracing](services/tracing-service) -* *Troubleshooting:* [Diagnostics](diagnostics) | [Debugging](debugging) -* *Scaling $productName$:* [Scaling $productName$](scaling) -* *Ingress:* $productName$ can function as an [Ingress Controller](ingress-controller) -* *Error Response Overrides:* $productName$ can override 4xx and 5xx responses with [custom response bodies](custom-error-responses) diff --git a/content/en/docs/3.3/topics/running/ingress-controller.md b/content/en/docs/3.3/topics/running/ingress-controller.md deleted file mode 100644 index 9b7afb82..00000000 --- a/content/en/docs/3.3/topics/running/ingress-controller.md +++ /dev/null @@ -1,325 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Ingress controller - -
-

Contents

- -- [When and how to use the Ingress resource](#when-and-how-to-use-the-ingress-resource) -- [What is required to use the Ingress resource?](#what-is-required-to-use-the-ingress-resource) -- [When to use an Ingress instead of annotations or CRDs](#when-to-use-an-ingress-instead-of-annotations-or-crds) -- [Ingress support](#ingress-support) -- [Examples of Ingress configs vs Mapping configs](#examples-of-ingress-configs-vs-mapping-configs) -- [Ingress routes and mappings](#ingress-routes-and-mappings) -- [The Minimal Ingress](#the-minimal-ingress) -- [Name based virtual hosting with an Ambassador ID](#name-based-virtual-hosting-with-an-ambassador-id) -- [TLS Termination](#tls-termination) - -
- -An Ingress resource is a popular way to expose Kubernetes services to the Internet. In order to use Ingress resources, you need to install an [ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/). $productName$ can function as a fully-fledged Ingress controller, making it easy to work with other Ingress-oriented tools within the Kubernetes ecosystem. - -## When and how to use the Ingress resource - -If you're new to $productName$ and to Kubernetes, we'd recommend you start with our [quickstart](../../../tutorials/getting-started/) instead of this Ingress guide. If you're a power user and need to integrate with other software that leverages the Ingress resource, read on. The Ingress specification is very basic and does not support many of the features of $productName$, so you'll be using both the Ingress resource and $productName$'s Mapping resource to manage your Kubernetes services. - -### What is required to use the Ingress resource? - -- Know what version of Kubernetes you are using. - - - In Kubernetes 1.13 and below, the Ingress was only included in the `extensions` API. - - - Starting in Kubernetes 1.14, the Ingress was added to the new `networking.k8s.io` API. - - - Kubernetes 1.18 introduced the IngressClass resource to the existing `networking.k8s.io/v1beta1` API. - - If you are using 1.14 and above, it is recommended to use 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. - - -- You will need RBAC permissions to create Ingress resources in either - the `extensions` `apiGroup` (present in all supported versions of - Kubernetes) or the `networking.k8s.io` `apiGroup` (introduced in - Kubernetes 1.14). - -- $productName$ will need RBAC permissions to get, list, watch, and update Ingress resources. - - You can see this in the [`aes-crds.yaml`](https://app.getambassador.io/yaml/ambassador-docs/latest/aes.yaml) - file, but this is the critical rule to add to $productName$'s `Role` or `ClusterRole`: - - ```yaml - - apiGroups: ['extensions', 'networking.k8s.io'] - resources: ['ingresses', 'ingressclasses'] - verbs: ['get', 'list', 'watch'] - - apiGroups: ['extensions', 'networking.k8s.io'] - resources: ['ingresses/status'] - verbs: ['update'] - ``` - - - This is included by default in all $productName$ installations. - - -- You must create your Ingress resource with the correct `ingress.class`. - - $productName$ will automatically read Ingress resources with the annotation - `kubernetes.io/ingress.class: ambassador`. - -- You may need to set your Ingress resource's `ambassador-id`. - - If you are [using `amabssador-id` on your Module](../running/#ambassador_id), you'll need to add the `getambassador.io/ambassador-id` - annotation to your Ingress. See the [examples below](#name-based-virtual-hosting-with-an-ambassador-id). - -- You must create a Service resource with the correct `app.kubernetes.io/component` label. - - $productName$ will automatically load balance Ingress resources using the endpoint exposed - from the Service with the annotation `app.kubernetes.io/component: ambassador-service`. - - ```yaml - --- - kind: Service - apiVersion: v1 - metadata: - name: ingress-ambassador - labels: - app.kubernetes.io/component: ambassador-service - spec: - externalTrafficPolicy: Local - type: LoadBalancer - selector: - service: ambassador - ports: - - name: http - port: 80 - targetPort: http - - name: https - port: 443 - targetPort: https - ``` - -### When to use an Ingress instead of annotations or CRDs - -We recommend that $productName$ be configured using CRDs. The Ingress resource is available to users who need it for integration with other ecosystem tools, or who feel that it more closely matches their workflows. However, it is important to recognize that the Ingress resource is rather more limited than the $productName$ Mapping is (for example, the Ingress spec has no support for rewriting or for TLS origination). **When in doubt, use CRDs.** - -## Ingress support - -$productName$ supports basic core functionality of the Ingress resource, as defined by the [Ingress resource](https://kubernetes.io/docs/concepts/services-networking/ingress/) itself: - -- Basic routing is supported, including the `route` specification and the default backend functionality. It's particularly easy to use a minimal Ingress to the $productName$ diagnostic UI. -- [TLS termination](../tls/) is supported. You can use multiple Ingress resources for SNI. -- Using the Ingress resource in concert with $productName$ CRDs or annotations is supported. This includes $productName$ annotations on the Ingress resource itself. - -$productName$ does **not** extend the basic Ingress specification with the following exceptions: - -- The `getambassador.io/ambassador-id` annotation allows you to set [the Ambassador ID](../running/#ambassador_id) for the Ingress itself. - -- The `getambassador.io/config` annotation can be provided on the Ingress resource, just as on a Service. - -Note that if you need to set `getambassador.io/ambassador-id` on the Ingress, you will also need to set `ambassador-id` on resources within the annotation. - -## Examples of Ingress configs vs Mapping configs - -### Ingress routes and Mappings - -$productName$ actually creates Mapping objects from the Ingress route rules. These Mapping objects interact with Mappings defined in CRDs **exactly** as they would if the Ingress route rules had been specified with CRDs originally. - -For example, this Ingress resource routes traffic to `/foo/` to `service1`: - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: test-ingress -spec: - rules: - - http: - paths: - - path: /foo/ - backend: - serviceName: service1 - servicePort: 80 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: test-ingress-0-0 -spec: - hostname: '*' - prefix: /foo/ - service: service1:80 -``` - -This YAML will set up $productName$ to do canary routing where 50% of the traffic will go to `service1` and 50% will go to `service2`. - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: test-ingress -spec: - rules: - - http: - paths: - - path: /foo/ - backend: - serviceName: service1 - servicePort: 80 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: my-mapping -spec: - hostname: '*' - prefix: /foo/ - service: service2 -``` - -### The minimal Ingress - -An Ingress resource must provide at least some routes or a [default backend](https://kubernetes.io/docs/concepts/services-networking/ingress/#default-backend). The default backend provides for a simple way to direct all traffic to some upstream service: - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: test-ingress -spec: - backend: - serviceName: exampleservice - servicePort: 8080 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: test-ingress -spec: - hostname: '*' - prefix: / - service: exampleservice:8080 -``` - -### Name based virtual hosting with an Ambassador ID - -This Ingress resource will result in all requests to `foo.bar.com` going to `service1`, and requests to `bar.foo.com` going to `service2`: - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - getambassador.io/ambassador-id: externalid - name: name-virtual-host-ingress -spec: - rules: - - host: foo.bar.com - http: - paths: - - backend: - serviceName: service1 - servicePort: 80 - - host: bar.foo.com - http: - paths: - - backend: - serviceName: service2 - servicePort: 80 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: host-foo-mapping -spec: - ambassador_id: ['externalid'] - prefix: / - host: foo.bar.com - service: service1 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: host-bar-mapping -spec: - ambassador_id: ['externalid'] - prefix: / - host: bar.foo.com - service: service2 -``` - -Read more on the [Kubernetes documentation on name based virtual routing](https://kubernetes.io/docs/concepts/services-networking/ingress/#name-based-virtual-hosting). - -### TLS termination - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: tls-example-ingress -spec: - tls: - - hosts: - - sslexample.foo.com - secretName: testsecret-tls - rules: - - host: sslexample.foo.com - http: - paths: - - path: / - backend: - serviceName: service1 - servicePort: 80 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: sslexample-termination-context -spec: - hosts: - - sslexample.foo.com - secret: testsecret-tls ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: sslexample-mapping -spec: - host: sslexample.foo.com - prefix: / - service: service1 -``` - -Note that this shows TLS termination, not origination: the Ingress spec does not support origination. Read more on the [Kubernetes docs on TLS termination](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls). diff --git a/content/en/docs/3.3/topics/running/listener.md b/content/en/docs/3.3/topics/running/listener.md deleted file mode 100644 index 152e1b74..00000000 --- a/content/en/docs/3.3/topics/running/listener.md +++ /dev/null @@ -1,218 +0,0 @@ -# The `Listener` CRD - -The `Listener` CRD defines where, and how, $productName$ should listen for requests from the network, and which `Host` definitions should be used to process those requests. For further examples of how to use `Listener`, see [Configuring $productName$ Communications](../../../howtos/configure-communications). - -**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. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 # int32, port number on which to listen - protocol: HTTPS # HTTP, HTTPS, HTTPPROXY, HTTPSPROXY, TCP - securityModel: XFP # XFP (for X-Forwarded-Proto), SECURE, INSECURE - statsPrefix: example-listener # default depends on protocol; see below - l7Depth: 0 # int32 - hostBinding: - namespace: - from: SELF # SELF, ALL - selector: ... # Kubernetes label selector -``` - -| Element | Type | Definition | -| :------ | :--- | :--------- | -| `port` | `int32` | The network port on which $productName$ should listen. *Required.* | -| `protocol` | `enum`; see below | A high-level protocol type, like "HTTPS". *Exactly one of `protocol` and `protocolStack` must be supplied.* | -| `protocolStack` | array of `enum`; see below | A sequence of low-level protocols to layer together. *Exactly one of `protocol` and `protocolStack` must be supplied.* | -| `securityModel` | `enum`; see below | How does $productName$ decide whether requests here are secure? *Required.* | -| `statsPrefix` | `string`; see below | Under what name do statistics for this `Listener` appear? *Optional; default depends on protocol.* | -| `l7Depth` | `int32` | How many layer 7 load balancers are between the edge of the network and $productName$? *Optional; default is 0.*| -| `hostBinding` | `struct`, see below | Mechanism for determining which `Host`s will be associated with this `Listener`. *Required* | - -### `protocol` and `protocolStack` - -`protocol` is the **recommended** way to tell $productName$ that a `Listener` expects connections using a well-known protocol. When using `protocol`, `protocolStack` may not also be supplied. - -Valid `protocol` values are: - -| `protocol` | Description | -| :--------- | :---------- | -| `HTTP` | Cleartext-only HTTP. HTTPS is not allowed. | -| `HTTPS` | Either HTTPS or HTTP -- Envoy's TLS support can tell whether or not TLS is in use, and it will set `X-Forwarded-Proto` correctly for later decision-making. | -| `HTTPPROXY` | Cleartext-only HTTP, using the HAProxy `PROXY` protocol. | -| `HTTPSPROXY` | Either HTTPS or HTTP, using the HAProxy `PROXY` protocol. | -| `TCP` | TCP sessions without HTTP at all. You will need to use `TCPMapping`s to route requests for this `Listener`. | -| `TLS` | TLS sessions without HTTP at all. You will need to use `TCPMapping`s to route requests for this `Listener`. | - -### `securityModel` - -`securityModel` defines how the `Listener` will decide whether a request is secure or insecure: - -| `securityModel` | Description | -| :--------- | :---------- | -| `XFP` | Requests are secure if, and only if, `X-Forwarded-Proto` indicates HTTPS. This is common; see below. | -| `SECURE` | Requests are always secure. You might set this if your load balancer always terminates TLS for you, and you can trust the clients. | -| `INSECURE` | Requests are always insecure. You might set this for an HTTP-only `Listener`, or a `Listener` for clients that are expected to be hostile. | - -The `X-Forwarded-Proto` header mentioned above is meant to reflect the protocol the _original client_ -used to contact $productName$. When no layer 7 proxies are in use, Envoy will make certain that the -`X-Forwarded-Proto` header matches the wire protocol of the connection the client made to Envoy, -which allows $productName$ to trust `X-Forwarded-Proto` for routing decisions such as deciding to -redirect requests made using HTTP over to HTTPS for greater security. When using $productName$ as an -edge proxy or a typical API gateway, this is a desirable configuration; setting `securityModel` to -`XFP` makes this easy. - -When layer proxies _are_ in use, the `XFP` setting is often still desirable; however, you will also -need to set `l7Depth` to allow it to function. See below. - -`SECURE` and `INSECURE` are helpful for cases where something downstream of $productName$ should be -allowing only one kind of request to reach $productName$. For example, a `Listener` behind a load -balancer that terminates TLS and checks client certificates might use -`SecurityModel: SECURE`, then use `Host`s to reject insecure requests if one somehow -arrives. - -### `l7Depth` - -When layer 7 (L7) proxies are in use, the connection to $productName$ comes from the L7 proxy itself -rather than from the client. Examining the protocol and IP address of that connection is useless, and -instead you need to configure the L7 proxy to pass extra information about the client to $productName$ -using the `X-Forwarded-Proto` and `X-Forwarded-For` headers. - -However, if $productName$ always trusted `X-Forwarded-Proto` and `X-Forwarded-For`, any client could -use them to lie about itself to $productName$. As a security mechanism, therefore, you must _also_ -set `l7Depth` in the `Listener` to the number of trusted L7 proxies in front of $productName$. If -`l7Depth` is not set in the `Listener`, the `xff_num_trusted_hops` value from the `ambassador` `Module` -will be used. If neither is set, the default `l7Depth` is 0. - -When `l7Depth` is 0, any incoming `X-Forwarded-Proto` is stripped: Envoy always provides an -`X-Forwarded-Proto` matching the wire protocol of the incoming connection, so that `X-Forwarded-Proto` -can be trusted. When `l7Depth` is non-zero, `X-Forwarded-Proto` is accepted from the L7 proxy, and -trusted. The actual wire protocol in use from the L7 proxy to $productName$ is ignored. - -`l7Depth` also affects $productName$'s view of the client's source IP address, which is used as the -`remote_address` field when rate limiting, and for the `X-Envoy-External-Address` header: - -- When `l7Depth` is 0, $productName$ uses the IP address of the incoming connection. -- When `l7Depth` is some value N that is non-zero, the behavior is determined by the value of - `use_remote_address` in the `ambassador` `Module`: - - - When `use_remote_address` is true (the default) then the trusted client address will be the Nth - address from the right end of the `X-Forwarded-For` header. (If the XFF contains fewer than N - addresses, Envoy falls back to using the immediate downstream connection’s source address as a - trusted client address.) - - - When `use_remote_address` is false, the trusted client address is the (N+1)th address from the - right end of XFF. (If the XFF contains fewer than N+1 addresses, Envoy falls back to using the - immediate downstream connection’s source address as a trusted client address.) - - For more detailed examples of this interaction, refer to [Envoy's documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers.html#x-forwarded-for). - - -### `hostBinding` - -`hostBinding` specifies how this `Listener` should determine which `Host`s are associated with it: - -- `namespace.from` allows filtering `Host`s by the namespace of the `Host`: - - `namespace.from: SELF` accepts only `Host`s in the same namespace as the `Listener`. - - `namespace.from: ALL` accepts `Host`s in any namespace. -- `selector` accepts only `Host`s that has labels matching the selector. - -`hostBinding` is mandatory, and at least one of `namespace.from` and `selector` must be set. If both are set, both must match for a `Host` to be accepted. - -### `statsPrefix` - -$productName$ produces detailed [statistics](../statistics) which can be monitored in a variety of ways. Statistics have hierarchical names, and the `Listener` will cause a set of statistics to be logged under the name specified by `statsPrefix`. - -The default `statsPrefix` depends on the protocol for this `Listener`: - -- If the `Listener` speaks HTTPS, the default is `ingress-https`. -- Otherwise, if the `Listener` speaks HTTP, the default is `ingress-http`. -- Otherwise, if the `Listener` speaks TLS, the default is `ingress-tls-$port`. -- Otherwise, the default is `ingress-$port`. - -Note that it doesn't matter whether you use `protocol` or `protocolStack`: what matters is what protocol is actually configured. Also note that the default doesn't take the HAProxy `PROXY` protocol into account. - -Some examples: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 - protocol: HTTPS - ... -``` - -will use a `statsPrefix` of `ingress-https`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 - protocol: TCP - ... -``` - -will use `statsPrefix` of `ingress-8080`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 - protocol: HTTPSPROXY - statsPrefix: proxy-8080 - ... -``` - -would also use `ingress-https`, but it explicitly overrides `statsPrefix` to `proxy-8080`. - -For complete information on which statistics will appear for the `Listener`, see [the Envoy listener statistics documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/listeners/stats.html). Some important statistics include - -| Statistic name | Type | Description | -| :-----------------------------------------------| :-------- | :-------------------------------- | -| `listener.$statsPrefix.downstream_cx_total` | Counter | Total connections | -| `listener.$statsPrefix.downstream_cx_active` | Gauge | Total active connections | -| `listener.$statsPrefix.downstream_cx_length_ms` | Histogram | Connection length in milliseconds | - -### `protocolStack` - -**`protocolStack` is not recommended if you can instead use `protocol`.** - -Where `protocol` allows configuring the `Listener` to use well-known protocol stacks, `protocolStack` allows configuring exactly which protocols will be layered together. If `protocol` allows what you need, it is safer to use `Protocol` than to risk having the stack broken with an incorrect `protocolStack`. - -The possible stack elements are: - -| `ProtocolStack` Element | Description | -| :---------------------- | :---------- | -| `HTTP` | Cleartext-only HTTP; must be layered with `TLS` for HTTPS | -| `PROXY` | The HAProxy `PROXY` protocol | -| `TLS` | TLS | -| `TCP` | Raw TCP | - -`protocolStack` supplies a list of these elements to describe the protocol stack. **Order matters.** Some examples: - -| `protocolStack` | Description | -| :-------------- | :---------- | -| [ `HTTP`, `TCP` ] | Cleartext-only HTTP, exactly equivalent to `protocol: HTTP`. | -| [ `TLS`, `HTTP`, `TCP` ] | HTTPS or HTTP, exactly equivalent to `protocol: HTTPS`. | -| [ `PROXY`, `TLS`, `TCP` ] | The `PROXY` protocol, wrapping `TLS` _afterward_, wrapping raw TCP. This isn't equivalent to any `protocol` setting, and may be nonsensical. | - -## Examples - -For further examples of how to use `Listener`, see [Configuring $productName$ to Communicate](../../../howtos/configure-communications). diff --git a/content/en/docs/3.3/topics/running/load-balancer.md b/content/en/docs/3.3/topics/running/load-balancer.md deleted file mode 100644 index 987a910b..00000000 --- a/content/en/docs/3.3/topics/running/load-balancer.md +++ /dev/null @@ -1,209 +0,0 @@ -# Load balancing - -Load balancing configuration can be set for all $productName$ mappings in the [`ambassador` `Module`](../ambassador), or set per [`Mapping`](../../using/mappings). If nothing is set, simple round robin balancing is used via Kubernetes services. - -To use advanced load balancing, you must first configure a [resolver](../resolvers) that supports advanced load balancing (e.g., the Kubernetes Endpoint Resolver or Consul Resolver). Once a resolver is configured, you can use the `load_balancer` attribute. The following fields are supported: - -```yaml -load_balancer: - policy: -``` - -Supported load balancer policies: - -- `round_robin` -- `least_request` -- `ring_hash` -- `maglev` - -For more information on the different policies and the implications, see [load balancing strategies in Kubernetes](https://blog.getambassador.io/load-balancing-strategies-in-kubernetes-l4-round-robin-l7-round-robin-ring-hash-and-more-6a5b81595d6c). - -## Round robin -When `policy` is set to `round_robin`, $productName$ discovers healthy endpoints for the given mapping, and load balances the incoming L7 requests with round robin scheduling. To specify this: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - resolver: my-resolver - load_balancer: - policy: round_robin -``` - -or, per mapping: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - resolver: my-resolver - hostname: '*' - load_balancer: - policy: round_robin -``` - -Note that load balancing may not appear to be "even" due to Envoy's threading model. For more details, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/faq/load_balancing/concurrency_lb). - -## Least request - -When `policy` is set to `least_request`, $productName$ discovers healthy endpoints for the given mapping, and load balances the incoming L7 requests to the endpoint with the fewest active requests. To specify this: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - resolver: my-resolver - load_balancer: - policy: least_request -``` - -or, per mapping: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend/ -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: least_request -``` - -## Sticky sessions / session affinity - -Configuring sticky sessions makes $productName$ route requests to a specific pod providing your service in a given session. One pod serves all requests from a given session, eliminating the need for session data to be transferred between pods. $productName$ lets you configure session affinity based on the following parameters in an incoming request: - -- Cookie -- Header -- Source IP - -**NOTE:** $productName$ supports sticky sessions using two load balancing policies, `ring_hash` and `maglev`. - -### Cookie - -```yaml -load_balancer: - policy: ring_hash - cookie: - name: - ttl: - path: -``` - -If the cookie you wish to set affinity on is already present in incoming requests, then you only need the `cookie.name` field. However, if you want $productName$ to generate and set a cookie in response to the first request, then you need to specify a value for the `cookie.ttl` field which generates a cookie with the given expiration time. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - hostname: '*' - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - cookie: - name: sticky-cookie - ttl: 60s -``` - -### Header - -```yaml -load_balancer: - policy: ring_hash - header:
-``` - -$productName$ allows header based session affinity if the given header is present on incoming requests. - -Example: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - header: STICKY_HEADER -``` - -#### Source IP - -```yaml -load_balancer: - policy: ring_hash - source_ip: -``` - -$productName$ allows session affinity based on the source IP of incoming requests. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - source_ip: true -``` - -Load balancing can be configured both globally, and overridden on a per mapping basis. The following example configures the default load balancing policy to be round robin, while using header-based session affinity for requests to the `/backend/` endpoint of the quote application: - -Load balancing can be configured both globally, and overridden on a per mapping basis. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - resolver: my-resolver - load_balancer: - policy: round_robin -``` - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - header: STICKY_HEADER -``` diff --git a/content/en/docs/3.3/topics/running/resolvers.md b/content/en/docs/3.3/topics/running/resolvers.md deleted file mode 100644 index 1ace9a86..00000000 --- a/content/en/docs/3.3/topics/running/resolvers.md +++ /dev/null @@ -1,128 +0,0 @@ -# Service discovery and resolvers - -Service discovery is how cloud applications and their microservices are located on the network. In a cloud environment, services are ephemeral, existing only as long as they are needed and in use, so a real-time service discovery mechanism is required. $productName$ uses information from service discovery to determine where to route incoming requests. - -## $productName$ support for service discovery - -$productName$ supports different mechanisms for service discovery. These mechanisms are: - -* Kubernetes service-level discovery (default). -* Kubernetes endpoint-level discovery. -* Consul endpoint-level discovery. - -### Kubernetes service-level discovery - -By default, $productName$ uses Kubernetes DNS and service-level discovery. In a `Mapping` resource, specifying `service: foo` will prompt $productName$ to look up the DNS address of the `foo` Kubernetes service. Traffic will be routed to the `foo` service. Kubernetes will then load balance that traffic between multiple pods. For more details on Kubernetes networking and how this works, see our blog post on [Session affinity, load balancing controls, gRPC-Web, and $productName$](https://blog.getambassador.io/session-affinity-load-balancing-controls-grpc-web-and-ambassador-0-52-2b916b396d0c). - -### Kubernetes endpoint-level discovery - -$productName$ can also watch Kubernetes endpoints. This bypasses the Kubernetes service routing layer and enables the use of advanced load balancing controls such as session affinity and maglev. For more details, see the [load balancing reference](../load-balancer). - -### Consul endpoint-level discovery - -$productName$ natively integrates with [Consul](https://www.consul.io) for endpoint-level service discovery. In this mode, $productName$ obtains endpoint information from Consul. One of the primary use cases for this architecture is in hybrid cloud environments that run a mixture of Kubernetes services as well as VMs, as Consul can serve as the single global registry for all services. - -## The Resolver resource - -The `Resolver` resource is used to configure the discovery service strategy for $productName$. - -### The Kubernetes service resolver - -The Kubernetes Service Resolver configures $productName$ to use Kubernetes services. If no resolver is specified, this behavior is the default. When this resolver is used, the `service.namespace` value from a `Mapping` is handed to the Kubernetes cluster's DNS resolver to determine where requests are sent. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: KubernetesServiceResolver -metadata: - name: kubernetes-service -``` - -### The Kubernetes endpoint resolver - -The Kubernetes Endpoint Resolver configures $productName$ to resolve Kubernetes endpoints. This enables the use of more a [advanced load balancing configuration](../load-balancer). When this resolver is used, the endpoints for the `service` defined in a `Mapping` are resolved and used to determine where requests are sent. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: KubernetesEndpointResolver -metadata: - name: endpoint -``` - -### The Consul resolver - -The Consul Resolver configures $productName$ to use Consul for service discovery. When this resolver is used, the `service` defined in a `Mapping` is passed to Consul, along with the datacenter specified, to determine where requests are sent. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: ConsulResolver -metadata: - name: consul-dc1 -spec: - address: consul-server.default.svc.cluster.local:8500 - datacenter: dc1 -``` -- `address`: The fully-qualified domain name or IP address of your Consul server. This field also supports environment variable substitution. -- `datacenter`: The Consul data center where your services are registered - -You may want to use an environment variable if you're running a Consul agent on each node in your cluster. In this setup, you could do the following: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: ConsulResolver -metadata: - name: consul-dc1 -spec: - address: "${HOST_IP}" - datacenter: dc1 -``` - -and then add the `HOST_IP` environment variable to your Kubernetes deployment: - -```yaml -containers: - - name: example - image: docker.io/datawire/ambassador:$version$ - env: - - name: HOST_IP - valueFrom: - fieldRef: - fieldPath: status.hostIP -``` - -## Using resolvers - -Once a resolver is defined, you can use them in a given `Mapping`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: "*" - prefix: /backend/ - service: quote - resolver: endpoint - load_balancer: - policy: round_robin ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: bar -spec: - hostname: "*" - prefix: /bar/ - service: https://bar:9000 - tls: client-context - resolver: consul-dc1 - load_balancer: - policy: round_robin -``` - -The YAML configuration above will configure $productName$ to use Kubernetes Service Discovery to route to the Consul Service Discovery to route to the `bar` service on requests with `prefix: /bar/`. diff --git a/content/en/docs/3.3/topics/running/running.md b/content/en/docs/3.3/topics/running/running.md deleted file mode 100644 index a28b0cb5..00000000 --- a/content/en/docs/3.3/topics/running/running.md +++ /dev/null @@ -1,338 +0,0 @@ -# Running and deployment - -This section is intended for operators running $productName$, and covers various aspects of deploying and configuring the $productName$ in production. - -## $productName$ and Kubernetes - -$productName$ relies on Kubernetes for reliability, availability, and scalability. This means that features such as Kubernetes readiness and liveness probes, rolling updates, and the Horizontal Pod Autoscaling should be utilized to manage $productName$. - -## Default configuration - -The default configuration of $productName$ includes default [resource limits](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-requests-and-limits-of-pod-and-container), as well as [readiness and liveness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/). These values should be adjusted for your specific environment. - -## Running as non-root - -Starting with $productName$ 0.35, we support running $productName$ as non-root. This is the recommended configuration, and will be the default configuration in future releases. We recommend you configure $productName$ to run as non-root as follows: - -* Have Kubernetes run $productName$ as non-root. This may happen by default (e.g., OpenShift) or you can set a `securityContext` in your Deployment as shown below in this abbreviated example: - -```yaml ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: ambassador -spec: - replicas: 1 - selector: - matchLabels: - service: ambassador - template: - metadata: - labels: - service: ambassador - spec: - containers: - image: docker.io/datawire/aes:$version$ - name: ambassador - restartPolicy: Always - securityContext: - runAsUser: 8888 - serviceAccountName: ambassador -``` - -* Set the `service_port` element in the `ambassador Module` to 8080 (cleartext) or 8443 (TLS). This is the port that $productName$ will use to listen to incoming traffic. Note that any port number above 1024 will work; $productName$ will use 8080/8443 as its defaults in the future. - -* Make sure that incoming traffic to $productName$ is configured to route to the `service_port`. If you're using the default $productName$ configuration, this means configuring the `targetPort` to point to the `service_port` above. - -* If you are using `redirect_cleartext_from`, change the value of this field to point to your cleartext port (e.g., 8080) and set `service_port` to be your TLS port (e.g., 8443). - -## Changing the configuration directory - -While running, $productName$ needs to use a directory within its container for generated configuration data. Normally this is `/ambassador`, but in some situations - especially if running as non-root - it may be necessary to change to a different directory. To do so, set the environment variable `AMBASSADOR_CONFIG_BASE_DIR` to the full pathname of the directory to use, as shown below in this abbreviated example: - -```yaml -env: -- name: AMBASSADOR_CONFIG_BASE_DIR - value: /tmp/ambassador-config -``` - -With `AMBASSADOR_CONFIG_BASE_DIR` set as above, $productName$ will create and use the directory `/tmp/ambassador-config` for its generated data. (Note that, while the directory will be created if it does not exist, attempts to turn an existing file into a directory will fail.) - -## Running as DaemonSet - -$productName$ can be deployed as a DaemonSet to have one pod per node in a Kubernetes cluster. This setup is especially helpful when you have a Kubernetes cluster running on a private cloud. - -* In an ideal example scenario, you are running containers on Kubernetes alongside with your non-containerized applications running exposed via VIP using BIG-IP or similar products. In such cases, east-west traffic is routed based on iRules to certain a set of application pools consisting of application or web servers. In this setup, alongside traditional application servers, two or more $productName$ pods can also be part of the application pools. In case of failure there is at least one $productName$ pod available to BIG-IP that can take care of routing traffic to the Kubernetes cluster. - -* In manifest files `kind: Deployment` needs to be updated to `kind: DaemonSet` and `replicas` should be removed in `spec` section. - -## Namespaces - -$productName$ supports multiple namespaces within Kubernetes. To make this work correctly, you need to set the `AMBASSADOR_NAMESPACE` environment variable in $productName$'s container. By far the easiest way to do this is using Kubernetes' downward API (this is included in the YAML files from `getambassador.io`): - -```yaml -env: -- name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace -``` - -Given that `AMBASSADOR_NAMESPACE` is set, $productName$ [`Mappings`](../../using/mappings) can operate within the same namespace, or across namespaces. **Note well** that `Mappings` will have to explicitly include the namespace with the service to cross namespaces; see the [`Mapping`](../../using/mappings) documentation for more information. - -If you want $productName$ to only work within a single namespace, set `AMBASSADOR_SINGLE_NAMESPACE` as an environment variable. - -```yaml -env: -- name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace -- name: AMBASSADOR_SINGLE_NAMESPACE - value: "true" -``` - -With $productName$, if you set `AMBASSADOR_NAMESPACE` or `AMBASSADOR_SINGLE_NAMESPACE`, set it in the deployment container. - -If you want to set a certificate for your `TLScontext` from another namespace, you can use the following: - -```yaml -env: -- name: AMBASSADOR_SINGLE_NAMESPACE - value: "YES" -- name: AMBASSADOR_CERTS_SINGLE_NAMESPACE - value: "YES" -- name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - apiVersion: v1 - fieldPath: metadata.namespace -``` - -## `AMBASSADOR_ID` - -$productName$ supports running multiple $productNamePlural$ in the same cluster, without restricting a given $productName$ to a single namespace. This is done with the `AMBASSADOR_ID` setting. In the `ambassador Module`, set the `ambassador_id`, e.g., - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - ambassador_id: [ "ambassador-1" ] - config: - ... -``` - -Then, assign each $productName$ pod a unique `AMBASSADOR_ID` with the environment variable as part of your deployment: - -```yaml -env: -- name: AMBASSADOR_ID - value: ambassador-1 -``` - -With $productName$, if you set `AMBASSADOR_ID`, you will need to set it in the deployment container. - -$productName$ will then only use YAML objects that include an appropriate `ambassador_id` attribute. For example, if $productName$ is given the ID `ambassador-1` as above, only the first two YAML objects below will be used: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-used -spec: - ambassador_id: [ "ambassador-1" ] - prefix: /demo1/ - service: demo1 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-used-2 -spec: - ambassador_id: [ "ambassador-1", "ambassador-2" ] - prefix: /demo2/ - service: demo2 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-skipped -spec: - prefix: /demo3/ - service: demo3 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-skipped-2 -spec: - ambassador_id: [ "ambassador-2" ] - prefix: /demo4/ - service: demo4 -``` - -`ambassador_id` is always a list, and may (as shown in `mapping-used-2` above) include multiple IDs to allow a given object in the configuration for multiple $productName$ instances. In this case, `mapping-used-2` will be included in the configuration for `ambassador-1` and also for `ambassador-2`. - -**Note well that _any_ $productName$ configuration resource can have an `ambassador_id` included** so, for example, it is _fully supported_ to use `ambassador_id` to qualify the `ambassador Module`, `TLSContext`, and `AuthService` objects. You will need to set `ambassador_id` in all resources you want to use for $productName$. - -If no `AMBASSADOR_ID` is assigned to an $productName$, it will use the ID `default`. If no `ambassador_id` is present in a YAML object, it will also use the ID `default`. - -## `AMBASSADOR_ENVOY_BASE_ID` - -$productName$ supports running side-by-side with other envoy-based projects in a single pod. An example of this is running with an `istio` sidecar. This is done with the `AMBASSADOR_ENVOY_BASE_ID` environment variable as part of your deployment: - -```yaml -env: -- name: AMBASSADOR_ENVOY_BASE_ID - value: 1 -``` - -If no `AMBASSADOR_ENVOY_BASE_ID` is provided then it will use the ID `0`. For more information on the Envoy base-id option please see the [Envoy command line documentation](https://www.envoyproxy.io/docs/envoy/latest/operations/cli.html?highlight=base%20id#cmdoption-base-id). - -## `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. - -## `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. - -## `AMBASSADOR_LEGACY_MODE` - -Setting `AMBASSADOR_LEGACY_MODE` to `true` will result in $productName$ disabling certain features -and reverting to older codepaths which may be better preserve certain older behaviors. Legacy mode -currently has the following effects: - -- $productName$ will switch back to the $productName$ 1.6 input-resource validator (which can significantly -increase configuration latency for $productName$ installations with many resources). -- $productName$ will use the shell boot sequence that was the default up through 1.9.1, rather than the Golang boot sequence that became the default in 1.10.0. -- `AMBASSADOR_FAST_RECONFIGURE` (see below) is not supported in legacy mode. - -## `AMBASSADOR_FAST_RECONFIGURE` - -Setting `AMBASSADOR_FAST_RECONFIGURE` to "true" enables incremental reconfiguration. When enabled, $productName$ will track deltas from one configuration to the next and recalculate only what is necessary to follow the change. When disabled (the default), $productName$ will recompute the entire configuration at every change. - -**`AMBASSADOR_FAST_RECONFIGURE` is not supported when `AMBASSADOR_LEGACY_MODE` is active.** - -## Configuration from the filesystem - -If desired, $productName$ can be configured from YAML files in the directory `$AMBASSADOR_CONFIG_BASE_DIR/ambassador-config` (by default, `/ambassador/ambassador-config`, which is empty in the images built by Datawire). You could volume mount an external configuration directory here, for example, or use a custom Dockerfile to build configuration directly into a Docker image. - -Note well that while $productName$ will read its initial configuration from this directory, configuration loaded from Kubernetes annotations will _replace_ this initial configuration. If this is not what you want, you will need to set the environment variable `AMBASSADOR_NO_KUBEWATCH` so that $productName$ will not try to update its configuration from Kubernetes resources. - -Also note that the YAML files in the configuration directory must contain the $productName$ resources, not Kubernetes resources with annotations. - -## Log levels and debugging - -The $OSSproductName$ and $AESproductName$ support more verbose debugging levels. If using $OSSproductName$, the [diagnostics](../diagnostics) service has a button to enable debug logging. Be aware that if you're running $productName$ on multiple pods, the debug log levels are not enabled for all pods -- they are configured on a per-pod basis. - -If using $AESproductName$, you can 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 format - -By default, $productName$ writes its own logs in a plain text format. To produce logs as JSON instead, set the `AMBASSADOR_JSON_LOGGING` environment variable: - -```yaml -env: -- name: AMBASSADOR_JSON_LOGGING - value: "true" -``` - -## Port assignments - -$productName$ uses some TCP ports in the range 8000-8499 internally, as well as port 8877. Third-party software integrating with $productName$ should not use ports in this range on the $productName$ pod. - -## $productName$ update checks (Scout) - -$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 $productName$ will run regardless of the status of Scout (i.e., our uptime has zero impact on your uptime.) - -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. - -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. - -Unless disabled, $productName$ will also report the following anonymized information back to Datawire: - -| Attribute | Type | Description | -| :------------------------ | :---- | :------------------------ | -| `cluster_count` | int | total count of clusters in use | -| `cluster_grpc_count` | int | count of clusters using GRPC upstream | -| `cluster_http_count` | int | count of clusters using HTTP or HTTPS upstream | -| `cluster_routing_envoy_rh_count` | int | count of clusters routing using Envoy `ring_hash` | -| `cluster_routing_envoy_maglev_count` | int | count of clusters routing using Envoy `maglev` | -| `cluster_routing_envoy_lr_count` | int | count of clusters routing using Envoy `least_request` | -| `cluster_routing_envoy_rr_count` | int | count of clusters routing using Envoy `round_robin` | -| `cluster_routing_kube_count` | int | count of clusters routing using Kubernetes | -| `cluster_tls_count` | int | count of clusters originating TLS | -| `custom_ambassador_id` | bool | has the `ambassador_id` been changed from 'default'? | -| `custom_listener_port` | bool | has the listener port been changed from 80/443? | -| `diagnostics` | bool | is the diagnostics service enabled? | -| `endpoint_grpc_count` | int | count of endpoints to which $productName$ will originate GRPC | -| `endpoint_http_count` | int | count of endpoints to which $productName$ will originate HTTP or HTTPS | -| `endpoint_routing` | bool | is endpoint routing enabled? | -| `endpoint_routing_envoy_rh_count` | int | count of endpoints being routed using Envoy `ring_hash` | -| `endpoint_routing_envoy_maglev_count` | int | count of endpoints being routed using Envoy `maglev` | -| `endpoint_routing_envoy_lr_count` | int | count of endpoints being routed using Envoy `least_request` | -| `endpoint_routing_envoy_rr_count` | int | count of endpoints being routed using Envoy `round_robin` | -| `endpoint_routing_kube_count` | int | count of endpoints being routed using Kubernetes | -| `endpoint_tls_count` | int | count of endpoints to which $productName$ will originate TLS | -| `extauth` | bool | is extauth enabled? | -| `extauth_allow_body` | bool | will $productName$ send the body to extauth? | -| `extauth_host_count` | int | count of extauth hosts in use | -| `extauth_proto` | str | extauth protocol in use ('http', 'grpc', or `null` if not active) | -| `group_canary_count` | int | count of Mapping groups that include more than one Mapping | -| `group_count` | int | total count of Mapping groups in use (length of the route table) | -| `group_header_match_count` | int | count of groups using header matching (including `host` and `method`) | -| `group_host_redirect_count` | int | count of groups using host_redirect | -| `group_host_rewrite_count` | int | count of groups using host_rewrite | -| `group_http_count` | int | count of HTTP Mapping groups | -| `group_precedence_count` | int | count of groups that explicitly set the precedence of the group | -| `group_regex_header_count` | int | count of groups using regex header matching | -| `group_regex_prefix_count` | int | count of groups using regex prefix matching | -| `group_resolver_consul` | int | count of groups using the Consul resolver | -| `group_resolver_kube_endpoint` | int | count of groups using the Kubernetes endpoint resolver | -| `group_resolver_kube_service` | int | count of groups using the Kubernetes service resolver | -| `group_shadow_count` | int | count of groups using shadows | -| `group_shadow_weighted_count` | int | count of groups using shadows but not shadowing all traffic | -| `group_tcp_count` | int | count of TCP Mapping groups | -| `host_count` | int | count of Host resources in use | -| `k8s_ingress_class_count` | int | count of IngressClass resources in use | -| `k8s_ingress_count` | int | count of Ingress resources in use | -| `listener_count` | int | count of active listeners (1 unless `redirect_cleartext_from` or TCP Mappings are in use) | -| `liveness_probe` | bool | are liveness probes enabled? | -| `managed_by` | string | tool that manages the $productName$ deployment, if any (e.g. helm, edgectl, etc.) | -| `mapping_count` | int | count of Mapping resources in use | -| `ratelimit` | bool | is rate limiting in use? | -| `ratelimit_custom_domain` | bool | has the rate limiting domain been changed from 'ambassador'? | -| `ratelimit_data_plane_proto` | bool | is rate limiting using the data plane proto? | -| `readiness_probe` | bool | are readiness probes enabled? | -| `request_4xx_count` | int | lower bound for how many requests have gotten a 4xx response | -| `request_5xx_count` | int | lower bound for how many requests have gotten a 5xx response | -| `request_bad_count` | int | lower bound for how many requests have failed (either 4xx or 5xx) | -| `request_elapsed` | float | seconds over which the request_ counts are valid | -| `request_hr_elapsed` | string | human-readable version of `request_elapsed` (e.g. "3 hours 35 minutes 20 seconds" | -| `request_ok_count` | int | lower bound for how many requests have succeeded (not a 4xx or 5xx) | -| `request_total_count` | int | lower bound for how many requests were handled in total | -| `statsd` | bool | is StatsD enabled? | -| `server_name` | bool | is the `server_name` response header overridden? | -| `service_resource_total` | int | total count of service resources loaded from all discovery sources | -| `tls_origination_count` | int | count of TLS origination contexts | -| `tls_termination_count` | int | count of TLS termination contexts | -| `tls_using_contexts` | bool | are new TLSContext resources in use? ? | -| `tls_using_module` | bool |is the old TLS module in use | -| `tracing` | bool | is tracing in use? | -| `tracing_driver` | str | tracing driver in use ('zipkin', 'lightstep', 'datadog', or `null` if not active) | -| `use_proxy_proto` | bool | is the `PROXY` protocol in use? | -| `use_remote_address` | bool | is $productName$ honoring remote addresses? | -| `x_forwarded_proto_redirect` | bool | is $productName$ redirecting based on `X-Forwarded-Proto`? | -| `xff_num_trusted_hops` | int | what is the count of trusted hops for `X-Forwarded-For`? | - -The `request_*` counts are always incremental: they contain only information about the last `request_elapsed` seconds. Additionally, they only provide a lower bound -- notably, if an $productName$ pod crashes or exits, no effort is made to ship out a final update, so it's very easy for counts to never be reported. - -To completely disable feature reporting, set the environment variable `AMBASSADOR_DISABLE_FEATURES` to any non-empty value. diff --git a/content/en/docs/3.3/topics/running/scaling.md b/content/en/docs/3.3/topics/running/scaling.md deleted file mode 100644 index 22fa743e..00000000 --- a/content/en/docs/3.3/topics/running/scaling.md +++ /dev/null @@ -1,194 +0,0 @@ -# Performance and scaling $productName$ - -Scaling any cloud native application is inherently domain specific, however the content here -reflects common issues, tips, and tricks that come up frequently. - -## Performance dimensions - -The performance of $productName$'s control plane can be characterized along a number of -different dimensions: - - - The number of `TLSContext` resources. - - The number of `Host` resources. - - The number of `Mapping` resources per `Host` resource. - - The number of `Mapping` resources that will span all `Host` resources (either because they're using `host_regex`, or because they're using `hostname: "*"`). - -If your application involves a larger than average number of any of the above resources, you may -find yourself in need of some of the content in this section. - -## Mysterious pod restarts (aka pushing the edge of the envelope) - -Whether your application is growing organically or whether you are deliberately scale testing, it's -helpful to recognize how $productName$ behaves as it reaches the edge of its performance -envelope along any of these dimensions. - -As $productName$ approaches the edge of its performance envelope, it will often manifest as -mysterious pod restarts triggered by Kubernetes. This does not always mean there is a problem, it -could just mean you need to tune some of the resource limits set in your deployment. When it comes -to scaling, Kubernetes will generally kill an $productName$ pod for one of two reasons: exceeding -memory limits or failed liveness/readiness probes. See the [Memory Limits](#memory-limits), -[Liveness Probes](#liveness-probes), and [Readiness Probes](#readiness-probes) -sections for more on how to cope with these situations. - -## Memory limits - -$productName$ can grow in memory usage and be killed by Kubernetes if it exceeds the limits -defined in its pod spec. When this happens it is confusing and difficult to catch because the only -indication that this has occurred is the pod transitioning momentarily into the `OOMKilled` -state. The only way to actually observe this is if you are lucky enough to be running the following -command (or have similar monitoring configured) when $productName$ gets `OOMKilled`: - -``` - kubectl get pods -n ambassador -w -``` - -In order to take the luck out of the equation, $productName$ will periodically log its -memory usage so you can see in the logs if memory limits might be a problem and require adjustment: - -``` -2020/11/26 22:35:20 Memory Usage 0.56Gi (28%) - PID 1, 0.22Gi: busyambassador entrypoint - PID 14, 0.04Gi: /usr/bin/python /usr/bin/diagd /ambassador/snapshots /ambassador/bootstrap-ads.json /ambassador/envoy/envoy.json --notices /ambassador/notices.json --port 8004 --kick kill -HUP 1 - PID 16, 0.12Gi: /ambassador/sidecars/amb-sidecar - PID 37, 0.07Gi: /usr/bin/python /usr/bin/diagd /ambassador/snapshots /ambassador/bootstrap-ads.json /ambassador/envoy/envoy.json --notices /ambassador/notices.json --port 8004 --kick kill -HUP 1 - PID 48, 0.08Gi: envoy -c /ambassador/bootstrap-ads.json --base-id 0 --drain-time-s 600 -l error -``` - -In general you should try to keep $productName$'s memory usage below 50% of the pod's limit. This may -seem like a generous safety margin, but when reconfiguration occurs, $productName$ requires additional -memory to avoid disrupting active connections. At each reconfiguration, $productName$ keeps around the -old version for the duration of the configured drain time. See -[AMBASSADOR_DRAIN_TIME](#ambassador_drain_time) for more details on how to tune this -behavior. - -$productName$'s exact memory usage depends on (among other things) how many `Host` and -`Mapping` resources are defined in your cluster. If this number has grown over time, you may need to -increase the memory limit defined in your deployment. - -## Liveness probes - -$productName$ defines the `/ambassador/v0/check_alive` endpoint on port `8877` for use with Kubernetes -liveness probes. See the Kubernetes documentation for more details on [HTTP liveness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-a-liveness-http-request). - -Kubernetes will restart the $productName$ pod if it fails to get a 200 result from the endpoint. If -this happens it won't necessarily show up in an easily recognizable way in the pod logs. You can -look for Kubernetes events to see if this is happening. Use `kubectl describe pod -n ambassador` or -`kubectl get events -n ambassador` or equivalent. - -The purpose of liveness probes is to rescue an $productName$ instance that is wedged, however if -liveness probes are too sensitive they can take out $productName$ instances that are functioning -normally. This is more prone to happen as the number of $productName$ inputs increase. The -`timeoutSeconds` and `failureThreshold` fields of the $productName$ deployment's liveness Probe -determines how tolerant Kubernetes is with its probes. If you observe pod restarts along with -`Unhealthy` events, try tuning these fields upwards from their default values. See the Kubernetes documentation for more details on [tuning probes](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#probe-v1-core). - -Note that whatever changes you make to $productName$'s liveness probes should most likely be made to -its readiness probes also. - -## Readiness probes - -$productName$ defines the `/ambassador/v0/check_ready` endpoint on port `8877` for use with Kubernetes -readiness probes. See the Kubernetes documentation for more details on [readiness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-readiness-probes). - -Kubernetes uses readiness checks to prevent traffic from going to pods that are not ready to handle -requests. The only time $productName$ cannot usefully handle requests is during initial startup when it -has not yet loaded all the routing information from Kubernetes and/or consul. During this bootstrap -period there is no guarantee $productName$ would know where to send a given request. The `check_ready` -endpoint will only return 200 when all routing information has been loaded. After the initial -bootstrap period it behaves identically to the `check_alive` endpoint. - -Generally $productName$'s readiness probes should be configured with the same settings as its liveness -probes. - -## `AMBASSADOR_FAST_RECONFIGURE` and `AMBASSADOR_LEGACY_MODE` flags - -`AMBASSADOR_FAST_RECONFIGURE` is a feature flag that enables a higher performance implementation of -the code $productName$ uses to validate and generate envoy configuration. It will eventually be enabled -by default, but if you are experiencing performance problems you should try setting -`AMBASSADOR_FAST_RECONFIGURE` to `true` to see if this helps. - -`AMBASSADOR_LEGACY_MODE` is **not** recommended when performance is critical. - -## `AMBASSADOR_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. - -## Unconstrained Mappings with many hosts - -When working with a large number of `Host` resources, it's important to understand the impact of -unconstrained `Mapping`s. An unconstrained `Mapping` is one that is not restricted to a specific -`Host`. Such a `Mapping` will create a route for all of your `Host`s. If this is what you want then -it is the appropriate thing to do, however if you do not intend to do this, then you can end up with -many more routes than you had intended and this can adversely impact performance. - -## Inspecting $productName$ performance - -$productName$ internally tracks a number of key performance indicators. You can inspect these via the -debug endpoint at `localhost:8877/debug`. Note that the `AMBASSADOR_FAST_RECONFIGURE` flag needs to -be set to `"true"` for this endpoint to be present: - -``` -$ kubectl exec -n ambassador -it ${POD} curl localhost:8877/debug -{ - "timers": { - # These two timers track how long it takes to respond to liveness and readiness probes. - "check_alive": "7, 45.411495ms/61.85999ms/81.358927ms", - "check_ready": "7, 49.951304ms/61.976205ms/86.279038ms", - - # These two timers track how long we spend updating our in-memory snapshot when our Kubernetes - # watches tell us something has changed. - "consulUpdate": "0, 0s/0s/0s", - "katesUpdate": "3382, 28.662µs/102.784µs/95.220222ms", - - # These timers tell us how long we spend notifying the sidecars if changed input. This - # includes how long the sidecars take to process that input. - "notifyWebhook:diagd": "2, 1.206967947s/1.3298432s/1.452718454s", - "notifyWebhooks": "2, 1.207007216s/1.329901037s/1.452794859s", - - # This timer tells us how long we spend parsing annotations. - "parseAnnotations": "2, 21.944µs/22.541µs/23.138µs", - - # This timer tells us how long we spend reconciling changes to consul inputs. - "reconcileConsul": "2, 50.104µs/55.499µs/60.894µs", - - # This timer tells us how long we spend reconciling secrets related changes to $productName$ - # inputs. - "reconcileSecrets": "2, 18.704µs/20.786µs/22.868µs" - }, - "values": { - "envoyReconfigs": { - "times": [ - "2020-11-06T13:13:24.218707995-05:00", - "2020-11-06T13:13:27.185754494-05:00", - "2020-11-06T13:13:28.612279777-05:00" - ], - "staleCount": 2, - "staleMax": 0, - "synced": true - }, - "memory": "39.73Gi of Unlimited (0%)" - } -} -``` - -## Running profiles - -$productName$ exposes endpoints at `localhost:8877/debug/pprof` to run Golang profiles to aid in live debugging. The endpoints are equivalent to those found in the [http/pprof](https://pkg.go.dev/net/http/pprof) package. `/debug/pprof/` returns an HTML page listing the available profiles. - -The following are the different types of profiles you can run: - -| Profile | Function | -| :------- | :-------- | -| /debug/pprof/allocs | Returns a sampling of all past memory allocations. | -| /debug/pprof/block | Returns stack traces of goroutines that led to blocking on sychronization primitives. | -| /debug/pprof/cmdline | Returns the command line that was invoked by the current program. | -| /debug/pprof/goroutine | Returns stack traces of all current goroutines. | -| /debug/pprof/heap | Returns a sampling of memory allocations of live objects. | -| /debug/pprof/mutex | Returns stack traces of goroutines holding contended mutexes. | -| /debug/pprof/profile | Returns pprof-formatted cpu profile. You can specify the duration using the seconds `GET` parameter. The default duration is 30 seconds. | -| /debug/pprof/symbol | Returns the program counters listed in the request. | -| /debug/pprof/threadcreate | Returns stack traces that led to creation of new OS threads. | -| /debug/pprof/trace | Returns the execution trace in binary form. You can specify the duration using the seconds `GET` parameter. The default duration is 1 second. | diff --git a/content/en/docs/3.3/topics/running/services/auth-service.md b/content/en/docs/3.3/topics/running/services/auth-service.md deleted file mode 100644 index adfb77e4..00000000 --- a/content/en/docs/3.3/topics/running/services/auth-service.md +++ /dev/null @@ -1,150 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Authentication service - -$productName$ provides a highly flexible mechanism for authentication, -via the `AuthService` resource. An `AuthService` configures -$productName$ to use an external service to check authentication and -authorization for incoming requests. Each incoming request is -authenticated before routing to its destination. - -All requests are validated by the `AuthService` (unless the `Mapping` -applied to the request sets `bypass_auth`). It is not possible to -combine multiple `AuthServices`. While it is possible to create -multiple `AuthService` resources, $productName$ load-balances between -them in a round-robin fashion. This is useful for canarying an -`AuthService` change, but is not useful for deploying multiple -distinct `AuthServices`. In order to combine multiple external -services (either having multiple services apply to the same request, -or selecting between different services for the different requests), -instead of using an `AuthService`, use an [$AESproductName$ `External` -`Filter`](/docs/edge-stack/latest/topics/using/filters/). - - - -Because of the limitations described above, **$AESproductName$ does -not support `AuthService` resources, and you should instead use an -[`External` -`Filter`](/docs/edge-stack/latest/topics/using/filters/external),** -which is mostly a drop-in replacement for an `AuthService`. The -`External` `Filter` relies on the $AESproductName$ `AuthService`. -Make sure the $AESproductName$ `AuthService` is deployed before -configuring `External` `Filters`. - - - -The currently supported version of the `AuthService` resource is -`getambassador.io/v3alpha1`. Earlier versions are deprecated. - -## Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: AuthService -metadata: - name: authentication -spec: - ambassador_id: [ "ambassador-1" ] - auth_service: "example-auth.authentication:3000" - tls: true - proto: http - timeout_ms: 5000 - include_body: - max_bytes: 4096 - allow_partial: true - status_on_error: - code: 403 - failure_mode_allow: false - - # proto: grpc only, default is v2. If upgrading from 2.x then you must set this to v3. - protocol_version: v3 - - # proto: http only - path_prefix: "/path" - allowed_request_headers: - - "x-example-header" - allowed_authorization_headers: - - "x-qotm-session" - add_auth_headers: - x-added-auth: auth-added - add_linkerd_headers: false -``` - -## Fields - -`auth_service` is the only required field, all others are optional. - -| Attribute | Default value | Description | -| ---------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `ambassador_id` | `[ "default" ]` | Which [Ambassador ID](../../running/#ambassador_id) the `AuthService` should apply to. | -| `auth_service` | (none; a value is required) | Identifies the external auth service to talk to. The format of this field is `scheme://host:port` where `scheme://` and `:port` are optional. The scheme-part, if present, must be either `http://` or `https://`; if the scheme-part is not present, it behaves as if `http://` is given. The scheme-part controls whether TLS or plaintext is used and influences the default value of the port-part. The host-part must be the [namespace-qualified DNS name](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#namespaces-of-services) of the service you want to use for authentication. | -| `tls` | `""` | This field is populated with the name of the defined TLSContext, which determines the TLS certificate presented to external auth services. | -| `proto` | `http` | Specifies which variant of the [`ext_authz` protocol](../ext-authz/) to use when communicating with the external auth service. Valid options are `http` or `grpc`. | -| `timeout_ms` | `5000` | The total maximum duration in milliseconds for the request to the external auth service, before triggering `status_on_error` or `failure_mode_allow`. | -| `include_body` | `null` | Controls how much to buffer the request body to pass to the external auth service, for use cases such as computing an HMAC or request signature. If `include_body` is `null` or unset, then the request body is not buffered at all, and an empty body is passed to the external auth service. If `include_body` is not `null`, the `max_bytes` and `allow_partial` subfields are required. | -| `include_body.max_bytes` | (none; a value is required if `include_body` is not `null`) | Controls the amount of body data that is passed to the external auth service. | -| `include_body.allow_partial` | (none; a value is required if `include_body` is not `null`) | Controls what happens to requests with bodies larger than `max_bytes`. If `allow_partial` is `true`, the first `max_bytes` of the body are sent to the external auth service. If `false`, the message is rejected with HTTP 413 ("Payload Too Large"). | -| `status_on_error.code` | `403` | Controls the status code returned when unable to communicate with external auth service. This is ignored if `failure_mode_allow: true`. | -| `failure_mode_allow` | `false` | Controls whether to allow or reject requests when there is an error communicating with the external auth service; a value of `true` allows the request through to the upstream backend service, a value of `false` returns a `status_on_error.code` response to the client. | -| `stats_name` | the `auth_service` value with non-alphanumeric characters replaced with underscores | See [Overriding Statistics Names](../../statistics/#overriding-statistics-names). | -| `circuit_breakers` | the value set in the [`ambassador` `Module`](../../../using/defaults) | See [Circuit Breakers](../../../using/circuit-breakers/). | - -The following field is only used if `proto` is set to `grpc`. It is -ignored if `proto` is `http`. - -| Attribute | Default value | Description | -| ------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `protocol_version` | `v3` | Allowed values are `v3` and `v2`(defualt). `protocol_version` was used in previous versions of $productName$ to control the protocol used by the gRPC service. $productName$ 3.x is running an updated version of Envoy that has dropped support for the `v2` protocol, so starting in 3.x, if `protocol_version` is not specified, 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. | - -The following fields are only used if `proto` is set to `http`. They -are ignored if `proto` is `grpc`. - -| Attribute | Default value | Description | -| ------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `path_prefix` | `""` | Prepends a string to the request path of the request when sending it to the external auth service. By default this is empty, and nothing is prepended. For example, if the client makes a request to `/foo`, and `path_prefix: /bar`, then the path in the request made to the external auth service will be `/foo/bar`. | -| `allowed_request_headers` | `[]` | Lists the headers (case-insensitive) that are copied from the incoming request to the request made to the external auth service. In addition to the headers listed in this field, the following headers are always included: `Authorization`, `Cookie`, `From`, `Proxy-Authorization`, `User-Agent`, `X-Forwarded-For`, `X-Forwarded-Host`, and `X-Forwarded-Proto`. | -| `allowed_authorization_headers` | `[]` | Lists the headers (case-insensitive) that are copied from the response from the external auth service to the request sent to the upstream backend service (if the external auth service indicates that the request to the upstream backend service should be allowed). In addition to the headers listed in this field, the following headers are always included: `Authorization`, `Location`, `Proxy-Authenticate`, `Set-cookie`, `WWW-Authenticate` | -| `add_auth_headers` | `{}` | A dictionary of `header: value` pairs that are added to the request made to the external auth service. | -| `add_linkerd_headers` | Defaults to the value set in the [`ambassador` `Module`](../../ambassador) | When true, in the request to the external auth service, adds an `l5d-dst-override` HTTP header that is set to the hostname and port number of the external auth service. | - -## Canarying multiple `AuthServices` - -You may create multiple `AuthService` manifests to round-robin -authentication requests among multiple services. **All services must -use the same `path_prefix` and header definitions.** If you try to -have different values, you'll see an error in the [diagnostics -service](../../ambassador/#diagnostics), telling you which value is -being used. - -## Configuring public `Mappings` - -An `AuthService` can be disabled for a `Mapping` by setting -`bypass_auth` to `true`. This will tell $productName$ to allow all -requests for that `Mapping` through without interacting with the -external auth service. - - - -## Transport Protocol Migration - - -> **Note:** The following information is only applicable to `AuthServices` using `proto: grpc` -As of $productName$ version 2.3, the `v2` transport protocol is deprecated and any AuthServices making use -of it should migrate to `v3` before support for `v2` is removed in a future release. - -The following imports simply need to be updated to migrate an AuthService - -`v2` Imports: -``` - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" -``` - -`v3` Imports: -``` - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" -``` diff --git a/content/en/docs/3.3/topics/running/services/ext-authz.md b/content/en/docs/3.3/topics/running/services/ext-authz.md deleted file mode 100644 index d850ba4b..00000000 --- a/content/en/docs/3.3/topics/running/services/ext-authz.md +++ /dev/null @@ -1,83 +0,0 @@ -# ExtAuth protocol - -By design, the ExtAuth protocol used by [the AuthService](../auth-service) and by [External Filters](/docs/edge-stack/latest/topics/using/filters/external) is highly flexible. The authentication service is the first external service invoked on an incoming request (e.g., it runs before the rate limit filter). Because the logic of authentication is encapsulated in an external service, you can use this to support a wide variety of use cases. For example: - -* Supporting traditional SSO authentication protocols, e.g., OAuth, OpenID Connect, etc. -* Supporting HTTP basic authentication ([see a sample implementation](https://github.com/datawire/ambassador-auth-httpbasic)). -* Only authenticating requests that are under a rate limit and rejecting authentication requests above the rate limit. -* Authenticating specific services (URLs), and not others. - -For each request, the ExtAuth service may either: - 1. return a direct HTTP *response*, intended to be sent back to the requesting HTTP client (normally *denying* the request from being forwarded to the upstream backend service) or - 2. return a modification to make to the HTTP *request* before sending it to the upstream backend service (normally *allowing* the request to be forwarded to the upstream backend service with modifications). - -The ExtAuth service receives information about every request through $productName$ and must indicate whether the request is to be allowed or not. If not, the ExtAuth service provides the HTTP response which is to be handed back to the client. A potential control flow for Authentication is shown in the image below. - -Giving the ExtAuth service the ability to control the response allows many different types of auth mechanisms, for example: - -- The ExtAuth service can simply return an error page with an HTTP 401 response. -- The ExtAuth service can choose to include a `WWW-Authenticate` header in the 401 response, to ask the client to perform HTTP Basic Auth. -- The ExtAuth service can issue a 301 `Redirect` to divert the client into an OAuth or OIDC authentication sequence. The control flow of this is shown below. ![Authentication flow](../../../images/auth-flow.png) - -There are two variants of the ExtAuth: gRPC and plain HTTP. - -### The gRPC protocol - -When `proto: grpc` is set, the ExtAuth service must implement the `Authorization` gRPC interface, defined in [Envoy's `external_auth.proto`](https://github.com/emissary-ingress/emissary/blob/master/api/envoy/service/auth/v3/external_auth.proto). - -### The HTTP protocol - -External services for `proto: http` are often easier to implement, but have several limitations compared to `proto: grpc`. - - The list of headers that the ExtAuth service is interested in reading must be known ahead of time, in order to set `allow_request_headers`. Inspecting headers that are not known ahead of time requires instead using `proto: grpc`. - - The list of headers that the ExtAuth service would like to set or modify must be known ahead of time, in order to set `allow_authorization_headers`. Setting headers that are not known ahead of time requires instead using `proto: grpc`. - - When returning a direct HTTP response, the HTTP status code cannot be 200 or in the 5XX range. Intercepting with a 200 or 5XX response requires instead using `proto: grpc`. - -#### The request From $productName$ to the ExtAuth service - -For every incoming request, a similar request is made to the ExtAuth service that mimics the: - - HTTP request method - - HTTP request path, potentially modified by `path_prefix` - - HTTP request headers that are either named in `allowed_request_headers` or in the fixed list of headers that are always included - - first `include_body.max_bytes` of the HTTP request body. - -The `Content-Length` HTTP header is set to the number of bytes in the body of the request sent to the ExtAuth service (`0` if `include_body` is not set). - -**ALL** request methods will be proxied, which implies that the ExtAuth service must be able to handle any request that any client could make. - -Take this incoming request for example: - -``` -PUT /path/to/service HTTP/1.1 -Host: myservice.example.com:8080 -User-Agent: curl/7.54.0 -Accept: */* -Content-Type: application/json -Content-Length: 27 - -{ "greeting": "hello world!", "spiders": "OMG no" } -``` - -The request $productName$ will make of the auth service is: - -``` -PUT /path/to/service HTTP/1.1 -Host: extauth.example.com:8080 -User-Agent: curl/7.54.0 -Accept: */* -Content-Type: application/json -Content-Length: 0 -``` - -#### The response returned from the ExtAuth service to $productName$ - - - If the HTTP response returned from the ExtAuth service to $productName$ has an HTTP status code of 200, then the request is allowed through to the upstream backend service. **Only** 200 indicates this; other 2XX status codes will prevent the request from being allowed through. - - The 200 response should not contain anything in the body, but may contain arbitrary headers. Any header present in the ExtAuth service' response that is also either listed in the `allow_authorization_headers` attribute of the AuthService resource or in the fixed list of headers that are always included will be copied from the ExtAuth service's response into the request going to the upstream backend service. This allows the ExtAuth service to inject tokens or other information into the request, or to modify headers coming from the client. - - The big limitation here is that the list of headers to be set must be known ahead of time, in order to set `allow_request_headers`. Setting headers that are not known ahead of time requires instead using `proto: grpc`. - - - If $productName$ cannot reach the ExtAuth service at all, if the ExtAuth service does not return a valid HTTP response, or if the HTTP response has an HTTP status code in the 5XX range, then the communication with the ExtAuth service is considered to have failed, and the `status_on_error` or `failure_mode_allow` behavior is triggered. - - - Any HTTP status code other than 200 or 5XX from the ExtAuth service tells $productName$ to **not** allow the request to continue to the upstream backend service, but that the ExtAuth service is instead intercepting the request. The entire HTTP response from the ExtAuth service--including the status code, the headers, and the body--is handed back to the client verbatim. This gives the ExtAuth service **complete** control over the entire response presented to the client. - - The big limitation here is that you cannot directly return a 200 or 5XX response. Intercepting with a 200 of 5XX response requires instead using `proto: grpc`. diff --git a/content/en/docs/3.3/topics/running/services/index.md b/content/en/docs/3.3/topics/running/services/index.md deleted file mode 100644 index 1646aa5a..00000000 --- a/content/en/docs/3.3/topics/running/services/index.md +++ /dev/null @@ -1,11 +0,0 @@ -# Available plugins - -You may need an API Gateway to enforce policies specific to your organization. $productName$ supports custom policies through external service plugins. The policy logic specific to your organization is implemented in the external service, and $productName$ is configured to send RPC requests to your service. - -Currently, $productName$ supports plugins for authentication, -access logging, rate limiting, and tracing. - -* [AuthService](auth-service) Plugin -* [LogService](log-service) Plugin -* [RateLimitService](rate-limit-service) Plugin -* [TracingService](tracing-service) Plugin diff --git a/content/en/docs/3.3/topics/running/services/log-service.md b/content/en/docs/3.3/topics/running/services/log-service.md deleted file mode 100644 index b3e90c7c..00000000 --- a/content/en/docs/3.3/topics/running/services/log-service.md +++ /dev/null @@ -1,116 +0,0 @@ -# Log service - -By default, $productName$ puts the access logs on stdout; such -that the can be read using `kubectl logs`. The format of those logs, -and the local destination of them, can be configured using the -[`envoy_log_` settings in the `ambassador -Module`](../../ambassador). However, the -options there only allow for logging local to $productName$'s Pod. By -configuring a `LogService`, you can configure $productName$ to -report its access logs to a remote service, in addition to the usual -`ambassador Module` configured logging. - -The remote access log service (or ALS) must implement the -`AccessLogService` gRPC interface, defined in [Envoy's `als.proto`][als.proto]. - -[als.proto]: https://github.com/emissary-ingress/emissary/blob/master/api/envoy/service/accesslog/v3/als.proto - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: LogService -metadata: - name: example-log-service -spec: - # Common to all $productName$ resources - ambassador_id: []string # optional; default is ["default"] - - # LogService specific - service: "string" # required - driver: "enum-string:[tcp, http]" # required - driver_config: # required - additional_log_headers: # optional; default is [] (only for `driver: http`) - - header_name: string # required - during_request: boolean # optional; default is true - during_response: boolean # optional; default is true - during_trailer: boolean # optional; default is true - flush_interval_time: int-seconds # optional; default is 1 - flush_interval_byte_size: integer # optional; default is 16384 - grpc: boolean # optional; default is false - protocol_version: enum # optional; default is v2 -``` - - - `service` is where to route the access log gRPC requests to - - - `driver` identifies which type of accesses to log; HTTP requests (`"http"`) or - TLS connections (`"tcp"`). - - - `driver_config` stores the configuration that is specific to the `driver`: - - * `driver: tcp` has no additional configuration; the config must - be set as `driver_config: {}`. - - * `driver: http` - - - `additional_log_headers` identifies HTTP headers to include in - the access log, and when in the logged-request's lifecycle to - include them. - - - `flush_interval_time` is the maximum number of seconds to buffer - accesses for before sending them to the ALS. The logs will be - flushed to the ALS every time this duration is reached, or when the - buffered data reaches `flush_interval_byte_size`, whichever comes - first. See the [Envoy documentation on - `buffer_flush_interval`][buffer_flush_interval] for more - information. - - - `flush_interval_byte_size` is a soft size limit for the access log - buffer. The logs will be flushed to the ALS every time the - buffered data reaches this size, or whenever `flush_interval_time` - elapses, whichever comes first. See the [Envoy documentation on - `buffer_size_bytes`][buffer_size_bytes] for more information. - - - `grpc` must be `true`. - -[buffer_flush_interval]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/access_loggers/grpc/v3/als.proto.html#extensions-access-loggers-grpc-v3-commongrpcaccesslogconfig -[buffer_size_bytes]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/access_loggers/grpc/v3/als.proto.html#extensions-access-loggers-grpc-v3-commongrpcaccesslogconfig - - - `protocol_version` was used in previous versions of $productName$ to control the gRPC service name used to communicate with the `LogService`. $productName$ 3.x is running an updated version of Envoy that has dropped support for the `v2` protocol, so starting in 3.x, if `protocol_version` is not specified, 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. - -## Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: LogService -metadata: - name: als -spec: - service: "als.default:3000" - driver: http - driver_config: {} # NB: driver_config must be set, even if it's empty - grpc: true # NB: grpc must be true and it will use the V3 transport protocol -``` - -## Transport Protocol Migration - - -> **Note:** The following information is only applicable to `AuthServices` using `proto: grpc` -As of $productName$ version 2.3, the `v2` transport protocol is deprecated and any AuthServices making use -of it should migrate to `v3` before support for `v2` is removed in a future release. - -The following imports simply need to be updated to migrate an AuthService - -`v2` Imports: -``` - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" -``` - -`v3` Imports: -``` - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" -``` diff --git a/content/en/docs/3.3/topics/running/services/rate-limit-service.md b/content/en/docs/3.3/topics/running/services/rate-limit-service.md deleted file mode 100644 index 39c2b0ce..00000000 --- a/content/en/docs/3.3/topics/running/services/rate-limit-service.md +++ /dev/null @@ -1,118 +0,0 @@ -# Rate limit service - -Rate limiting is a powerful technique to improve the [availability and -resilience of your -services](https://blog.getambassador.io/rate-limiting-a-useful-tool-with-distributed-systems-6be2b1a4f5f4). -In $productName$, each request can have one or more _labels_. These labels are -exposed to a third-party service via a gRPC API. The third-party service can -then rate limit requests based on the request labels. - -**Note that `RateLimitService` is only applicable to $OSSproductName$, -and not $AESproductName$, as $AESproductName$ includes a -built-in rate limit service.** - -## Request labels - -See [Attaching labels to -requests](../../../using/rate-limits#attaching-labels-to-requests) -for how to configure the labels that are attached to a request. - -## Domains - -In $productName$, each engineer (or team) can be assigned its own _domain_. A -domain is a separate namespace for labels. By creating individual domains, each -team can assign their own labels to a given request, and independently set the -rate limits based on their own labels. - -See [Attaching labels to -requests](../../../using/rate-limits/#attaching-labels-to-requests) -for how to labels under different domains. - -## External rate limit service - -In order for $productName$ to rate limit, you need to implement a -gRPC `RateLimitService`, as defined in [Envoy's `v3/rls.proto`] -interface. If you do not have the time or resources to implement your own rate -limit service, $AESproductName$ integrates a high-performance rate -limiting service. - -[envoy's `v3/rls.proto`]: https://github.com/emissary-ingress/emissary/tree/master/api/envoy/service/ratelimit/v3/rls.proto - -$productName$ generates a gRPC request to the external rate limit -service and provides a list of labels on which the rate limit service can base -its decision to accept or reject the request: - -``` -[ - {"source_cluster", ""}, - {"destination_cluster", ""}, - {"remote_address", ""}, - {"generic_key", ""}, - {"", ""} -] -``` - -If $productName$ cannot contact the rate limit service, it will -allow the request to be processed as if there were no rate limit service -configuration. - -It is the external rate limit service's responsibility to determine whether rate -limiting should take place, depending on custom business logic. The rate limit -service must simply respond to the request with an `OK` or `OVER_LIMIT` code: - -- If Envoy receives an `OK` response from the rate limit service, then $productName$ allows the client request to resume being processed by - the normal flow. -- If Envoy receives an `OVER_LIMIT` response, then $productName$ - will return an HTTP 429 response to the client and will end the transaction - flow, preventing the request from reaching the backing service. - -The headers injected by the [AuthService](../auth-service) can also be passed to -the rate limit service since the `AuthService` is invoked before the -`RateLimitService`. - -## Configuring the rate limit service - -A `RateLimitService` manifest configures $productName$ to use an -external service to check and enforce rate limits for incoming requests: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: RateLimitService -metadata: - name: ratelimit -spec: - service: 'example-rate-limit.default:5000' - protocol_version: # default is v2, if upgrading from 2.x then you must set this to v3. - failure_mode_deny: false # when set to true envoy will return 500 error when unable to communicate with RateLimitService -``` - -- `service` gives the URL of the rate limit service. If using a Kubernetes service, this should be the [namespace-qualified DNS name](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#namespaces-of-services) of that service. -- `protocol_version` Allowed values are `v3` and `v2`(default). `protocol_version` was used in previous versions of $productName$ to control the protocol used by the gRPC service to communicate with the `RateLimitService`. $productName$ 3.x is running an updated version of Envoy that has dropped support for the `v2` protocol, so starting in 3.x, if `protocol_version` is not specified, 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. -- `failure_mode_deny` By default, Envoy will fail open when unable to communicate with the service due to it becoming unvailable or due to timeouts. When this happens the upstream service that is being protected by a rate limit may be overloaded due to this behavior. When set to `true` Envoy will be configured to return a `500` status code when it is unable to communicate with the RateLimit service and will fail closed by rejecting request to the upstream service. - -You may only use a single `RateLimitService` manifest. - -## Rate limit service and TLS - -You can tell $productName$ to use TLS to talk to your service by -using a `RateLimitService` with an `https://` prefix. However, you may also -provide a `tls` attribute: if `tls` is present and `true`, $productName$ will originate TLS even if the `service` does not have the `https://` -prefix. - -If `tls` is present with a value that is not `true`, the value is assumed to be the name of a defined TLS context, which will determine the certificate presented to the upstream service. - -## Example - -The [$OSSproductName$ Rate Limiting -Tutorial](../../../../howtos/rate-limiting-tutorial) has a simple rate limiting -example. For a more advanced example, read the [advanced rate limiting -tutorial](../../../../../2.0/howtos/advanced-rate-limiting), which uses the rate limit -service that is integrated with $AESproductName$. - -## Further reading - -- [Rate limiting: a useful tool with distributed systems](https://blog.getambassador.io/rate-limiting-a-useful-tool-with-distributed-systems-6be2b1a4f5f4) -- [Rate limiting for API Gateways](https://blog.getambassador.io/rate-limiting-for-api-gateways-892310a2da02) -- [Implementing a Java Rate Limiting Service for $productName$](https://blog.getambassador.io/implementing-a-java-rate-limiting-service-for-the-ambassador-api-gateway-e09d542455da) -- [Designing a Rate Limit Service for $productName$](https://blog.getambassador.io/designing-a-rate-limiting-service-for-ambassador-f460e9fabedb) diff --git a/content/en/docs/3.3/topics/running/services/tracing-service.md b/content/en/docs/3.3/topics/running/services/tracing-service.md deleted file mode 100644 index 69f4551d..00000000 --- a/content/en/docs/3.3/topics/running/services/tracing-service.md +++ /dev/null @@ -1,119 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Tracing service - -Applications that consist of multiple services can be difficult to debug, as a single request can span multiple services. Distributed tracing tells the story of your request as it is processed through your system. Distributed tracing is a powerful tool to debug and analyze your system in addition to request logging and metrics. - -When enabled, the `TracingService` will instruct $productName$ to initiate a trace on requests by generating and populating an `x-request-id` HTTP header. Services can make use of this `x-request-id` header in logging and forward it in downstream requests for tracing. $productName$ also integrates with external trace visualization services, including [LightStep](https://lightstep.com/) and Zipkin-compatible APIs such as [Zipkin](https://zipkin.io/) and [Jaeger](https://github.com/jaegertracing/) to allow you to store and visualize traces. You can read further on [Envoy's Tracing capabilities](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/tracing). - -A `TracingService` manifest configures $productName$ to use an external trace visualization service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TracingService -metadata: - name: tracing -spec: - service: "example-zipkin:9411" - driver: zipkin - config: {} - custom_tags: # optional - - tag: host - request_header: - name: ":authority" - default_value: "unknown" - - tag: path - request_header: - name: ":path" - default_value: "unknown" - sampling: - overall: 100 -``` - -| Field | Description | values | -| --------- | ----------- | ------------- | -| `service` | gives the URL of the external HTTP trace service. | ex. `example-zipkin:9411` | -| `driver` | provides the driver information that handles communicating with the service | enum:
`lightstep`
`zipkin`
`datadog` | -| `config` | provides additional configuration options for the selected `driver`. Supported configuration for each driver is found below. | | -| `tag_headers` | **Deprecated** - it is recommend that you switch to using `custom_tags`| | -| `custom_tags` | configure tags to attach to traces. See section below for more details. | | -| `propagation_modes` | (optional) if present, specifies a list of the propogation modes to be used | enum:
`ENVOY`
`LIGHTSTEP`
`B3`
`TRACE_CONTEXT` | -| `sampling` | (optional) if present, specifies some target percentages of requests that will be traced. | | - -Please note that you must use the HTTP/2 pseudo-header names. For example: - -- the `host` header should be specified as the `:authority` header; and -- the `method` header should be specified as the `:method` header. - -## Sampling - -Configuring `sampling` will specify some target percentages of requests that will be traced. This is beneficial for high-volume services to control the amount of tracing data collected. Sampling can be configured with the following fields: - -- `client`: percentage of requests that will be force traced if the `x-client-trace-id` header is set. Defaults to 100. -- `random`: percentage of requests that will be randomly traced. Defaults to 100. -- `overall`: percentage of requests that will be traced after all other checks have been applied (force tracing, sampling, etc.). -This field functions as an upper limit on the total configured sampling rate. For instance, setting `client` -to `100%` but `overall` to `1%` will result in only `1%` of client requests with the appropriate headers to be force -traced. Defaults to 100. - -## Custom Tags and Tag Headers - -When collecting traces, $productName$ will attach tags to the `span`'s that are generated which are useful for observability. See the [Envoy Tracing Docs](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/tracing#what-data-each-trace-contains) for the default list of data collected. - -Previous versions of $productName$ only supported adding additional tags through the use of the `tag_headers` field. This field is now **deprecated** and it is recommended to use `custom_tags` which supports a more powerful set of features for adding additional tags to a span. - - -If both tag_headers and custom_tags are set then tag_headers will be ignored. - - -`custom_tags` provides support for configuring additional tags based on [Envoy Custom Tags](https://www.envoyproxy.io/docs/envoy/latest/api-v3/type/tracing/v3/custom_tag.proto%23custom-tag). The following custom tag kinds supported are: - -- `request_header` - set tag from header in the request -- `environment` - set tag from an environment variable -- `literal` - set tag based on a configured literal value - -Each custom_tag supports setting oneOf `request_header`, `literal` or `environment`. Each tag should have its own entry in `custom_tags`. - -For example: - -```yaml -custom_tags: - - tag: host - request_header: - name: ":authority" - default_value: "unknown host" # optional - - tag: path - request_header: ":path" - name: ":authority" - default_value: "unknown path" # optional - - tag: cluster - literal: - value: "us-east-cluster" - - tag: nodeID - environment: - name: SERVER_ID - default_value: "unknown" # optional -``` - -### Lightstep driver configurations - -- `access_token_file` provides the location of the file containing the access token to the LightStep API. - -### Zipkin driver configurations - -- `collector_endpoint` gives the API endpoint of the Zipkin service where the spans will be sent. The default value is `/api/v2/spans` -- `collector_endpoint_version` gives the transport version used when sending data to your Zipkin collector. The default value is `HTTP_JSON` and it must be one of `HTTP_JSON` or `HTTP_PROTO`. -- `collector_endpoint_hostname` sets the hostname Envoy will use when sending data to your Zipkin collector. The default value is the name of the underlying Envoy cluster. -- `trace_id_128bit` whether a 128-bit `trace id` will be used when creating a new trace instance. Defaults to `true`. Setting to `false` will result in a 64-bit trace id being used. -- `shared_span_context` whether client and server spans will share the same `span id`. The default value is `true`. - -### Datadog Driver Configurations - -- `service_name` the name of the service which is attached to the traces. The default value is `ambassador`. - -You may only use a single `TracingService` manifest per $productName$ deployment. Ensure [ambassador_id](../../running#ambassador_id) is set correctly in the `TracingService` manifest. - -## Example - -Check out the [DataDog](../../../../howtos/tracing-datadog) and [Zipkin](../../../../howtos/tracing-zipkin) HOWTOs. diff --git a/content/en/docs/3.3/topics/running/statistics/8877-metrics-grafana.json b/content/en/docs/3.3/topics/running/statistics/8877-metrics-grafana.json deleted file mode 100644 index b2b19b37..00000000 --- a/content/en/docs/3.3/topics/running/statistics/8877-metrics-grafana.json +++ /dev/null @@ -1,943 +0,0 @@ -{ - "annotations": { - "list": [ - { - "builtIn": 1, - "datasource": "Prometheus", - "enable": true, - "hide": true, - "iconColor": "rgba(0, 211, 255, 1)", - "name": "Annotations & Alerts", - "type": "dashboard" - } - ] - }, - "description": "Ambassador dashboard for Prometheus", - "editable": true, - "gnetId": 4698, - "graphTooltip": 0, - "id": 1, - "iteration": 1595611060519, - "links": [], - "panels": [ - { - "collapsed": false, - "datasource": null, - "gridPos": { - "h": 1, - "w": 24, - "x": 0, - "y": 0 - }, - "id": 34, - "panels": [], - "title": "Ambassador - Control Plane", - "type": "row" - }, - { - "cacheTimeout": null, - "colorBackground": false, - "colorValue": false, - "colors": [ - "#299c46", - "rgba(237, 129, 40, 0.89)", - "#d44a3a" - ], - "datasource": null, - "format": "none", - "gauge": { - "maxValue": 100, - "minValue": 0, - "show": false, - "thresholdLabels": false, - "thresholdMarkers": true - }, - "gridPos": { - "h": 5, - "w": 5, - "x": 0, - "y": 1 - }, - "id": 36, - "interval": "", - "links": [], - "mappingType": 1, - "mappingTypes": [ - { - "name": "value to text", - "value": 1 - }, - { - "name": "range to text", - "value": 2 - } - ], - "maxDataPoints": 100, - "maxPerRow": 3, - "nullPointMode": "connected", - "nullText": null, - "options": {}, - "postfix": "", - "postfixFontSize": "50%", - "prefix": "", - "prefixFontSize": "50%", - "rangeMaps": [ - { - "from": "null", - "text": "N/A", - "to": "null" - } - ], - "repeat": null, - "repeatDirection": "h", - "sparkline": { - "fillColor": "rgba(31, 118, 189, 0.18)", - "full": false, - "lineColor": "rgb(31, 120, 193)", - "show": false, - "ymax": null, - "ymin": null - }, - "tableColumn": "", - "targets": [ - { - "expr": "ambassador_diagnostics_info{namespace=~\"$namespace\"}", - "format": "time_series", - "hide": false, - "instant": true, - "intervalFactor": 1, - "legendFormat": "{{version}}", - "refId": "A" - } - ], - "thresholds": "", - "timeFrom": null, - "timeShift": null, - "title": "Version", - "type": "singlestat", - "valueFontSize": "80%", - "valueMaps": [], - "valueName": "name" - }, - { - "cacheTimeout": null, - "datasource": null, - "gridPos": { - "h": 5, - "w": 19, - "x": 5, - "y": 1 - }, - "id": 42, - "links": [], - "options": { - "displayMode": "lcd", - "fieldOptions": { - "calcs": [ - "lastNotNull" - ], - "defaults": { - "mappings": [], - "max": 2.5, - "min": 0, - "nullValueMode": "connected", - "thresholds": [ - { - "color": "green", - "value": null - }, - { - "color": "#EAB839", - "value": 1 - }, - { - "color": "red", - "value": 2 - } - ], - "title": "", - "unit": "s" - }, - "override": {}, - "values": false - }, - "orientation": "vertical" - }, - "pluginVersion": "6.4.3", - "repeat": "pod", - "repeatDirection": "v", - "scopedVars": { - "pod": { - "selected": false, - "text": "ambassador-x", - "value": "ambassador-x" - } - }, - "targets": [ - { - "expr": "ambassador_reconfiguration_time_seconds{namespace=~\"$namespace\", pod=~\"$pod\"}", - "instant": false, - "legendFormat": "Reconfiguration", - "refId": "C" - }, - { - "expr": "ambassador_fetcher_time_seconds{namespace=~\"$namespace\", pod=~\"$pod\"}", - "instant": false, - "legendFormat": "Fetcher", - "refId": "E" - }, - { - "expr": "ambassador_aconf_time_seconds{namespace=~\"$namespace\", pod=~\"$pod\"}", - "instant": false, - "legendFormat": "AConf", - "refId": "A" - }, - { - "expr": "ambassador_ir_time_seconds{namespace=~\"$namespace\", pod=~\"$pod\"}", - "instant": false, - "legendFormat": "IR", - "refId": "F" - }, - { - "expr": "ambassador_econf_time_seconds{namespace=~\"$namespace\", pod=~\"$pod\"}", - "instant": false, - "legendFormat": "EConf", - "refId": "B" - }, - { - "expr": "ambassador_diagnostics_time_seconds{namespace=~\"$namespace\", pod=~\"$pod\"}", - "instant": false, - "legendFormat": "Diagnostics", - "refId": "D" - } - ], - "timeFrom": null, - "timeShift": null, - "title": "Last control plane operation time ($pod)", - "type": "bargauge" - }, - { - "collapsed": true, - "datasource": null, - "gridPos": { - "h": 1, - "w": 24, - "x": 0, - "y": 6 - }, - "id": 38, - "panels": [ - { - "aliasColors": {}, - "bars": false, - "dashLength": 10, - "dashes": false, - "datasource": null, - "fill": 1, - "fillGradient": 0, - "gridPos": { - "h": 7, - "w": 24, - "x": 0, - "y": 2 - }, - "id": 40, - "legend": { - "avg": false, - "current": false, - "max": false, - "min": false, - "show": true, - "total": false, - "values": false - }, - "lines": true, - "linewidth": 1, - "nullPointMode": "null", - "options": { - "dataLinks": [] - }, - "percentage": false, - "pointradius": 2, - "points": false, - "renderer": "flot", - "seriesOverrides": [], - "spaceLength": 10, - "stack": false, - "steppedLine": false, - "targets": [ - { - "expr": " ambassador_edge_stack_go_memstats_alloc_bytes{namespace=~\"$namespace\", pod=~\"$pod\"}", - "legendFormat": "{{pod}}", - "refId": "A" - } - ], - "thresholds": [], - "timeFrom": null, - "timeRegions": [], - "timeShift": null, - "title": "amb-sidecar memory usage", - "tooltip": { - "shared": true, - "sort": 0, - "value_type": "individual" - }, - "type": "graph", - "xaxis": { - "buckets": null, - "mode": "time", - "name": null, - "show": true, - "values": [] - }, - "yaxes": [ - { - "format": "decbytes", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": true - }, - { - "format": "none", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": false - } - ], - "yaxis": { - "align": false, - "alignLevel": null - } - } - ], - "title": "Ambassador", - "type": "row" - }, - { - "collapsed": false, - "datasource": null, - "gridPos": { - "h": 1, - "w": 24, - "x": 0, - "y": 7 - }, - "id": 22, - "panels": [], - "repeat": null, - "title": "Ambassador - Envoy Data Plane", - "type": "row" - }, - { - "aliasColors": {}, - "bars": false, - "dashLength": 10, - "dashes": false, - "datasource": null, - "fill": 1, - "fillGradient": 0, - "gridPos": { - "h": 8, - "w": 24, - "x": 0, - "y": 8 - }, - "id": 30, - "legend": { - "avg": false, - "current": false, - "max": false, - "min": false, - "show": true, - "total": false, - "values": false - }, - "lines": true, - "linewidth": 1, - "links": [], - "nullPointMode": "null", - "options": { - "dataLinks": [] - }, - "percentage": false, - "pointradius": 2, - "points": false, - "renderer": "flot", - "seriesOverrides": [], - "spaceLength": 10, - "stack": false, - "steppedLine": false, - "targets": [ - { - "expr": "sum(increase(envoy_http_downstream_rq_xx{envoy_response_code_class=\"2\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "2xx", - "refId": "A" - }, - { - "expr": "sum(increase(envoy_http_downstream_rq_xx{envoy_response_code_class=\"3\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "3xx", - "refId": "B" - }, - { - "expr": "sum(increase(envoy_http_downstream_rq_xx{envoy_response_code_class=\"4\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "4xx", - "refId": "C" - }, - { - "expr": "sum(increase(envoy_http_downstream_rq_xx{envoy_response_code_class=\"5\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "5xx", - "refId": "D" - } - ], - "thresholds": [], - "timeFrom": null, - "timeRegions": [], - "timeShift": null, - "title": "Ambassador Response Codes", - "tooltip": { - "shared": true, - "sort": 0, - "value_type": "individual" - }, - "type": "graph", - "xaxis": { - "buckets": null, - "mode": "time", - "name": null, - "show": true, - "values": [] - }, - "yaxes": [ - { - "format": "short", - "label": "RPM", - "logBase": 1, - "max": null, - "min": null, - "show": true - }, - { - "format": "short", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": true - } - ], - "yaxis": { - "align": false, - "alignLevel": null - } - }, - { - "aliasColors": {}, - "bars": false, - "dashLength": 10, - "dashes": false, - "datasource": null, - "fill": 1, - "fillGradient": 0, - "gridPos": { - "h": 8, - "w": 24, - "x": 0, - "y": 16 - }, - "id": 20, - "legend": { - "avg": false, - "current": false, - "max": false, - "min": false, - "show": true, - "total": false, - "values": false - }, - "lines": true, - "linewidth": 1, - "links": [], - "nullPointMode": "null", - "options": { - "dataLinks": [] - }, - "percentage": false, - "pointradius": 2, - "points": false, - "renderer": "flot", - "seriesOverrides": [], - "spaceLength": 10, - "stack": false, - "steppedLine": false, - "targets": [ - { - "expr": "sum(increase(envoy_cluster_upstream_rq_xx{envoy_response_code_class=\"2\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "2xx", - "refId": "A" - }, - { - "expr": "sum(increase(envoy_cluster_upstream_rq_xx{envoy_response_code_class=\"3\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "3xx", - "refId": "B" - }, - { - "expr": "sum(increase(envoy_cluster_upstream_rq_xx{envoy_response_code_class=\"4\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "4xx", - "refId": "C" - }, - { - "expr": "sum(increase(envoy_cluster_upstream_rq_xx{envoy_response_code_class=\"5\"}[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "5xx", - "refId": "D" - } - ], - "thresholds": [], - "timeFrom": null, - "timeRegions": [], - "timeShift": null, - "title": "API Response Codes", - "tooltip": { - "shared": true, - "sort": 0, - "value_type": "individual" - }, - "type": "graph", - "xaxis": { - "buckets": null, - "mode": "time", - "name": null, - "show": true, - "values": [] - }, - "yaxes": [ - { - "format": "short", - "label": "RPM", - "logBase": 1, - "max": null, - "min": null, - "show": true - }, - { - "format": "short", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": true - } - ], - "yaxis": { - "align": false, - "alignLevel": null - } - }, - { - "aliasColors": {}, - "bars": false, - "dashLength": 10, - "dashes": false, - "datasource": null, - "fill": 1, - "fillGradient": 0, - "gridPos": { - "h": 8, - "w": 24, - "x": 0, - "y": 24 - }, - "id": 26, - "legend": { - "avg": false, - "current": false, - "max": false, - "min": false, - "show": true, - "total": false, - "values": false - }, - "lines": true, - "linewidth": 1, - "links": [], - "nullPointMode": "null", - "options": { - "dataLinks": [] - }, - "percentage": false, - "pointradius": 2, - "points": false, - "renderer": "flot", - "seriesOverrides": [], - "spaceLength": 10, - "stack": false, - "steppedLine": false, - "targets": [ - { - "expr": "histogram_quantile(0.95, sum(rate(envoy_http_downstream_cx_length_ms_bucket[5m])) by (le))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "95 percentile", - "refId": "A" - }, - { - "expr": "histogram_quantile(0.9, sum(rate(envoy_http_downstream_cx_length_ms_bucket[5m])) by (le))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "90th percentile", - "refId": "B" - }, - { - "expr": "histogram_quantile(0.5, sum(rate(envoy_http_downstream_cx_length_ms_bucket[5m])) by (le))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "50th percentile", - "refId": "C" - } - ], - "thresholds": [], - "timeFrom": null, - "timeRegions": [], - "timeShift": null, - "title": "Downstream Connections Length", - "tooltip": { - "shared": true, - "sort": 0, - "value_type": "individual" - }, - "type": "graph", - "xaxis": { - "buckets": null, - "mode": "time", - "name": null, - "show": true, - "values": [] - }, - "yaxes": [ - { - "format": "short", - "label": "Milliseconds", - "logBase": 1, - "max": null, - "min": null, - "show": true - }, - { - "format": "short", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": true - } - ], - "yaxis": { - "align": false, - "alignLevel": null - } - }, - { - "aliasColors": {}, - "bars": false, - "dashLength": 10, - "dashes": false, - "datasource": null, - "fill": 1, - "fillGradient": 0, - "gridPos": { - "h": 8, - "w": 18, - "x": 0, - "y": 32 - }, - "id": 28, - "legend": { - "avg": false, - "current": false, - "max": false, - "min": false, - "show": true, - "total": false, - "values": false - }, - "lines": true, - "linewidth": 1, - "links": [], - "nullPointMode": "null", - "options": { - "dataLinks": [] - }, - "percentage": false, - "pointradius": 2, - "points": false, - "renderer": "flot", - "seriesOverrides": [], - "spaceLength": 10, - "stack": false, - "steppedLine": false, - "targets": [ - { - "expr": "sum(increase(envoy_http_downstream_cx_http1_active[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "HTTP/1", - "refId": "A" - }, - { - "expr": "sum(increase(envoy_http_downstream_cx_http2_active_active[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "HTTP/2", - "refId": "B" - }, - { - "expr": "sum(increase(envoy_http_downstream_cx_upgrades_active[1m]))", - "format": "time_series", - "intervalFactor": 1, - "legendFormat": "Websocket", - "refId": "C" - } - ], - "thresholds": [], - "timeFrom": null, - "timeRegions": [], - "timeShift": null, - "title": "Active Connections", - "tooltip": { - "shared": true, - "sort": 0, - "value_type": "individual" - }, - "type": "graph", - "xaxis": { - "buckets": null, - "mode": "time", - "name": null, - "show": true, - "values": [] - }, - "yaxes": [ - { - "format": "short", - "label": "RPM", - "logBase": 1, - "max": null, - "min": null, - "show": true - }, - { - "format": "short", - "label": null, - "logBase": 1, - "max": null, - "min": null, - "show": true - } - ], - "yaxis": { - "align": false, - "alignLevel": null - } - }, - { - "cacheTimeout": null, - "colorBackground": false, - "colorValue": false, - "colors": [ - "#299c46", - "rgba(237, 129, 40, 0.89)", - "#d44a3a" - ], - "datasource": null, - "format": "none", - "gauge": { - "maxValue": 100, - "minValue": 0, - "show": false, - "thresholdLabels": false, - "thresholdMarkers": true - }, - "gridPos": { - "h": 8, - "w": 6, - "x": 18, - "y": 32 - }, - "id": 32, - "interval": null, - "links": [], - "mappingType": 1, - "mappingTypes": [ - { - "name": "value to text", - "value": 1 - }, - { - "name": "range to text", - "value": 2 - } - ], - "maxDataPoints": 100, - "nullPointMode": "connected", - "nullText": null, - "options": {}, - "postfix": "", - "postfixFontSize": "50%", - "prefix": "", - "prefixFontSize": "50%", - "rangeMaps": [ - { - "from": "null", - "text": "N/A", - "to": "null" - } - ], - "sparkline": { - "fillColor": "rgba(31, 118, 189, 0.18)", - "full": false, - "lineColor": "rgb(31, 120, 193)", - "show": false - }, - "tableColumn": "", - "targets": [ - { - "expr": "avg(envoy_cluster_manager_active_clusters)", - "format": "time_series", - "intervalFactor": 1, - "refId": "A" - } - ], - "thresholds": "", - "timeFrom": null, - "timeShift": null, - "title": "Registered Services", - "type": "singlestat", - "valueFontSize": "80%", - "valueMaps": [ - { - "op": "=", - "text": "N/A", - "value": "null" - } - ], - "valueName": "avg" - } - ], - "refresh": "5s", - "schemaVersion": 20, - "style": "dark", - "tags": [ - "ambassador" - ], - "templating": { - "list": [ - { - "allValue": null, - "current": { - "text": "All", - "value": [ - "$__all" - ] - }, - "datasource": "Prometheus", - "definition": "label_values(ambassador_diagnostics_info, namespace)", - "hide": 0, - "includeAll": true, - "label": "Namespace", - "multi": true, - "name": "namespace", - "options": [], - "query": "label_values(ambassador_diagnostics_info, namespace)", - "refresh": 1, - "regex": "", - "skipUrlSync": false, - "sort": 5, - "tagValuesQuery": "", - "tags": [], - "tagsQuery": "", - "type": "query", - "useTags": false - }, - { - "allValue": null, - "current": { - "tags": [], - "text": "All", - "value": [ - "$__all" - ] - }, - "datasource": "Prometheus", - "definition": "label_values(ambassador_diagnostics_info{namespace=\"$namespace\"}, pod)", - "hide": 0, - "includeAll": true, - "label": "Pod", - "multi": true, - "name": "pod", - "options": [], - "query": "label_values(ambassador_diagnostics_info{namespace=\"$namespace\"}, pod)", - "refresh": 1, - "regex": "", - "skipUrlSync": false, - "sort": 5, - "tagValuesQuery": "", - "tags": [], - "tagsQuery": "", - "type": "query", - "useTags": false - } - ] - }, - "time": { - "from": "now-15m", - "to": "now" - }, - "timepicker": { - "refresh_intervals": [ - "5s", - "10s", - "30s", - "1m", - "5m", - "15m", - "30m", - "1h", - "2h", - "1d" - ], - "time_options": [ - "5m", - "15m", - "1h", - "6h", - "12h", - "24h", - "2d", - "7d", - "30d" - ] - }, - "timezone": "", - "title": "Ambassador", - "uid": "AJieHz4Mz", - "version": 16 -} diff --git a/content/en/docs/3.3/topics/running/statistics/8877-metrics.md b/content/en/docs/3.3/topics/running/statistics/8877-metrics.md deleted file mode 100644 index 42f5690a..00000000 --- a/content/en/docs/3.3/topics/running/statistics/8877-metrics.md +++ /dev/null @@ -1,79 +0,0 @@ -# The metrics endpoint - -> For an overview of other options for gathering statistics on -> $productName$, see the [Statistics and Monitoring](../) overview. - -Each $productName$ pod exposes statistics and metrics for that pod at -`http://{POD}:8877/metrics`. The response is in the text-based -Prometheus [exposition format][]. - -[exposition format]: https://prometheus.io/docs/instrumenting/exposition_formats/ - -## Understanding the statistics - -The Prometheus exposition format includes special "HELP" lines that -make the file self-documenting as to what specific statistics mean. - - - -- `envoy_*`: See the [Envoy documentation][`GET /stats/prometheus`]. -- `ambassador_*` (new in 1.7.0): - - `ambassador_edge_stack_*` (not present in $OSSproductName$): - - `ambassador_edge_stack_go_*`: See [`promethus.NewGoCollector()`][]. - - `ambassador_edge_stack_promhttp_*` See [`promhttp.Handler()`][]. - - `ambassador_edge_stack_process_*`: See [`promethus.NewProcessCollector()`][].. - - `ambassador_*_time_seconds` (for `*` = one of `aconf`, `diagnostics`, `econf`, `fetcher`, `ir`, or `reconfiguration`): - Gauges of how long the various core operations take in the diagd - process. - - `ambassador_diagnostics_(errors|notices)`: The number of - diagnostics errors and notices that would be shown in the - diagnostics UI or the Edge Policy Console. - - `ambassador_diagnostics_info`: [Info][`prometheus_client.Info`] - about the $productName$ install; all information is presented in - labels; the value of the Gauge is always "1". - - `ambassador_process_*`: See [`prometheus_client.ProcessCollector`][]. - -[`GET /stats/prometheus`]: https://www.envoyproxy.io/docs/envoy/v1.15.0/operations/admin.html#get--stats-prometheus -[`prometheus.NewProcessCollector`]: https://godoc.org/github.com/prometheus/client_golang/prometheus#NewProcessCollector -[`prometheus.NewGoCollector`]: https://godoc.org/github.com/prometheus/client_golang/prometheus#NewGoCollector -[`promhttp.Handler()`]: https://godoc.org/github.com/prometheus/client_golang/prometheus/promhttp#Handler -[`prometheus_client.Info`]: https://github.com/prometheus/client_python#info -[`prometheus_client.ProcessCollector`]: https://github.com/prometheus/client_python#process-collector - -## Polling the `:8877/metrics` endpoint with Prometheus - -To scrape metrics directly, follow the instructions for [Monitoring -with Prometheus and Grafana](../../../../howtos/prometheus). - -### Using Grafana to visualize statistics gathered by Prometheus - -#### Sample dashboard - -We provide a [sample Grafana dashboard](https://grafana.com/grafana/dashboards/4698-ambassador-edge-stack/) -that displays information collected by Prometheus from the -`:8877/metrics` endpoint. - - -#### Just Envoy information - -![Screenshot of a Grafana dashboard that displays just information from Envoy](../../../images/grafana.png) - -[Alex Gervais][] has written a template [$productName$ dashboard for -Grafana][] that displays information collected by Prometheus either -from the `:8877/metrics` endpoint, or from [Envoy over -StatsD][envoy-statsd-prometheus]. Because it is designed to work with -the Envoy StatsD set up, it does not include any of the `ambassador_*` -statistics; because of this, we recommend using the other sample -dashboard above. - -[Alex Gervais]: https://twitter.com/alex_gervais -[$productName$ dashboard for Grafana]: https://grafana.com/grafana/dashboards/4698-ambassador-edge-stack/ -[envoy-statsd-prometheus]: ../envoy-statsd#using-prometheus-statsd-exporter-as-the-statsd-sink diff --git a/content/en/docs/3.3/topics/running/statistics/envoy-statsd.md b/content/en/docs/3.3/topics/running/statistics/envoy-statsd.md deleted file mode 100644 index 851c9182..00000000 --- a/content/en/docs/3.3/topics/running/statistics/envoy-statsd.md +++ /dev/null @@ -1,254 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Envoy statistics with StatsD - -> For an overview of other options for gathering statistics on -> $productName$, see the [Statistics and Monitoring](../) overview. - -At the core of $productName$ is [Envoy Proxy], which has built-in -support for exporting a multitude of statistics about its own -operations to StatsD (or to the modified DogStatsD used by Datadog). - -[Envoy Proxy]: https://www.envoyproxy.io - -If enabled, then $productName$ has Envoy expose this 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: - -```diff - spec: - containers: - - env: -+ - name: STATSD_ENABLED -+ value: "true" - - name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: -``` - -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. - -We have included a few example configurations in the -[`statsd-sink/`] directory to help you get started. Clone the -repository to get local, editable copies. - -[`statsd-sink/`]: https://github.com/emissary-ingress/emissary/tree/master/deployments/statsd-sink - -## Using Graphite as the StatsD sink - -[Graphite] is a web-based real-time graphing system. Spin up an -example Graphite setup: - -[Graphite]: http://graphite.readthedocs.org/ - -``` -kubectl apply -f statsd-sink/graphite/graphite-statsd-sink.yaml -``` - -This sets up the `statsd-sink` service and a deployment that contains -Graphite and its related infrastructure. Graphite's web interface is -available at `http://statsd-sink/` from within the cluster. Use port -forwarding to access the interface from your local machine: - -``` -SINKPOD=$(kubectl get pod -l service=statsd-sink -o jsonpath="{.items[0].metadata.name}") -kubectl port-forward $SINKPOD 8080:80 -``` - -This sets up Graphite access at `http://localhost:8080/`. - -## Using Prometheus StatsD Exporter as the StatsD sink - - - $productName$ $version$ has an endpoint that has exposes statistics in - a format that Prometheus understands natively. If you're using Prometheus, - we recommend configuring Prometheus to talk to  - the :8877/metrics endpoint  - directly, instead of instead of going through StatsD and a translator. - - -[Prometheus] is an open-source monitoring and alerting system. -Prometheus does not natively understand the StatsD protocol, but you -can deploy the [Prometheus StatsD Exporter] to act as the StatsD -sink, and it will translate from StatsD to the [exposition format] -that Prometheus requires. An example of how deploying Prometheus -StatsD Exporter is available in [`prom-statsd-sink.yaml`]. - -[Prometheus]: https://prometheus.io/ -[Prometheus StatsD Exporter]: https://github.com/prometheus/statsd_exporter -[exposition format]: https://prometheus.io/docs/instrumenting/exposition_formats/ -[`prom-statsd-sink.yaml`]: https://github.com/emissary-ingress/emissary/blob/master/deployments/statsd-sink/prometheus/prom-statsd-sink.yaml - -To finally get the statistics to Prometheus, you then configure a -Prometheus target to read from `statsd-sink` on port 9102. - -You could instead also add the `statsd-sink` service and Prometheus StatsD -Exporter as a sidecar on the $productName$ pod. If you do this, make -sure to set `STATSD_HOST=localhost` so that UDP packets are routed to -the sidecar. - -### Configuring how Prometheus StatsD Exporter translates from StatsD to the Prometheus format - -It may be desirable to change how metrics produced by the -`statsd-sink` are named, labeled and grouped when they finally make it -to Prometheus. - -For example, by default, each service that $productName$ serves will -create a new metric using its name. For the service called `usersvc` -you will see this metric -`envoy.cluster.usersvc_cluster.upstream_rq_total`. This may lead to -problems if you are trying to create a single aggregate that is the -sum of all similar metrics from different services. In this case, it -is common to differentiate the metrics for an individual service with -a `label`. This can be done by configuring a Prometheus StatsD -Exporter "mapping" (not to be confused with an [$productName$ -`Mapping`][Mappings]). See [Metric Mapping and Configuration] in -the Prometheus StatsD Exporter documentation to learn how to modify -its mappings. - -[Mappings]: ../../../using/mappings -[Metric Mapping and Configuration]: https://github.com/prometheus/statsd_exporter/#user-content-metric-mapping-and-configuration - -#### Configuring Prometheus StatsD Exporter with Helm - -If you deploy Prometheus using Helm the value that you should change -in order to add a mapping is `prometheusExporter.configuration`. Set -it to something like this: - -```yaml - configuration: | - --- - mappings: - - match: 'envoy.cluster.*.upstream_rq_total' - name: "envoy_cluster_upstream_rq_total" - timer_type: 'histogram' - labels: - cluster_name: "$1" -``` - -#### Configuring Prometheus StatsD Exporter in `prom-statsd-sink.yaml` - -If you are using the [`prom-statsd-sink.yaml`] example, edit its `ambassador-config` -ConfigMap with your Prometheus mappings, for example: - -```yaml ---- -apiVersion: v1 -kind: ConfigMap -metadata: - name: ambassador-config -data: - exporterConfiguration: | - --- - mappings: - - match: 'envoy.cluster.*.upstream_rq_total' - name: "envoy_cluster_upstream_rq_total" - timer_type: 'histogram' - labels: - cluster_name: "$1" -``` - -### Using the Prometheus Operator to configure Prometheus for use with the Prometheus StatsD Exporter - -If you don't already have a Prometheus setup, the [Prometheus -Operator] is a powerful way to create and deploy Prometheus -instances. Use the following YAML to quickly configure the Prometheus -Operator with $productName$: - -- [`statsd-sink.yaml`] Creates the Prometheus Stats Exporter - deployment and `statsd-sink` service that receives the statistics - from $productName$ and translates them to Prometheus metrics. It also - creates a `ServiceMonitor` resource that tells the Prometheus - Operator to configure Prometheus to fetch those metrics from the - StatsD Exporter. -- [`prometheus.yaml`] Deploys the Prometheus Operator and creates - `Prometheus` resource that tells the Prometheus Operator to create - the actual Prometheus deployment. - -[Prometheus operator]: https://github.com/coreos/prometheus-operator -[`statsd-sink.yaml`]: https://github.com/emissary-ingress/emissary/blob/master/deployments/statsd-sink/prometheus/statsd-sink.yaml -[`prometheus.yaml`]: https://github.com/emissary-ingress/emissary/blob/master/deployments/statsd-sink/prometheus/prometheus.yaml - -Make sure that the `ServiceMonitor` is in the same namespace as -$productName$. A walk-through of the basics of configuring the -Prometheus Operator with $productName$ is available -[here](http://www.datawire.io/faster/ambassador-prometheus/). - -Ensure `STATSD_ENABLED` is set to `"true"` and apply the YAML with -`kubectl`: - -``` -kubectl apply -f statsd-sink.yaml -kubectl apply -f prometheus.yaml -``` - -Wait for a minute after the pods spin up and then access the -Prometheus dashboard by port-forwarding the Prometheus pod and going -to `http://localhost:9090/` on a web-browser. - -``` -kubectl port-forward prometheus-prometheus-0 9090 -``` - -### Using Grafana to visualize statistics gathered by Prometheus - -![Screenshot of a Grafana dashboard that displays just information from Envoy](../../../images/grafana.png) - -If you're using Grafana, [Alex Gervais] has written a template -[$productName$ dashboard for Grafana] that works with either the -metrics exposed by the Prometheus StatsD Exporter, or by [the -`:8877/metrics` endpoint]. - -[Alex Gervais]: https://twitter.com/alex_gervais -[$productName$ dashboard for Grafana]: https://grafana.com/grafana/dashboards/4698-ambassador-edge-stack/ - -## Using Datadog DogStatsD as the StatsD sink - -If you are a user of the [Datadog] monitoring system, pulling in the -Envoy statistics from $productName$ is very easy. - -[Datadog]: https://www.datadoghq.com/ - -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: - -```diff - spec: - containers: - - env: -+ - name: STATSD_ENABLED -+ value: "true" -+ - name: DOGSTATSD -+ value: "true" - - name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: -``` - -Then, you will need to deploy the DogStatsD agent in to your cluster -to act as the StatsD sink. To do this, replace the sample API key in -our [sample YAML file][`dd-statsd-sink.yaml`] with your own, then -apply that YAML: - -[`dd-statsd-sink.yaml`]: https://github.com/emissary-ingress/emissary/blob/master/deployments/statsd-sink/datadog/dd-statsd-sink.yaml - -``` -kubectl apply -f statsd-sink/datadog/dd-statsd-sink.yaml -``` - -This sets up the `statsd-sink` service and a deployment of the -DogStatsD agent that forwards the $productName$ statistics to your -Datadog account. - -Additionally, $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). diff --git a/content/en/docs/3.3/topics/running/statistics/index.md b/content/en/docs/3.3/topics/running/statistics/index.md deleted file mode 100644 index 04033002..00000000 --- a/content/en/docs/3.3/topics/running/statistics/index.md +++ /dev/null @@ -1,79 +0,0 @@ -# Statistics and monitoring - -$productName$ collects many statistics internally, and makes it easy to -direct this information to a statistics and monitoring tool of your -choice. As an example, for a given service `usersvc`, here are some -interesting statistics to investigate: - -- `envoy.cluster.usersvc.upstream_rq_total` is the total - number of requests that `usersvc` has received via $productName$. The rate of change of this value is one basic measure of - service utilization, i.e. requests per second. -- `envoy.cluster.usersvc.upstream_rq_2xx` is the total number - of requests to which `usersvc` responded with an HTTP response - indicating success. This value divided by the prior one, taken on - an rolling window basis, represents the recent success rate of the - service. There are corresponding `4xx` and `5xx` counters that can - help clarify the nature of unsuccessful requests. -- `envoy.cluster.usersvc.upstream_rq_time` is a StatsD timer - that tracks the latency in milliseconds of `usersvc` from $productName$'s perspective. StatsD timers include information about - means, standard deviations, and decile values. - -## Overriding Statistics Names - -The optional `stats_name` element of every CRD that references a service (`Mapping`, `TCPMapping`, -`AuthService`, `LogService`, `RateLimitService`, and `TracingService`) can override the name under which cluster statistics -are logged (`usersvc` above). If not set, the default is the `service` value, with non-alphanumeric characters replaced by -underscores: - -- `service: foo` will just use `foo` -- `service: foo:8080` will use `foo_8080` -- `service: http://foo:8080` will use `http___foo_8080` -- `service: foo.othernamespace` will use `foo_othernamespace` - -The last example is worth special mention: a resource in a different namespace than the one in which $productName$ is running will automatically be qualified with the namespace of the resource itself. So, for example, if $productName$ is running in the `ambassador` namespace, and this `Mapping` is present in the `default` namespace: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: default-mapping - namespace: default -spec: - prefix: /default/ - service: default-service -``` - -then the `service` will be qualified to `default-service.default`, so the `stats_name` will be `default_service_default` rather than simply `default_service`. To change this behavior, set `stats_name` explicitly. - -## Monitoring Statistics - -There are several ways to get different statistics out of $productName$: - -- [The `:8877/metrics` endpoint](./8877-metrics) can be polled for - aggregated statistics (in a Prometheus-compatible format). This is - our recommended method. -- $productName$ can push [Envoy statistics](./envoy-statsd) over the - StatsD or DogStatsD protocol. -- $productName$ can push [RateLimiting - statistics](../environment) over the StatsD protocol. - -## The Four Golden Signals - -The [Four Golden Signals](https://sre.google/sre-book/monitoring-distributed-systems/) are four generally-accepted metrics -that are important to monitor for good information about service health: - -### Latency - -The time it takes to service a request. `cluster.$name.upstream_rq_time` is a histogram of time taken by individual requests, which can be an effective latency metric. - -### Traffic - -The amount of demand being placed on your system. `cluster.$name.upstream_rq_active` is a gauge that shows the number of active outstanding requests, which can be a good proxy for traffic. - -### Errors - -The number of failing requests. Some errors (e.g. a request succeeds, but gives the wrong answer) can only be detected by application-specific monitoring; however, many errors can be spotted simply by looking at the HTTP status code of requests. `cluster.$name.upstream_rq_5xx` is a counter of HTTP `5xx` responses, so monitoring it over time can show error rates. (Likewise, `cluster.$name.upstream_rq_4xx` exists.) - -### Saturation - -The hardest metric to measure, saturation describes how much of the total capability of the system to respond to requests is being used. Fully measuring saturation often requires application-specific monitoring, but looking at the 99th percentile of latency over a short window - perhaps a a minute - can often give an early indication of saturation problems. diff --git a/content/en/docs/3.3/topics/running/tls/cleartext-redirection.md b/content/en/docs/3.3/topics/running/tls/cleartext-redirection.md deleted file mode 100644 index deee5354..00000000 --- a/content/en/docs/3.3/topics/running/tls/cleartext-redirection.md +++ /dev/null @@ -1,80 +0,0 @@ ---- - description: Cleartext support - While most modern web applications choose to encrypt all traffic, there are some cases where supporting cleartext communications is i… | $productName$ ---- - -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`. - - - The 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. - - -## Cleartext Routing - -To allow cleartext to be routed, set the `requestPolicy.insecure.action` of a `Host` to `Route`: - -```yaml -requestPolicy: - insecure: - action: Redirect -``` - -This allows routing for either HTTP and HTTPS, or _only_ HTTP, depending on `tlsSecret` configuration: - -- If the `Host` does not specify a `tlsSecret`, it will only route HTTP, not terminating TLS at all. -- If the `Host` does specify a `tlsSecret`, it will route both HTTP and HTTPS. - - - The 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. - - -## HTTP->HTTPS redirection - -Most websites that force HTTPS will also automatically redirect any -requests that come into it over HTTP: - -``` -Client $productName$ -| | -| http:///api | -| --------------------------> | -| | -| 301: https:///api | -| <-------------------------- | -| | -| https:///api | -| --------------------------> | -| | -``` - -In $productName$, this is configured by setting the `insecure.action` in a `Host` to `Redirect`. - -```yaml -requestPolicy: - insecure: - action: Redirect -``` - -$productName$ determines which requests are secure and which are insecure using the -`securityModel` of the [`Listener`] that accepts the request. - -[`Listener`]: ../../listener - - - The 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. - diff --git a/content/en/docs/3.3/topics/running/tls/index.md b/content/en/docs/3.3/topics/running/tls/index.md deleted file mode 100644 index 850fb5c0..00000000 --- a/content/en/docs/3.3/topics/running/tls/index.md +++ /dev/null @@ -1,487 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Transport Layer Security (TLS) - -$productName$'s robust TLS support exposes configuration options -for many different TLS use cases, using the [`Host`](#host) and -[`TLSContext`](#host-and-tlscontext) resources in concert. - -## Certificates and Secrets - -Properly-functioning TLS requires the use of [TLS certificates] to prove that the -various systems communicating are who they say they are. At minimum, $productName$ -must have a server certificate that identifies it to clients; when [mTLS] or -[client certificate authentication] are in use, additional certificates are needed. - -You supply certificates to $productName$ in Kubernetes [TLS Secrets]. These Secrets -_must_ contain valid X.509 certificates with valid PKCS1, PKCS8, or Elliptic Curve private -keys. If a Secret does not contain a valid certificate, an error message will be logged, for -example: - -``` -tls-broken-cert.default.1 2 errors:; 1. K8sSecret secret tls-broken-cert.default tls.key cannot be parsed as PKCS1 or PKCS8: asn1: syntax error: data truncated; 2. K8sSecret secret tls-broken-cert.default tls.crt cannot be parsed as x.509: x509: malformed certificate -``` - -If you set the `AMBASSADOR_FORCE_SECRET_VALIDATION` environment variable, the invalid -Secret will be rejected, and a `Host` or `TLSContext` resource attempting to use an invalid -certificate will be disabled entirely. **Note** that in $productName$ $version$, this -includes disabling cleartext communication for such a `Host`. - -[TLS Certificates]: https://protonmail.com/blog/tls-ssl-certificate/ -[mTLS]: mtls -[client certificate authentication]: ../../../howtos/client-cert-validation/ -[TLS Secrets]: https://kubernetes.io/docs/concepts/configuration/secret/#tls-secrets - -## `Host` - -A `Host` represents a domain in $productName$ and defines how the domain manages TLS. For more information on the Host resource, see [The Host CRD reference documentation](../host-crd). - -**If no `Host`s are present**, $productName$ synthesizes a `Host` that -allows only cleartext routing. You will need to explictly define `Host`s to enable -TLS termination. - - - The examples below do not define a requestPolicy; however, most real-world - usage of $productName$ will require defining the requestPolicy.
-
- For more information, please refer to the Host documentation. - - -### Bring your own certificate - -The `Host` can read a certificate from a Kubernetes Secret and use that certificate -to terminate TLS on a domain. - -The following example shows the certificate contained in the Kubernetes Secret named -`host-secret` configured to have $productName$ terminate TLS on the `host.example.com` -domain: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: host-secret -``` - -By default, `tlsSecret` will only look for the named secret in the same namespace as the `Host`. -In the above example, the secret `host-secret` will need to exist within the `default` namespace -since that is the namespace of the `Host`. - -To reference a secret that is in a different namespace from the `Host`, the `namespace` field is required. -The below example will configure the `Host` to use the `host-secret` secret from the `example` namespace. - -```yaml ---- -apiVersion: getambassador.io/v2 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - acmeProvider: - authority: none - tlsSecret: - name: host-secret - namespace: example -``` - - - - The Kubernetes Secret named by 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. - - - -### Advanced TLS configuration with the `Host` - -You can specify TLS configuration directly in the `Host` via the `tls` field. This is the -recommended method to do more advanced TLS configuration for a single `Host`. - -For example, the configuration to enforce a minimum TLS version on the `Host` looks as follows: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: min-secret - tls: - min_tls_version: v1.2 -``` - - - - The Kubernetes Secret named by 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. - - - -The following fields are accepted in the `tls` field: -```yaml -tls: - cert_chain_file: # string - private_key_file: # string - ca_secret: # string - cacert_chain_file: # string - alpn_protocols: # string - cert_required: # bool - min_tls_version: # string - max_tls_version: # string - cipher_suites: # array of strings - ecdh_curves: # array of strings - sni: # string - crl_secret: # string -``` - -These fields have the same function as in the [`TLSContext`](#tlscontext) resource, -as described below. - -### `Host` and `TLSContext` - -You can link a `Host` to a [`TLSContext`](#tlscontext) instead of defining `tls` -settings in the `Host` itself. This is primarily useful for sharing settings between -multiple `Host`s. - -#### Link a `TLSContext` to the `Host` - - - It is invalid to use both the 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. - - -To link a [`TLSContext`](#tlscontext) with a `Host`, create a [`TLSContext`](#tlscontext) -with the desired configuration and link it to the `Host` by setting the `tlsContext.name` -field in the `Host`. For example, to enforce a minimum TLS version on the `Host` above, -create a `TLSContext` with any name with the following configuration: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: min-tls-context -spec: - hosts: - - host.example.com - secret: min-secret - min_tls_version: v1.2 -``` - -Next, link it to the `Host` via the `tlsContext` field as shown: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: min-secret - tlsContext: - name: min-tls-context -``` - - - - The `Host` and the `TLSContext` must name the same Kubernetes Secret; if not, - $productName$ will disable TLS for the `Host`. - - - - - - The Kubernetes Secret named by 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. - - - - - - The `Host`'s `hostname` and the `TLSContext`'s `hosts` must have compatible settings. If - they do not, requests may not be accepted. - - - -See [`TLSContext`](#tlscontext) below to read more on the description of these fields. - -#### Create a `TLSContext` with the name `{{AMBASSADORHOST}}-context` (DEPRECATED) - - - This implicit 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. - - -The `Host` will implicitly link to the `TLSContext` when a `TLSContext` exists with the following: - -- the name `{{NAME_OF_AMBASSADORHOST}}-context` -- `hosts` in the `TLSContext` set to the same value as `hostname` in the `Host`, and -- `secret` in the `TLSContext` set to the same value as `tlsSecret` in the `Host` - -**As noted above, this implicit linking is deprecated.** - -For example, another way to enforce a minimum TLS version on the `Host` above would -be to simply create the `TLSContext` with the name `example-host-context` and then not modify the `Host`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-host-context -spec: - hosts: - - host.example.com - secret: host-secret - min_tls_version: v1.2 -``` - - - - The `Host` and the `TLSContext` must name the same Kubernetes Secret; if not, - $productName$ will disable TLS for the `Host`. - - - - - - The Kubernetes Secret named by 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. - - - - - - The `Host`'s `hostname` and the `TLSContext`'s `hosts` must have compatible settings. If - they do not, requests may not be accepted. - - - -Full reference for all options available to the `TLSContext` can be found [below](#tlscontext). - -## TLSContext - -The `TLSContext` is used to configure advanced TLS options in $productName$. -Remember, a `TLSContext` must always be paired with a `Host`. - -A full schema of the `TLSContext` can be found below with descriptions of the -different configuration options. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-host-context -spec: - # 'hosts' defines the hosts for which this TLSContext is relevant. - # It ties into SNI. A TLSContext without "hosts" is useful only for - # originating TLS. - # type: array of strings - # - # hosts: [] - - # 'sni' defines the SNI string to use on originated connections. - # type: string - # - # sni: None - - # 'secret' defines a Kubernetes Secret that contains the TLS certificate we - # use for origination or termination. If not specified, $productName$ will look - # at the value of cert_chain_file and private_key_file. - # type: string - # - # secret: None - - # 'ca_secret' defines a Kubernetes Secret that contains the TLS certificate we - # use for verifying incoming TLS client certificates. - # type: string - # - # ca_secret: None - - # Tells $productName$ whether to interpret a "." in the secret name as a "." or - # a namespace identifier. - # type: boolean - # - # secret_namespacing: true - - # 'cert_required' can be set to true to _require_ TLS client certificate - # authentication. - # type: boolean - # - # cert_required: false - - # 'alpn_protocols' is used to enable the TLS ALPN protocol. It is required - # if you want to do GRPC over TLS; typically it will be set to "h2" for that - # case. - # type: string (comma-separated list) - # - # alpn_protocols: None - - # 'min_tls_version' sets the minimum acceptable TLS version: v1.0, v1.1, - # v1.2, or v1.3. It defaults to v1.0. - # min_tls_version: v1.0 - - # 'max_tls_version' sets the maximum acceptable TLS version: v1.0, v1.1, - # v1.2, or v1.3. It defaults to v1.3. - # max_tls_version: v1.3 - - # Tells $productName$ to load TLS certificates from a file in its container. - # type: string - # - # cert_chain_file: None - # private_key_file: None - # cacert_chain_file: None -``` - - - - `secret` and (if used) `ca_secret` must specify Kubernetes Secrets containing valid TLS - certificates. If `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and either Secret contains - an invalid certificate, $productName$ will reject the Secret, which will also completely - disable any `Host` using the `TLSContext`; see [**Certificates and Secrets**](#certificates-and-secrets) - above. - - - -### ALPN protocols - -The `alpn_protocols` setting configures the TLS ALPN protocol. To use gRPC over -TLS, set `alpn_protocols: h2`. If you need to support HTTP/2 upgrade from -HTTP/1, set `alpn_protocols: h2,http/1.1` in the configuration. - -#### HTTP/2 support - -The `alpn_protocols` setting is also required for HTTP/2 support. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls -spec: - secret: ambassador-certs - hosts: ["*"] - alpn_protocols: h2[, http/1.1] -``` -Without setting alpn_protocols as shown above, HTTP2 will not be available via -negotiation and will have to be explicitly requested by the client. - -If you leave off http/1.1, only HTTP2 connections will be supported. - -### TLS parameters - -The `min_tls_version` setting configures the minimum TLS protocol version that -$productName$ will use to establish a secure connection. When a client -using a lower version attempts to connect to the server, the handshake will -result in the following error: `tls: protocol version not supported`. - -The `max_tls_version` setting configures the maximum TLS protocol version that -$productName$ will use to establish a secure connection. When a client -using a higher version attempts to connect to the server, the handshake will -result in the following error: -`tls: server selected unsupported protocol version`. - -The `cipher_suites` setting configures the supported ciphers found below using the -[configuration parameters for BoringSSL](https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#Cipher-suite-configuration) when negotiating a TLS 1.0-1.2 connection. -This setting has no effect when negotiating a TLS 1.3 connection. When a client does not -support a matching cipher a handshake error will result. - -The `ecdh_curves` setting configures the supported ECDH curves when negotiating -a TLS connection. When a client does not support a matching ECDH a handshake -error will result. - -``` - - AES128-SHA - - AES256-SHA - - AES128-GCM-SHA256 - - AES256-GCM-SHA384 - - ECDHE-RSA-AES128-SHA - - ECDHE-RSA-AES256-SHA - - ECDHE-RSA-AES128-GCM-SHA256 - - ECDHE-RSA-AES256-GCM-SHA384 - - ECDHE-RSA-CHACHA20-POLY1305 - - ECDHE-ECDSA-AES128-SHA - - ECDHE-ECDSA-AES256-SHA - - ECDHE-ECDSA-AES128-GCM-SHA256 - - ECDHE-ECDSA-AES256-GCM-SHA384 - - ECDHE-ECDSA-CHACHA20-POLY1305 - - ECDHE-PSK-AES128-CBC-SHA - - ECDHE-PSK-AES256-CBC-SHA - - ECDHE-PSK-CHACHA20-POLY1305 - - PSK-AES128-CBC-SHA - - PSK-AES256-CBC-SHA - - DES-CBC3-SHA -``` - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls -spec: - hosts: ["*"] - secret: ambassador-certs - min_tls_version: v1.0 - max_tls_version: v1.3 - cipher_suites: - - "[ECDHE-ECDSA-AES128-GCM-SHA256|ECDHE-ECDSA-CHACHA20-POLY1305]" - - "[ECDHE-RSA-AES128-GCM-SHA256|ECDHE-RSA-CHACHA20-POLY1305]" - ecdh_curves: - - X25519 - - P-256 -``` - - -The `crl_secret` field allows you to reference a Kubernetes Secret that contains a certificate revocation list. -If specified, $productName$ will verify that the presented peer certificate has not been revoked by this CRL even if they are otherwise valid. This provides a way to reject certificates before they expire or if they become compromised. -The `crl_secret` field takes a PEM-formatted [Certificate Revocation List](https://en.wikipedia.org/wiki/Certificate_revocation_list) in a `crl.pem` entry. - -Note that if a CRL is provided for any certificate authority in a trust chain, a CRL must be provided for all certificate authorities in that chain. Failure to do so will result in verification failure for both revoked and unrevoked certificates from that chain. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls-crl -spec: - hosts: ["*"] - secret: ambassador-certs - min_tls_version: v1.0 - max_tls_version: v1.3 - crl_secret: 'ambassador-crl' ---- -apiVersion: v1 -kind: Secret -metadata: - name: ambassador-crl - namespace: ambassador -type: Opaque -data: - crl.pem: | - {BASE64 CRL CONTENTS} ---- -``` diff --git a/content/en/docs/3.3/topics/running/tls/mtls.md b/content/en/docs/3.3/topics/running/tls/mtls.md deleted file mode 100644 index 1b039cf8..00000000 --- a/content/en/docs/3.3/topics/running/tls/mtls.md +++ /dev/null @@ -1,88 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Mutual TLS (mTLS) - -Many organizations have security concerns that require all network traffic -throughout their cluster be encrypted. With traditional architectures, -this was not that complicated of a requirement since internal network traffic -was fairly minimal. With microservices, we are making many more requests over -the network that must all be authenticated and secured. - -In order for services to authenticate with each other, they will each need to -provide a certificate and key that the other trusts before establishing a -connection. This action of both the client and server providing and validating -certificates is referred to as mutual TLS. - -## mTLS with $productName$ - -Since $productName$ is a reverse proxy acting as the entry point to your cluster, -$productName$ is acting as the client as it proxies requests to services upstream. - -It is trivial to configure $productName$ to simply originate TLS connections as -the client to upstream services by setting -`service: https://{{UPSTREAM_SERVICE}}` in the `Mapping` configuration. -However, in order to do mTLS with services upstream, $productName$ must also -have certificates to authenticate itself with the service. - -To do this, we can use the `TLSContext` object to get certificates from a -Kubernetes `Secret` and use those to authenticate with the upstream service. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: upstream-context -spec: - hosts: [] - secret: upstream-certs -``` - -We use `hosts: []` for this `TLSContext` since we do not want to use it to terminate -TLS connections from the client. We are just using this to load certificates for -requests upstream. - - - - The Kubernetes Secret must contain a valid TLS certificate. If the environment - variable `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) in the TLS overview. - - - -After loading the certificates, we can tell $productName$ when to use them by -setting the `tls` parameter in a `Mapping`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: upstream-mapping -spec: - hostname: "*" - prefix: /upstream/ - service: upstream-service - tls: upstream-context -``` - -Now, when $productName$ proxies a request to `upstream-service`, it will provide -the certificates in the `upstream-certs` secret for authentication when -encrypting traffic. - -## Service mesh - -As you can imagine, when you have many services in your cluster all -authenticating with each other, managing all of those certificates can become a -very big challenge. - -For this reason, many organizations rely on a service mesh for their -service-to-service authentication and encryption. - -$productName$ integrates with multiple service meshes and makes it easy to -configure mTLS to upstream services for all of them. Click the links below to -see how to configure $productName$ to do mTLS with any of these service meshes: - -- [Consul Connect](../../../../howtos/consul/) - -- [Istio](../../../../howtos/istio/) diff --git a/content/en/docs/3.3/topics/running/tls/origination.md b/content/en/docs/3.3/topics/running/tls/origination.md deleted file mode 100644 index b15dd5f8..00000000 --- a/content/en/docs/3.3/topics/running/tls/origination.md +++ /dev/null @@ -1,82 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# TLS origination - -Sometimes you may want traffic from $productName$ to your services to be encrypted. For the cases where terminating TLS at the ingress is not enough, $productName$ can be configured to originate TLS connections to your upstream services. - -## Basic configuration - -Telling $productName$ to talk to your services over HTTPS is easily configured in the `Mapping` definition by setting `https://` in the `service` field. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: basic-tls -spec: - hostname: "*" - prefix: / - service: https://example-service -``` - -## Advanced configuration using a `TLSContext` - -If your upstream services require more than basic HTTPS support (for example, providing a client certificate or -setting the minimum TLS version support) you must create a `TLSContext` for $productName$ to use when -originating TLS. For example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls-context -spec: - secret: self-signed-cert - min_tls_version: v1.3 - sni: some-sni-hostname -``` - - - - The Kubernetes Secret named by `secret` must contain a valid TLS certificate. If the - environment variable `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and the Secret contains - an invalid certificate, $productName$ will reject the `TLSContext` and prevent its use; - see [**Certificates and Secrets**](../#certificates-and-secrets) in the TLS overview. - - - -Configure $productName$ to use this `TLSContext` for connections to upstream services by setting the `tls` attribute of a `Mapping`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-with-tls-context -spec: - hostname: "*" - prefix: / - service: https://example-service - tls: tls-context -``` - -The `example-service` service must now support TLS v1.3 for $productName$ to connect. - - - - The Kubernetes Secret named by `secret` must contain a valid TLS certificate. If the - environment variable `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and the Secret contains - an invalid certificate, $productName$ will reject the `TLSContext` and prevent its use; - see [**Certificates and Secrets**](../#certificates-and-secrets) in the TLS overview. - - - - - - A `TLSContext` requires a certificate be provided, even in cases where the upstream - service does not require it (for origination) and the `TLSContext` is not being used - to terminate TLS. In this case, simply generate and provide a self-signed certificate. - - diff --git a/content/en/docs/3.3/topics/running/tls/sni.md b/content/en/docs/3.3/topics/running/tls/sni.md deleted file mode 100644 index 92e4992f..00000000 --- a/content/en/docs/3.3/topics/running/tls/sni.md +++ /dev/null @@ -1,103 +0,0 @@ -# Server Name Indication (SNI) - -$productName$ supports serving multiple `Host`s behind a single IP address, each -with their own certificate. - -This is as easy to do as creating a `Host` for each domain or subdomain you -want $productName$ to serve, getting a certificate for each, and telling -$productName$ which `Host` the route should be created for. - -The example below configures two `Host`s and assigns routes to them. - -## Configuring a `Host` - -The `Host` resources lets you separate configuration for each distinct domain -and subdomain you plan on serving behind $productName$. - -Let's start by creating a simple `Host` and providing our own certificate in -the `host-cert` secret. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: host-cert -``` - -Now let's create a second `Host` for a different domain we want to serve behind -$productName$. This second `Host` uses $AESproductName$'s automatic TLS -to get a certificate from Let's Encrypt. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: host.foo.com - acmeProvider: - email: julian@example.com -``` - -We now have two `Host`s with two different certificates. - - - A minimum version of TLS 1.1 is required to properly use SNI. When setting up your TLS configuration, be sure you are not using TLS 1.0 or older. - - -## Configuring routes - -Now that we have two domains behind $productName$, we can create routes for either -or both of them. - -We do this by setting the `hostname` attribute of a `Mapping` to the domain the -`Mapping` should be created for. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin -spec: - prefix: /httpbin/ - service: httpbin.org:80 - host_rewrite: httpbin.org - hostname: host.example.com -``` - -The above creates a `/httpbin/` endpoint for `host.example.com`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mockbin -spec: - prefix: /foo/ - service: foo-service - hostname: host.foo.com -``` - -The above creates a `/foo/` endpoint for `host.foo.com`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: frontend -spec: - hostname: "*" - prefix: /bar/ - service: bar-endpoint -``` - -The above creates a `/bar/` endpoint for all `Host`s. diff --git a/content/en/docs/3.3/topics/using/authservice.md b/content/en/docs/3.3/topics/using/authservice.md deleted file mode 100644 index cfe3598b..00000000 --- a/content/en/docs/3.3/topics/using/authservice.md +++ /dev/null @@ -1,23 +0,0 @@ -# AuthService settings - -A Mapping can pass these settings along to an [AuthService](../../running/services/auth-service). This is helpful to allow these specific configurations to apply only to certain Mappings and not globally. - -## Bypass authentication - -An AuthService can be disabled for a specific Mapping with the `bypass_auth` attribute. This will tell $productName$ to allow all requests for that Mapping through without interacting with the external auth service. This could be helpful, for example, for a public API. - -```yaml -bypass_auth: true -``` - -## Context extensions - -The `auth_context_extensions` attribute will pass the given values along to the AuthService when authentication happens. The values are arbitrary key value pairs formatted as strings. - -```yaml -auth_context_extensions: - foo: bar - baz: zing -``` - -More information is available on [the Envoy documentation on external authentication](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto.html#extensions-filters-http-ext-authz-v3-checksettings). diff --git a/content/en/docs/3.3/topics/using/canary.md b/content/en/docs/3.3/topics/using/canary.md deleted file mode 100644 index f99de1a3..00000000 --- a/content/en/docs/3.3/topics/using/canary.md +++ /dev/null @@ -1,41 +0,0 @@ -# Canary releases - -Canary releasing is a deployment pattern where a small percentage of traffic is diverted to an early ("canary") release of a particular service. This technique lets you test a release on a small subset of users, mitigating the impact of any given bug. Canary releasing also allows you to quickly roll back to a known good version in the event of an unexpected error. Detailed monitoring of core service metrics is an essential part of canary releasing, as monitoring enables the rapid detection of problems in the canary release. - -## Canary releases in Kubernetes - -Kubernetes supports a basic canary release workflow using its core objects. In this workflow, a service owner can create a Kubernetes [service](https://kubernetes.io/docs/concepts/services-networking/service/). This service can then be pointed to multiple [deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/). Each deployment can be a different version. By specifying the number of `replicas` in a given deployment, you can control how much traffic goes between different versions. For example, you could set `replicas: 3` for `v1`, and `replicas: 1` for `v2`, to ensure that 25% of traffic goes to `v2`. This approach works but is fairly coarse-grained unless you have lots of replicas. Moreover, auto-scaling doesn't work well with this strategy. - -## Canary releases in $productName$ - -$productName$ supports fine-grained canary releases. $productName$ uses a weighted round-robin scheme to route traffic between multiple services. Full metrics are collected for all services, making it easy to compare the relative performance of the canary and production. - -### The weight attribute - -The `weight` attribute specifies how much traffic for a given resource will be routed using a given mapping. Its value is an integer percentage between 0 and 100. $productName$ will balance weights to make sure that, for every resource, the mappings for that resource will have weights adding to 100%. (In the simplest case, a single mapping is guaranteed to receive 100% of the traffic no matter whether it's assigned a `weight` or not.) - -Specifying a weight only makes sense if you have multiple mappings for the same resource, and typically you would _not_ assign a weight to the "default" mapping (the mapping expected to handle most traffic): letting $productName$ assign that mapping all the traffic not otherwise spoken for tends to make life easier when updating weights. - -Here's an example, which might appear during a canary deployment: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - prefix: /backend/ - service: quotev2 - weight: 10 -``` - -In this case, the quote-backend2 will receive 10% of the requests for `/backend/`, and $productName$ will assign the remaining 90% to the quote-backend. diff --git a/content/en/docs/3.3/topics/using/circuit-breakers.md b/content/en/docs/3.3/topics/using/circuit-breakers.md deleted file mode 100644 index 97b40f57..00000000 --- a/content/en/docs/3.3/topics/using/circuit-breakers.md +++ /dev/null @@ -1,116 +0,0 @@ -# Circuit breakers - -Circuit breakers are a powerful technique to improve resilience. By preventing additional connections or requests to an overloaded service, circuit breakers limit the ["blast radius"](https://www.ibm.com/garage/method/practices/manage/practice_limited_blast_radius/) of an overloaded service. By design, $productName$ circuit breakers are distributed, i.e., different $productName$ instances do not coordinate circuit breaker information. - -## Circuit breaker configuration - -A default circuit breaking configuration can be set for all -$productName$ resources in the [`ambassador -Module`](../../running/ambassador), or set to a different value on a -per-resource basis for [`Mappings`](../mappings), -[`TCPMappings`](../tcpmappings/), and -[`AuthServices`](../../running/services/auth-service/). - -The `circuit_breakers` attribute configures circuit breaking. The following fields are supported: - -```yaml -circuit_breakers: -- priority: - max_connections: - max_pending_requests: - max_requests: - max_retries: -``` - -|Key|Default value|Description| -|---|---|---| -|`priority`|`default`|Specifies the priority to which the circuit breaker settings apply to; it can be set to either `default` or `high`.| -|`max_connections`|`1024`|Specifies the maximum number of connections that $productName$ will make to the services. In practice, this is more applicable to HTTP/1.1 than HTTP/2.| -|`max_pending_requests`|`1024`|Specifies the maximum number of requests that will be queued while waiting for a connection. In practice, this is more applicable to HTTP/1.1 than HTTP/2.| -|`max_requests`|`1024`|Specifies the maximum number of parallel outstanding requests to an upstream service. In practice, this is more applicable to HTTP/2 than HTTP/1.1.| -|`max_retries`|`3`|Specifies the maximum number of parallel retries allowed to an upstream service.| - -The `max_*` fields can be reduced to shrink the "blast radius," or -increased to enable $productName$ to handle a larger number of -concurrent requests. - -## Examples - -Circuit breakers defined on a single `Mapping`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - circuit_breakers: - - max_connections: 2048 - max_pending_requests: 2048 -``` - -Circuit breakers defined on a single `AuthService`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: AuthService -metadata: - name: dancing-walrus -spec: - auth_service: http://dancing-walrus:8500 - proto: grpc - circuit_breakers: - - max_requests: 4096 -``` - -A global circuit breaker: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - circuit_breakers: - - max_connections: 2048 - max_pending_requests: 2048 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote -``` - -## Circuit breakers and automatic retries - -Circuit breakers are best used in conjunction with [automatic retries](../retries). Here are some examples: - -* You've configured automatic retries for failed requests to a service. Your service is under heavy load, and starting to time out on servicing requests. In this case, automatic retries can exacerbate your problem, increasing the total request volume by 2x or more. By aggressively circuit breaking, you can mitigate failure in this scenario. -* To circuit break when services are slow, you can combine circuit breakers with retries. Reduce the time out for retries, and then set a circuit breaker that detects many retries. In this setup, if your service doesn't respond quickly, a flood of retries will occur, which can then trip the circuit breaker. - -Note that setting circuit breaker thresholds requires careful monitoring and experimentation. We recommend you start with conservative values for circuit breakers and adjust them over time. - -## More about circuit breakers - -Responses from a broken circuit contain the `x-envoy-overloaded` header. - -The following are the default values for circuit breaking if nothing is specified: - -```yaml -circuit_breakers: -- priority: default - max_connections: 1024 - max_pending_requests: 1024 - max_requests: 1024 - max_retries: 3 -``` - -Circuit breaker metrics are exposed in StatsD. For more information about the specific statistics, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/circuit_breaking.html). diff --git a/content/en/docs/3.3/topics/using/cors.md b/content/en/docs/3.3/topics/using/cors.md deleted file mode 100644 index 315e4694..00000000 --- a/content/en/docs/3.3/topics/using/cors.md +++ /dev/null @@ -1,155 +0,0 @@ -# Cross-Origin Resource Sharing (CORS) - -Cross-Origin resource sharing lets users request resources (e.g., images, fonts, videos) from domains outside the original domain. - -CORS configuration can be set for all $productName$ mappings in the [`ambassador Module`](../../running/ambassador), or set per [`Mapping`](../mappings). - -When the CORS attribute is set at either the `Mapping` or `Module` level, $productName$ will intercept the pre-flight `OPTIONS` request and respond with the appropriate CORS headers. This means you will not need to implement any logic in your upstreams to handle these CORS `OPTIONS` requests. - -The flow of the request will look similar to the following: -``` -Client $productName$ Upstream - | OPTIONS | | - | —————————————————> | | - | CORS_RESP | | - | <————————————————— | | - | GET /foo/ | | - | —————————————————> | ————————————> | - | | RESP | - | <————————————————————————————————— | -``` -## The `cors` attribute - -The `cors` attribute enables the CORS filter. The following settings are supported: - -- `origins`: Specifies a list of allowed domains for the `Access-Control-Allow-Origin` header. To allow all origins, use the wildcard `"*"` value. Format can be either of: - - comma-separated list, e.g. - ```yaml - origins: http://foo.example,http://bar.example - ``` - - YAML array, e.g. - ```yaml - origins: - - http://foo.example - - http://bar.example - ``` - -- `methods`: if present, specifies a list of allowed methods for the `Access-Control-Allow-Methods` header. Format can be either of: - - comma-separated list, e.g. - ```yaml - methods: POST, GET, OPTIONS - ``` - - YAML array, e.g. - ```yaml - methods: - - GET - - POST - - OPTIONS - ``` - -- `headers`: if present, specifies a list of allowed headers for the `Access-Control-Allow-Headers` header. Format can be either of: - - comma-separated list, e.g. - ```yaml - headers: Content-Type - ``` - - YAML array, e.g. - ```yaml - headers: - - Content-Type - ``` - -- `credentials`: if present with a true value (boolean), will send a `true` value for the `Access-Control-Allow-Credentials` header. - -- `exposed_headers`: if present, specifies a list of allowed headers for the `Access-Control-Expose-Headers` header. Format can be either of: - - comma-separated list, e.g. - ```yaml - exposed_headers: X-Custom-Header - ``` - - YAML array, e.g. - ```yaml - exposed_headers: - - X-Custom-Header - ``` - -- `max_age`: if present, indicated how long the results of the preflight request can be cached, in seconds. This value must be a string. - -## Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cors -spec: - prefix: /cors/ - service: cors-example - cors: - origins: http://foo.example,http://bar.example - methods: POST, GET, OPTIONS - headers: Content-Type - credentials: true - exposed_headers: X-Custom-Header - max_age: "86400" -``` - -## AuthService and Cross-Origin Resource Sharing - -When you use external authorization, each incoming request is authenticated before routing to its destination, including pre-flight `OPTIONS` requests. - -By default, many [`AuthService`](../../running/services/auth-service) implementations will deny these requests. If this is the case, you will need to add some logic to your `AuthService` to accept all CORS headers. - -For example, a possible configuration for Spring Boot 2.0.1: - -```java -@EnableWebSecurity -class SecurityConfig extends WebSecurityConfigurerAdapter { - - public void configure(final HttpSecurity http) throws Exception { - http - .cors().configurationSource(new PermissiveCorsConfigurationSource()).and() - .csrf().disable() - .authorizeRequests() - .antMatchers("**").permitAll(); - } - - private static class PermissiveCorsConfigurationSource implements CorsConfigurationSource { - /** - * Return a {@link CorsConfiguration} based on the incoming request. - * - * @param request - * @return the associated {@link CorsConfiguration}, or {@code null} if none - */ - @Override - public CorsConfiguration getCorsConfiguration(final HttpServletRequest request) { - final CorsConfiguration configuration = new CorsConfiguration(); - configuration.setAllowCredentials(true); - configuration.setAllowedHeaders(Collections.singletonList("*")); - configuration.setAllowedMethods(Collections.singletonList("*")); - configuration.setAllowedOrigins(Collections.singletonList("*")); - return configuration; - } - } -} -``` - -This is okay since CORS is being handled by $productName$ after authentication. - -The flow of this request will look similar to the following: - -``` -Client $productName$ Auth Upstream - | OPTIONS | | | - | —————————————————> | ————————————> | | - | | CORS_ACCEPT_* | | - | CORS_RESP |<——————————————| | - | <——————————————————| | | - | GET /foo/ | | | - | —————————————————> | ————————————> | | - | | AUTH_RESP | | - | | <———————————— | | - | | AUTH_ALLOW | | - | | ————————————————————————————> | - | | | RESP | - | <————————————————————————————————————————————————— | - ``` diff --git a/content/en/docs/3.3/topics/using/defaults.md b/content/en/docs/3.3/topics/using/defaults.md deleted file mode 100644 index d08a84d8..00000000 --- a/content/en/docs/3.3/topics/using/defaults.md +++ /dev/null @@ -1,32 +0,0 @@ -# Using `ambassador` `Module` defaults - -## The defaults element - -If present, the `ambassador Module` can define a set of defaults that will automatically be applied to certain resources: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - class1: # This is a class. Different resource types will look in different classes. - key1: value1 # Within a class, you can set different keys. - key2: value2 - ... - class2: - ... - top_key1: value1 # If a key isn't found in a resource's class, the system will look in the - top_key2: value2 # toplevel defaults dictionary for it. -``` - -### Mapping - -Currently, only the `Mapping` resource uses the `defaults` mechanism. `Mapping` looks first for defaultable resources in the `httpmapping` class, including: - -- [`add_request_headers`](../../using/headers/add-request-headers) -- [`add_response_headers`](../../using/headers/add-response-headers) -- [`remove_request_headers`](../../using/headers/remove-request-headers) -- [`remove_response_headers`](../../using/headers/remove-response-headers) diff --git a/content/en/docs/3.3/topics/using/gateway-api.md b/content/en/docs/3.3/topics/using/gateway-api.md deleted file mode 100644 index 5e92cd0d..00000000 --- a/content/en/docs/3.3/topics/using/gateway-api.md +++ /dev/null @@ -1,19 +0,0 @@ -# Gateway API - -## Using the Gateway API - -$productName$ now supports a limited subset of the new `v1alpha1` [Gateway API](https://gateway-api.sigs.k8s.io/). -Note that the Gateway API is not supported when `AMBASSADOR_LEGACY_MODE` is set. - -Support is currently limited to the following fields, however this will expand in future releases: - - - `Gateway.spec.listeners.port` - - `HTTPRoute.spec.rules.matches.path.type` (`Exact`, `Prefix`, and `RegularExpression`) - - `HTTPRoute.spec.rules.matches.path.value` - - `HTTPRoute.spec.rules.matches.header.type` (`Exact` and `RegularExpression`) - - `HTTPRoute.spec.rules.matches.header.values` - - `HTTPRoute.spec.rules.forwardTo.serviceName` - - `HTTPRoute.spec.rules.forwardTo.port` - - `HTTPRoute.spec.rules.forwardTo.weight` - -Please see the [specification](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/) for more details. diff --git a/content/en/docs/3.3/topics/using/headers/add-request-headers.md b/content/en/docs/3.3/topics/using/headers/add-request-headers.md deleted file mode 100644 index c6ad4956..00000000 --- a/content/en/docs/3.3/topics/using/headers/add-request-headers.md +++ /dev/null @@ -1,77 +0,0 @@ -# Add request headers - -$productName$ can add a dictionary of HTTP headers that can be added to each request that is passed to a service. - -## The `add_request_headers` attribute - -The `add_request_headers` attribute is a dictionary of `header`: `value` pairs. The `value` can be a `string`, `bool` or `object`. When it is an `object`, the object should have a `value` property, which is the actual header value, and the remaining attributes are additional envoy properties. - -Envoy dynamic values `%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%` and `%PROTOCOL%` are supported, in addition to static values. - -`add_request_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -### Mapping example - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: "*" - prefix: /backend/ - add_request_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-static-2: - value: This the test header #same as above "x-test-static header" - x-test-object: - value: This the value - append: False #True by default - service: quote - ``` - -will add the protocol, client IP, and a static header to `/backend/`. - -### Defaults example - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - add_request_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-static-2: - value: This the test header #same as above "x-test-static header" - x-test-object: - value: This the value - append: False #True by default ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - hostname: "*" - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - hostname: "*" - prefix: /backend2/ - service: quote -``` - -This example will add the same headers for both mappings. diff --git a/content/en/docs/3.3/topics/using/headers/add-response-headers.md b/content/en/docs/3.3/topics/using/headers/add-response-headers.md deleted file mode 100644 index 236ace61..00000000 --- a/content/en/docs/3.3/topics/using/headers/add-response-headers.md +++ /dev/null @@ -1,73 +0,0 @@ -# Add response headers - -$productName$ can add a dictionary of HTTP headers that can be added to each response that is returned to the client. - -## The `add_response_headers` attribute - -The `add_response_headers` attribute is a dictionary of `header`: `value` pairs. The `value` can be a `string`, `bool` or `object`. When it is an `object`, the object should have a `value` property, which is the actual header value, and the remaining attributes are additional envoy properties. - -Envoy dynamic values `%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%` and `%PROTOCOL%` are supported, in addition to static values. - -`add_response_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -### Mapping example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - add_response_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-object: - append: False - value: this is from object header config - service: quote -``` - -will add the protocol, client IP, and a static header to the response returned to the client. - -### Defaults example - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - add_response_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-object: - append: False - value: this is from object header config ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - hostname: "*" - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - hostname: "*" - prefix: /backend2/ - service: quote -``` - -This example will add the same headers for both mappings. diff --git a/content/en/docs/3.3/topics/using/headers/headers.md b/content/en/docs/3.3/topics/using/headers/headers.md deleted file mode 100644 index 126653b0..00000000 --- a/content/en/docs/3.3/topics/using/headers/headers.md +++ /dev/null @@ -1,76 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Header-based routing - -$productName$ can route to target services based on HTTP headers with the `headers` and `regex_headers` specifications. Multiple mappings with different annotations can be applied to construct more complex routing rules. - -## The `headers` annotation - -The `headers` attribute is a dictionary of `header`: `value` pairs. $productName$ will only allow requests that match the specified `header`: `value` pairs to reach the target service. - -### Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - headers: - x-quote-mode: backend - x-random-header: datawire -``` - -will allow requests to /backend/ to succeed only if the x-quote-mode header has the value backend and the x-random-header has the value `datawire`. - - - 1.x versions of the Ambassador Edge Stack could test for the existence of a header using x-sample-header:true. Since 2.0, the same functionality is achieved by using regex_headers. - - -## Regex headers - -You can also set the `value` of a regex header to `".*"` to test for the existence of a header. - -### Conditional example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-mode -spec: - prefix: /backend/ - service: quote-mode - regex_headers: - x-quote-mode: ".*" - ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-regular -spec: - prefix: /backend/ - service: quote-regular -``` - -will send requests that contain the x-quote-mode header to the quote-mode target, while routing all other requests to the quote-regular target. - -The following mapping will route mobile requests from Android and iPhones to a mobile service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - regex_headers: - user-agent: ".*(iPhone|(a|A)ndroid).*" - prefix: /backend/ - service: quote -``` diff --git a/content/en/docs/3.3/topics/using/headers/host.md b/content/en/docs/3.3/topics/using/headers/host.md deleted file mode 100644 index 5a8dd02c..00000000 --- a/content/en/docs/3.3/topics/using/headers/host.md +++ /dev/null @@ -1,76 +0,0 @@ -# Host headers - -$productName$ supports several different methods for managing the HTTP `Host` header. - -## Using `host` and `host_regex` - -A mapping that specifies the `host` attribute will take effect _only_ if the HTTP `Host` header matches the value in the `host` attribute. If `host_regex` is `true`, the `host` value is taken to be a regular expression. Otherwise, an exact string match is required. - -You may have multiple mappings listing the same resource but different `host` attributes to effect `Host`-based routing. An example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote1 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend-2 -spec: - prefix: /backend/ - host: quote.datawire.io - service: quote2 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend-3 -spec: - prefix: /backend/ - host: "^quote[2-9]\\.datawire\\.io$" - host_regex: true - service: quote3 -``` - -will map requests for `/` to - -- the `quote2` service if the `Host` header is `quote.datawire.io`; -- the `quote3` service if the `Host` header matches `^quote[2-9]\\.datawire\\.io$`; and to -- the `quote1` service otherwise. - -Note that enclosing regular expressions in quotes can be important to prevent backslashes from being doubled. - -## Using `host_rewrite` - -By default, the `Host` header is not altered when talking to the service -- whatever `Host` header the client gave to $productName$ will be presented to the service. For many microservices, this will be fine, but if you use $productName$ to route to services that use the `Host` header for routing, it's likely to fail (legacy monoliths are particularly susceptible to this, as well as external services). You can use `host_rewrite` to force the `Host` header to whatever value that such target services need. - -An example: the default $productName$ configuration includes the following mapping for `httpbin.org`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin -spec: - prefix: /httpbin/ - service: httpbin.org:80 - host_rewrite: httpbin.org -``` - -As it happens, `httpbin.org` is virtually hosted, and it simply _will not_ function without a `Host` header of `httpbin.org`, which means that the `host_rewrite` attribute is necessary here. - -## `host` and `method` - -Internally: - -- the `host` attribute becomes a `header` match on the `:authority` header; and -- the `method` attribute becomes a `header` match on the `:method` header. - -You will see these headers in the diagnostic service if you use the `method` or `host` attributes. diff --git a/content/en/docs/3.3/topics/using/headers/remove-request-headers.md b/content/en/docs/3.3/topics/using/headers/remove-request-headers.md deleted file mode 100644 index 62603756..00000000 --- a/content/en/docs/3.3/topics/using/headers/remove-request-headers.md +++ /dev/null @@ -1,57 +0,0 @@ -# Remove request headers - -$productName$ can remove a list of HTTP headers that would be sent to the upstream from the request. - -## The `remove_request_headers` attribute - -The `remove_request_headers` attribute takes a list of keys used to match to the header. - -`remove_request_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -## Mapping example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - remove_request_headers: - - authorization - service: quote -``` - -will drop the header with key `authorization`. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - remove_request_headers: - - authorization ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - prefix: /backend2/ - service: quote -``` - -This is the same as the mapping example, but the headers will be removed for both mappings. diff --git a/content/en/docs/3.3/topics/using/headers/remove-response-headers.md b/content/en/docs/3.3/topics/using/headers/remove-response-headers.md deleted file mode 100644 index 16b18569..00000000 --- a/content/en/docs/3.3/topics/using/headers/remove-response-headers.md +++ /dev/null @@ -1,57 +0,0 @@ -# Remove response headers - -$productName$ can remove a list of HTTP headers that would be sent to the client in the response (e.g. default `x-envoy-upstream-service-time`). - -## The `remove_response_headers` attribute - -The `remove_response_headers` attribute takes a list of keys used to match to the header. - -`remove_request_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -## Mapping example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - remove_response_headers: - - x-envoy-upstream-service-time - service: quote -``` - -will drop the header with key `x-envoy-upstream-service-time`. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - remove_response_headers: - - x-envoy-upstream-service-time ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - prefix: /backend2/ - service: quote -``` - -This is the same as the mapping example, but the headers will be removed for both mappings. diff --git a/content/en/docs/3.3/topics/using/index.md b/content/en/docs/3.3/topics/using/index.md deleted file mode 100644 index d4f09a83..00000000 --- a/content/en/docs/3.3/topics/using/index.md +++ /dev/null @@ -1,32 +0,0 @@ -# Using $productName$ - -Application development teams use $productName$ to manage edge policies associated with a specific service. This section of the documentation covers core $productName$ elements that are typically used by the application development team. - -* [Introduction to Mappings](intro-mappings) The `Mapping` resource is the core resource used by every application development team. -* Mapping Configuration: - * [Automatic Retries](retries) - * [Canary Releases](canary) - * [Circuit Breakers](circuit-breakers) - * [Cross Origin Resource Sharing](cors) - * HTTP Headers - * [Header-based Routing](headers/headers) - * [Host Header](headers/host) - * [Adding Request Headers](headers/add-request-headers) - * [Adding Response Headers](headers/add-response-headers) - * [Removing Request Headers](headers/remove-request-headers) - * [Remove Response Headers](headers/remove-response-headers) - * [Query Parameter Based Routing](query-parameters) - * [Keepalive](keepalive) - * Protocols - * [TCP](tcpmappings) - * gRPC, HTTP/1.0, gRPC-Web, WebSockets - * [RegEx-based Routing](prefix-regex) - * [Redirects](redirects) - * [Rewrites](rewrites) - * [Timeouts](timeouts) - * [Traffic Shadowing](shadowing) -* [Advanced Mapping Configuration](mappings) -* Rate Limiting - * [Introduction to Rate Limits](rate-limits/) -* [Developer Portal](../../tutorials/dev-portal-tutorial) -* [Gateway API](gateway-api) diff --git a/content/en/docs/3.3/topics/using/intro-mappings.md b/content/en/docs/3.3/topics/using/intro-mappings.md deleted file mode 100644 index 51656052..00000000 --- a/content/en/docs/3.3/topics/using/intro-mappings.md +++ /dev/null @@ -1,148 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Introduction to the Mapping resource - -$productName$ is designed around a [declarative, self-service management model](../../concepts/gitops-continuous-delivery). The core resource used to support application development teams who need to manage the edge with $productName$ is the `Mapping` resource. - - - Remember that Listener and Host resources are -  required for a functioning $productName$ installation that can route traffic!
- Learn more about Listener.
- Learn more about Host. - - -## Quick example - -At its core a `Mapping` resource maps a `resource` to a `service`: - -| Required attribute | Description | -| :------------------------ | :------------------------ | -| `name` | is a string identifying the `Mapping` (e.g. in diagnostics) | -| [`prefix`](#resources) | is the URL prefix identifying your [resource](#resources) | -| [`service`](#services) | is the name of the [service](#services) handling the resource; must include the namespace (e.g. `myservice.othernamespace`) if the service is in a different namespace than $productName$ | - -These resources are defined as Kubernetes Custom Resource Definitions. Here's a simple example that maps all requests to `/httpbin/` to the `httpbin.org` web service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin-mapping -spec: - prefix: /httpbin/ - service: http://httpbin.org -``` - -## Applying a Mapping resource - -A `Mapping` resource can be managed using the same workflow as any other Kubernetes resources (e.g., `service`, `deployment`). For example, if the above `Mapping` is saved into a file called `httpbin-mapping.yaml`, the following command will apply the configuration directly to $productName$: - -``` -kubectl apply -f httpbin-mapping.yaml -``` - -For production use, the general recommended best practice is to store the file in a version control system and apply the changes with a continuous deployment pipeline. For more detail, see [the Ambassador Operating Model](../../concepts/gitops-continuous-delivery). - -## Extending Mappings - -`Mapping` resources support a rich set of annotations to customize the specific routing behavior. Here's an example service for implementing the CQRS pattern (using HTTP): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-get -spec: - prefix: /cqrs/ - method: GET - service: getcqrs ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-put -spec: - prefix: /cqrs/ - method: PUT - service: putcqrs -``` - -More detail on each of the available annotations are discussed in subsequent sections. - -## Resources - -To $productName$, a `resource` is a group of one or more URLs that all share a common prefix in the URL path. For example: - -``` -https://ambassador.example.com/resource1/foo -https://ambassador.example.com/resource1/bar -https://ambassador.example.com/resource1/baz/zing -https://ambassador.example.com/resource1/baz/zung -``` - -all share the `/resource1/` path prefix, so it can be considered a single resource. On the other hand: - -``` -https://ambassador.example.com/resource1/foo -https://ambassador.example.com/resource2/bar -https://ambassador.example.com/resource3/baz/zing -https://ambassador.example.com/resource4/baz/zung -``` - -share only the prefix `/` -- you _could_ tell $productName$ to treat them as a single resource, but it's probably not terribly useful. - -Note that the length of the prefix doesn't matter: if you want to use prefixes like `/v1/this/is/my/very/long/resource/name/`, go right ahead, $productName$ can handle it. - -Also note that $productName$ does not actually require the prefix to start and end with `/` -- however, in practice, it's a good idea. Specifying a prefix of - -``` -/man -``` - -would match all of the following: - -``` -https://ambassador.example.com/man/foo -https://ambassador.example.com/mankind -https://ambassador.example.com/man-it-is/really-hot-today -https://ambassador.example.com/manohmanohman -``` - -which is probably not what was intended. - -## Services - -$productName$ routes traffic to a `service`. A `service` is defined as: - -``` -[scheme://]service[.namespace][:port] -``` - -Where everything except for the `service` is optional. - -- `scheme` can be either `http` or `https`; if not present, the default is `http`. -- `service` is the name of a service (typically the service name in Kubernetes or Consul); it is not allowed to contain the `.` character. -- `namespace` is the namespace in which the service is running. Starting with $productName$ 1.0.0, if not supplied, it defaults to the namespace in which the Mapping resource is defined. The default behavior can be configured using the [`ambassador` Module](../../running/ambassador). When using a Consul resolver, `namespace` is not allowed. -- `port` is the port to which a request should be sent. If not specified, it defaults to `80` when the scheme is `http` or `443` when the scheme is `https`. Note that the [resolver](../../running/resolvers) may return a port in which case the `port` setting is ignored. - -Note that while using `service.namespace.svc.cluster.local` may work for Kubernetes resolvers, the preferred syntax is `service.namespace`. - -## Best practices for configuration - -$productName$'s configuration is assembled from multiple YAML blocks which are managed by independent application teams. This implies: - -- $productName$'s configuration should be under version control. - - While you can always read back the $productName$'s configuration from Kubernetes or its diagnostic service, the $productName$ will not do versioning for you. - -- Be aware that the $productName$ tries to not start with a broken configuration, but it's not perfect. - - Gross errors will result in $productName$ refusing to start, in which case `kubectl logs` will be helpful. However, it's always possible to e.g. map a resource to the wrong service, or use the wrong `rewrite` rules. $productName$ can't detect that on its own, although its diagnostic pages can help you figure it out. - -- Be careful of mapping collisions. - - If two different developers try to map `/user/` to something, this can lead to unexpected behavior. $productName$'s canary-deployment logic means that it's more likely that traffic will be split between them than that it will throw an error -- again, the diagnostic service can help you here. - -**Note:** Unless specified, mapping attributes cannot be applied to any other resource type. diff --git a/content/en/docs/3.3/topics/using/keepalive.md b/content/en/docs/3.3/topics/using/keepalive.md deleted file mode 100644 index d75e96ba..00000000 --- a/content/en/docs/3.3/topics/using/keepalive.md +++ /dev/null @@ -1,70 +0,0 @@ -# Keepalive - -Keepalive option indicates whether `SO_KEEPALIVE` on the socket should be enabled. - -## Keepalive configuration - -Keepalive configuration can be set for all $productName$ mappings in the [`ambassador Module`](../../running/ambassador) or set per [`Mapping`](../mappings). - -The `keepalive` attribute configures keepalive. The following fields are supported: - -```yaml -keepalive: - idle_time: - interval: - probes: -``` - -### `idle_time` - -(Default: `7200`) The number of seconds a connection needs to be idle before keep-alive probes start being sent. - -### `interval` - -(Default: `75`) The number of seconds between keep-alive probes. - -### `probes` - -(Default: `9`) is the maximum number of keepalive probes to send without response before deciding the connection is dead. - -## Examples - -Keepalive probes defined on a single mapping: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - keepalive: - idle_time: 100 - interval: 10 - probes: 9 -``` - -A global keepalive configuration: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - keepalive: - idle_time: 100 - interval: 10 - probes: 9 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote -``` diff --git a/content/en/docs/3.3/topics/using/mappings.md b/content/en/docs/3.3/topics/using/mappings.md deleted file mode 100644 index f930fc62..00000000 --- a/content/en/docs/3.3/topics/using/mappings.md +++ /dev/null @@ -1,189 +0,0 @@ -# Advanced Mapping configuration - -$productName$ is designed so that the author of a given Kubernetes service can easily and flexibly configure how traffic gets routed to the service. The core abstraction used to support service authors is a mapping, which maps a target backend service to a given host or prefix. For Layer 7 protocols such as HTTP, gRPC, or WebSockets, the `Mapping` resource is used. For TCP, the `TCPMapping` resource is used. - -$productName$ _must_ have one or more mappings defined to provide access to any services at all. The name of the mapping must be unique. - -## System-wide defaults for Mappings - -Certain aspects of mappings can be set system-wide using the `defaults` element of the `ambassador Module`: -see [using defaults](../../using/defaults) for more information. The `Mapping` element will look first in -the `httpmapping` default class. - -## Mapping evaluation order - -$productName$ sorts mappings such that those that are more highly constrained are evaluated before those less highly constrained. The prefix length, the request method, constraint headers, and query parameters are all taken into account. - -If absolutely necessary, you can manually set a `precedence` on the mapping (see below). In general, you should not need to use this feature unless you're using the `regex_headers` or `host_regex` matching features. If there's any question about how $productName$ is ordering rules, the diagnostic service is a good first place to look: the order in which mappings appear in the diagnostic service is the order in which they are evaluated. - -## Optional fallback Mapping - -$productName$ will respond with a `404 Not Found` to any request for which no mapping exists. If desired, you can define a fallback "catch-all" mapping so all unmatched requests will be sent to an upstream service. - -For example, defining a mapping with only a `/` prefix will catch all requests previously unhandled and forward them to an external service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: catch-all -spec: - prefix: / - service: https://www.getambassador.io -``` - -### Using `precedence` - -$productName$ sorts mappings such that those that are more highly constrained are evaluated before those less highly constrained. The prefix length, the request method, and the constraint headers are all taken into account. These mechanisms, however, may not be sufficient to guarantee the correct ordering when regular expressions or highly complex constraints are in play. - -For those situations, a `Mapping` can explicitly specify the `precedence`. A `Mapping` with no `precedence` is assumed to have a `precedence` of 0; the higher the `precedence` value, the earlier the `Mapping` is attempted. - -If multiple `Mapping`s have the same `precedence`, $productName$'s normal sorting determines the ordering within the `precedence`; however, there is no way that $productName$ can ever sort a `Mapping` with a lower `precedence` ahead of one at a higher `precedence`. - -### Using `tls` - -To originate TLS, use a `service` with an `https://` prefix. By itself, this will cause $productName$ to originate TLS without presenting a client certificate to the upstream service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-no-cert -spec: - prefix: /prefix/ - service: https://upstream/ -``` - -If you do need to supply a client certificate, you will also need to set `tls` to the name of a defined TLS context. The client certificate given in that context will be presented to the upstream service. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-with-cert -spec: - prefix: /prefix/ - service: https://upstream/ - tls: upstream-cert-context -``` - -(If `tls` is present, $productName$ will originate TLS even if the `service` does not have an `https://` prefix.) - -### Using `cluster_tag` - -If the `cluster_tag` attribute is present, its value will be prepended to cluster names generated from -the `Mapping`. This provides a simple mechanism for customizing the `cluster` name when working with metrics. - -## Using `dns_type` - -If the `dns_type` attribute is present, its value will determine how the DNS is used when locating the upstream service. Valid values are: - -- `strict_dns` (the default): The DNS result is assumed to define the exact membership of the cluster. For example, if DNS returns three IP addresses, the cluster is assumed to have three distinct upstream hosts. If a successful DNS query returns no hosts, the cluster is assumed to be empty. `strict_dns` makes sense for situations like a Kubernetes service, where DNS resolution is fast and returns a relatively small number of IP addresses. - -- `logical_dns`: Instead of assuming that the DNS result defines the full membership of the cluster, every new connection simply uses the first IP address returned by DNS. `logical_dns` makes sense for a service with a large number of IP addresses using round-robin DNS for upstream load balancing: typically each DNS query returns a different first result, and it is not necessarily possible to know the full membership of the cluster. With `logical_dns`, no attempt is made to garbage-collect connections: they will stay open until the upstream closes them. - -If `dns_type` is not given, `strict_dns` is the default, as this is the most conservative choice. When interacting with large web services with many IP addresses, switching to `logical_dns` may be a better choice. For more on the different types of DNS, see the [`strict_dns` Envoy documentation] or the [`logical_dns` Envoy documentation]. - -[`strict_dns` Envoy documentation]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/service_discovery#strict-dns -[`logical_dns` Envoy documentation]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/service_discovery#logical-dns - - -## Namespaces and Mappings - -If `AMBASSADOR_NAMESPACE` is correctly set, $productName$ can map to services in other namespaces by taking advantage of Kubernetes DNS: - -- `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. - -### Linkerd interoperability (`add_linkerd_headers`) - -When using Linkerd, requests going to an upstream service need to include the `l5d-dst-override` header to ensure that Linkerd will route them correctly. Setting `add_linkerd_headers` does this automatically, based on the `service` attribute in the `Mapping`. - -If `add_linkerd_headers` is not specified for a given `Mapping`, the default is taken from the `ambassador`[Module](../../running/ambassador). The overall default is `false`: you must explicitly enable `add_linkerd_headers` for $productName$ to add the header for you (although you can always add it yourself with `add_request_headers`, of course). - -### "Upgrading" to non-HTTP protocols (`allow_upgrade`) - -HTTP has [a mechanism][upgrade-mechanism] where the client can say -`Connection: upgrade` / `Upgrade: PROTOCOL` to switch ("upgrade") from -the current HTTP version to a different one, or even a different -protocol entirely. $productName$ itself understands and can handle the -different HTTP versions, but for other protocols you need to tell -$productName$ to get out of the way, and let the client speak that -protocol directly with your upstream service. You can do this by -setting the `allow_upgrade` field to a case-insensitive list of -protocol names $productName$ will allow switching to from HTTP. After -the upgrade, $productName$ does not interpret the traffic, and behaves -similarly to how it does for `TCPMapping`s. - -[upgrade-mechanism]: https://tools.ietf.org/html/rfc7230#section-6.7 - -This "upgrade" mechanism is a useful way of adding HTTP-based -authentication and access control to another protocol that might not -support authentication; for this reason the designers of the WebSocket -protocol made this "upgrade" mechanism the *only* way of initiating a -WebSocket connection. In a Mapping for an upstream service that -supports WebSockets, you would write - -```yaml -allow_upgrade: -- websocket -``` - -The Kubernetes apiserver itself uses this "upgrade" mechanism to -perform HTTP authentication before switching to SPDY for endpoint used -by `kubectl exec`; if you wanted to use $productName$ to expose the -Kubernetes apiserver such that `kubectl exec` functions, you would -write - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: apiserver -spec: - hostname: "*" - service: https://kubernetes.default - prefix: / - allow_upgrade: - - spdy/3.1 -``` - -There is a deprecated setting `use_websocket`; setting `use_websocket: -true` is equivalent to setting `allow_upgrade: ["websocket"]`. - -## DNS configuration for Mappings - -`respect_dns_ttl` can be set to `true` to force the DNS refresh rate for this `Mapping` to be set to the record’s TTL obtained from DNS resolution. -- Allowed values: `true` or `false` -- Default: `false` - - -`dns_type` can be used to configure the service discovery type between Strict DNS and Logical DNS. You can -- Allowed values: - - `strict_dns`: Ambassador will continuously and asynchronously resolve the specified DNS targets. - - `logical_dns`: Similar to `strict_dns`, but only uses the first IP address returned when a new connection needs to be initiated and Connections are never drained. More optimal for large scale web services that must be accessed via DNS. -- Default: `strict_dns` - - -For more information on the differences between dns types, see [the Envoy documentation for service discovery](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/service_discovery.html). - -> **Note:** When the [endpoint resolver](../../running/resolvers/#the-kubernetes-endpoint-resolver) is used in a `Mapping`, `dns_type` will be ignored in favor of the endpoint resolver's service discovery. - - - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: dnsoverwrite -spec: - service: quote - prefix: /backend/ - dns_type: logical_dns - respect_dns_ttl: true -``` diff --git a/content/en/docs/3.3/topics/using/method.md b/content/en/docs/3.3/topics/using/method.md deleted file mode 100644 index 94185dcd..00000000 --- a/content/en/docs/3.3/topics/using/method.md +++ /dev/null @@ -1,26 +0,0 @@ -# Method-based routing - -$productName$ supports routing based on the HTTP method and regular expression. - -## Using `method` - -The `method` annotation specifies the specific HTTP method for a mapping. The value of the `method` annotation must be in all upper case. - -For example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: get -spec: - hostname: "*" - prefix: /backend/get_only/ - method: GET - service: quote -``` - -## Using `method_regex` - -When `method_regex` is set to `true`, the value of the `method` annotation will be interpreted as a regular expression. diff --git a/content/en/docs/3.3/topics/using/prefix-regex.md b/content/en/docs/3.3/topics/using/prefix-regex.md deleted file mode 100644 index 04a6e4b8..00000000 --- a/content/en/docs/3.3/topics/using/prefix-regex.md +++ /dev/null @@ -1,25 +0,0 @@ -# Prefix regex - -## Using `prefix` and `prefix_regex` - -When the `prefix_regex` attribute is set to `true`, $productName$ configures a [regex route](https://www.envoyproxy.io/docs/envoy/v1.5.0/api-v1/route_config/route#route) instead of a prefix route in Envoy. **This means the entire path must match the regex specified, not only the prefix.** - -## Example with a version in the URL - -If the version is a path parameter and the resources are served by different services, then - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: qotm -spec: - prefix: "/(v1|v2)/qotm/.*" - prefix_regex: true - service: qotm -``` - -will map requests to both `/v1` and `/v2` to the `qotm` service. - -Note that enclosing regular expressions in quotes can be important to prevent backslashes from being doubled. diff --git a/content/en/docs/3.3/topics/using/query-parameters.md b/content/en/docs/3.3/topics/using/query-parameters.md deleted file mode 100644 index 6b880fd4..00000000 --- a/content/en/docs/3.3/topics/using/query-parameters.md +++ /dev/null @@ -1,69 +0,0 @@ -# Query parameter-based routing - -$productName$ can route to target services based on HTTP query parameters with the `query_parameters` and `regex_query_parameters` specifications. Multiple mappings with different annotations can be applied to construct more complex routing rules. - -## The `query_parameters` annotation - -The `query_parameters` attribute is a dictionary of `query_parameter`: `value` pairs. $productName$ will only allow requests that match the specified `query_parameter`: `value` pairs to reach the target service. - -You can also set the `value` of a query parameter to `true` to test for the existence of a query parameter. - -### A basic example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - query_parameters: - quote-mode: backend - random-query-parameter: datawire -``` - -This will allow requests to /backend/ to succeed only if the `quote-mode` query parameter has the value `backend` and the `random-query-parameter` has the value `datawire`. - -## `regex_query_parameters` - -The following mapping will route requests with the `quote-mode` header that contain values that match the regex. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - regex_query_parameters: - quote-mode: "^[a-z].*" - prefix: /backend/ - service: quote -``` - -### A conditional example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-mode -spec: - prefix: /backend/ - service: quote-mode - regex_query_parameters: - quote-mode: .* ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-regular -spec: - prefix: /backend/ - service: quote-regular -``` - -This will send requests that contain the `quote-mode` query parameter (with any value) to the `quote-mode` target, while routing all other requests to the `quote-regular` target. diff --git a/content/en/docs/3.3/topics/using/rate-limits/index.md b/content/en/docs/3.3/topics/using/rate-limits/index.md deleted file mode 100644 index b65f8c5d..00000000 --- a/content/en/docs/3.3/topics/using/rate-limits/index.md +++ /dev/null @@ -1,199 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Basic rate limiting - -Rate limiting in $productName$ is composed of two parts: - -* The [`RateLimitService`](../../running/services/rate-limit-service) resource tells $productName$ what external service - to use for rate limiting. - - If $productName$ cannot contact the rate limit service, it will allow the request to be processed as if there were no rate limit service configuration. - -* _Labels_ that get attached to requests. A label is basic metadata that - is used by the `RateLimitService` to decide which limits to apply to - the request. - - - These labels require Mapping resources with apiVersion - getambassador.io/v2 or newer — if you're updating an old installation, check the - apiVersion! - - -Labels are grouped according to _domain_ and _group_: - -```yaml -labels: - "domain1": - - "group1": - - "my_label_specifier_1" - - "my_label_specifier_2" - - "group2": - - "my_label_specifier_3" - - "my_label_specifier_4" - "domain2": - - ... -``` - -The names of domains and groups are not interpreted by $productName$ in any way: -they are solely there to help configuration authors remember the different groupings. -Note that **at present, rate limiting supports just one domain**: the name of the -domain must be configured in the [`RateLimitService`](../../running/services/rate-limit-service). - - - -## Attaching labels to requests - -There are two ways of setting labels on a request: - -1. You can set labels on an individual [`Mapping`](../mappings). These labels - will only apply to requests that use that `Mapping`. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Mapping - metadata: - name: foo-mapping - spec: - hostname: "*" - prefix: /foo/ - service: foo - labels: - "domain1": - - "group1": - - "my_label_specifier_1" - - "my_label_specifier_2" - - "group2": - - "my_label_specifier_3" - - "my_label_specifier_4" - "domain2": - - ... - ``` - -2. You can set global labels in the [`ambassador` `Module`](../../running/ambassador). - These labels will apply to _every_ request that goes through $productName$. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - spec: - config: - default_labels: - "domain1": - defaults: - - "my_label_specifier_a" - - "my_label_specifier_b" - "domain2": - defaults: - - "my_label_specifier_c" - - "my_label_specifier_d" - ``` - - If a `Mapping` and the defaults both give label groups for the same domain, the - default labels are prepended to each label group from the `Mapping`. If the `Mapping` - does not give any labels for that domain, the global labels are placed into a new - label group named "default" for that domain. - -Each label group is a list of labels; each label is a key/value pair. Since the label -group is a list rather than a map: -- it is possible to have multiple labels with the same key, and -- the order of labels matters. - -> Note: The terminology used by the Envoy documentation differs from -> the terminology used by $productName$: -> -> | $productName$ | Envoy | -> |-----------------|-------------------| -> | label group | descriptor | -> | label | descriptor entry | -> | label specifier | rate limit action | - -The `Mapping`s' listing of the groups of specifiers have names for the -groups; the group names are useful for humans dealing with the YAML, -but are ignored by $productName$, all $productName$ cares about are the -*contents* of the groupings of label specifiers. - -There are 5 types of label specifiers in $productName$: - - - -1. `source_cluster` - - ```yaml - source_cluster: - key: source_cluster - ``` - - Sets the label `source_cluster=«Envoy source cluster name»"`. The Envoy - source cluster name is the name of the Envoy cluster that the request came - in on. - - The syntax of this label currently _requires_ `source_cluster: {}`. - -2. `destination_cluster` - - ```yaml - destination_cluster: - key: destination_cluster - ``` - - Sets the label `destination_cluster=«Envoy destination cluster name»"`. The Envoy - destination cluster name is the name of the Envoy cluster to which the `Mapping` - routes the request. You can get the name for a cluster from the - [diagnostics service](../../running/diagnostics). - - The syntax of this label currently _requires_ `destination_cluster: {}`. - -3. `remote_address` - - ```yaml - remote_address: - key: remote_address - ``` - - Sets the label `remote_address=«IP address of the client»"`. The IP address of - the client will be taken from the `X-Forwarded-For` header, to correctly manage - situations with L7 proxies. This requires that $productName$ be correctly - [configured to communicate](../../../howtos/configure-communications). - - The syntax of this label currently _requires_ `remote_address: {}`. - -4. `request_headers` - - ```yaml - request_headers: - header_name: "header-name" - key: mykey - ``` - - If a header named `header-name` is present, set the label `mykey=«value of the header»`. - If no header named `header-name` is present, **the entire label group is dropped**. - -5. `generic_key` - - ```yaml - generic_key: - key: mykey - value: myvalue - ``` - - Sets the label `«mykey»=«myval»`. Note that supplying a `key` is supported only - with the Envoy V3 API. - -## Rate limiting requests based on their labels - -This is determined by your `RateLimitService` implementation. See the -[Basic Rate Limiting tutorial](../../../howtos/rate-limiting-tutorial) for an -example `RateLimitService` implementation for $productName$. - -If you'd rather not write your own `RateLimitService` implementation, -$AESproductName$ provides a `RateLimitService` implementation that is -configured by a `RateLimit` custom resource. See the -[$AESproductName$ RateLimit Reference](/docs/edge-stack/latest/topics/using/rate-limits/rate-limits/) -for more information. diff --git a/content/en/docs/3.3/topics/using/redirects.md b/content/en/docs/3.3/topics/using/redirects.md deleted file mode 100644 index f55c467d..00000000 --- a/content/en/docs/3.3/topics/using/redirects.md +++ /dev/null @@ -1,142 +0,0 @@ -# Redirects - -$productName$ can perform 3xx redirects on `Mapping`s to a different host, with various options to redirect the path and to return a different 3xx response code instead of the default 301. - -## Schema - -| Name | Type | Description | -| --- | --- | --- | -| `spec.host_redirect` | Boolean | This is *required* to be set to `true` to use any type of redirect, otherwise the request will be proxied instead of redirected. | -| `spec.path_redirect` | String | Optional, changes the path for the redirect. | -| `spec.prefix_redirect` | String | Optional, matches the `prefix` value and replaces it with the `prefix_redirect` value. | -| `spec.regex_redirect` | String | Optional, uses regex to match and replace the `prefix` value. | -| `spec.redirect_response_code` | Integer | Optional, changes the response code from the default 301, valid values are 301, 302, 303, 307, and 308. | -| `spec.config. x_forwarded_proto_redirect` | Boolean | Redirect only the originating HTTP requests to HTTPS, allowing the originating HTTPS requests to pass through. | -| `spec.config. use_remote_address` | Boolean | Required to be set to `false` to use the `x_forwarded_proto_redirect` feature. | - -## Examples - -### Basic redirect - -To effect any type of HTTP `Redirect`, the `Mapping` *must* set `host_redirect` to `true`, with `service` set to the host to which the client should be redirected: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - prefix: /redirect/ - service: httpbin.org - host_redirect: true - hostname: '*' -``` - -Using this `Mapping`, a request to `http://$AMBASSADOR_URL/redirect/` will be redirected to `http://httpbin.org/redirect/`. - -> As always with $productName$, the trailing `/` on any URL with a -`Mapping` is required! - -### Path redirect - -The `Mapping` may optionally also set additional properties to customize the behavior of the HTTP redirect response. - -To also change the path portion of the URL during the redirect, set `path_redirect`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - hostname: '*' - prefix: /redirect/ - service: httpbin.org - host_redirect: true - path_redirect: /ip -``` - -Here, a request to `http://$AMBASSADOR_URL/redirect/` will be redirected to `http://httpbin.org/ip/`. - -### Prefix redirect - -To change only a prefix of the path portion of the URL, set `prefix_redirect`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - hostname: '*' - prefix: /redirect/path/ - service: httpbin.org - host_redirect: true - prefix_redirect: /ip -``` - -Now, a request to `http://$AMBASSADOR_URL/redirect/path/` will be redirected to `http://httpbin.org/ip/`. The prefix `/redirect/path/` was matched and replaced with `/ip/`. - -### Regex redirect - -`regex_redirect` matches a regular expression to replace instead of a fixed prefix. -[See more information about using regex with $productName$](../rewrites/#regex_rewrite). - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - prefix: /foo/ - service: httpbin.org - host_redirect: true - regex_redirect: - pattern: '/foo/([0-9]*)/list' - substitution: '/bar/\1' -``` -A request to `http://$AMBASSADOR_URL/foo/12345/list` will be redirected to -`http://$AMBASSADOR_URL/bar/12345`. - -### Redirect response code - -To change the HTTP response code return by $productName$, set `redirect_reponse_code`. If this is not set, 301 is returned by default. Valid values include 301, 302, 303, 307, and 308. This -can be used with any type of redirect. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - prefix: /ip/ - service: httpbin.org - host_redirect: true - redirect_response_code: 302 -``` - -A request to `http://$AMBASSADOR_URL/ip/` will result in an HTTP 302 redirect to `http://httpbin.org/ip`. - -### X-FORWARDED-PROTO redirect - -In cases when TLS is being terminated at an external layer 7 load balancer, then you would want to redirect only the originating HTTP requests to HTTPS, and let the originating HTTPS requests pass through. - -This distinction between an originating HTTP request and an originating HTTPS request is done based on the `X-FORWARDED-PROTO` header that the external layer 7 load balancer adds to every request it forwards after TLS termination. - -To enable this `X-FORWARDED-PROTO` based HTTP to HTTPS redirection, add a `x_forwarded_proto_redirect: true` field to `ambassador Module`'s configuration. Note that when this feature is enabled `use_remote_address` MUST be set to false. - -An example configuration is as follows - - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - x_forwarded_proto_redirect: true - use_remote_address: false -``` - -Note: Setting `x_forwarded_proto_redirect: true` will impact all your $productName$ mappings. Every HTTP request to $productName$ will only be allowed to pass if it has an `X-FORWARDED-PROTO: https` header. diff --git a/content/en/docs/3.3/topics/using/retries.md b/content/en/docs/3.3/topics/using/retries.md deleted file mode 100644 index d018ab59..00000000 --- a/content/en/docs/3.3/topics/using/retries.md +++ /dev/null @@ -1,84 +0,0 @@ -# Automatic retries - -Sometimes requests fail. When these requests fail for transient issues, $productName$ can automatically retry the request. - -Retry policy can be set for all $productName$ mappings in the [`ambassador Module`](../../running/ambassador), or set per [`Mapping`](../mappings). Generally speaking, you should set `retry_policy` on a per mapping basis. Global retries can easily result in unexpected cascade failures. - -> Note that when setting `retry_policy`, adjusting `max_retries` in the [circuit breaker](https://www.getambassador.io/docs/edge-stack/pre-release/topics/using/circuit-breakers/) configuration should also be considered in order to account for all desired retries. - -## Configuring retries - -The `retry_policy` attribute configures automatic retries. The following fields are supported: - -```yaml -retry_policy: - retry_on: - num_retries: - per_try_timeout: -``` - -### `retry_on` - -(Required) Specifies the condition under which $productName$ retries a failed request. - -| Value | Description | -| --- | --- | -|`5xx`| Retries if the upstream service responds with any 5xx code or does not respond at all -|`gateway-error`| Similar to a `5xx` but only applies to a 502, 503, or 504 response -|`connect-failure`| Retries on a connection failure to the upstream service (included in `5xx`) -|`retriable-4xx`| Retries on a retriable 4xx response (currently only 409) -|`refused-stream`| Retires if the upstream service sends a REFUSED_STREAM error (included in `5xx`) -|`retriable-status-codes`| Retries based on status codes set in the `x-envoy-retriable-status-codes` header. If that header isn't set, $productName$ will not retry the request. - - For more details on each of these values, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/v1.9.0/configuration/http_filters/router_filter#x-envoy-retry-on). - -### `num_retries` - -(Default: 1) Specifies the number of retries to execute for a failed request. - -### `per_try_timeout` - -(Default: global request timeout) Specify the timeout for each retry. Must be in seconds or nanoseconds, e.g., `1s`, `1500ns`. - -## Examples - -A per mapping retry policy: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - retry_policy: - retry_on: "5xx" - num_retries: 10 -``` - -A global retry policy (not recommended): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - retry_policy: - retry_on: "retriable-4xx" - num_retries: 4 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - hostname: '*' -``` diff --git a/content/en/docs/3.3/topics/using/rewrites.md b/content/en/docs/3.3/topics/using/rewrites.md deleted file mode 100644 index 44d0a961..00000000 --- a/content/en/docs/3.3/topics/using/rewrites.md +++ /dev/null @@ -1,100 +0,0 @@ -# Rewrites - -Once $productName$ uses a prefix to identify the service to which a given request should be passed, it can rewrite the URL before handing it off to the service. - -There are two approaches for rewriting: `rewrite` for simpler scenarios and `regex_rewrite` for more advanced rewriting. - -**Please note that** only one of these two can be configured for a mapping **at the same time**. As a result $productName$ ignores `rewrite` when `regex_rewrite` is provided. - -## `rewrite` - -By default, the `prefix` is rewritten to `/`, so e.g., if we map `/backend-api/` to the service `service1`, then - - -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/content/en/docs/3.3/topics/using/shadowing.md b/content/en/docs/3.3/topics/using/shadowing.md deleted file mode 100644 index dd95fbba..00000000 --- a/content/en/docs/3.3/topics/using/shadowing.md +++ /dev/null @@ -1,78 +0,0 @@ -# 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. - -![Shadowing](../../images/shadowing.png) - -## 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/content/en/docs/3.3/topics/using/tcpmappings.md b/content/en/docs/3.3/topics/using/tcpmappings.md deleted file mode 100644 index f246e799..00000000 --- a/content/en/docs/3.3/topics/using/tcpmappings.md +++ /dev/null @@ -1,300 +0,0 @@ -# `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/content/en/docs/3.3/topics/using/timeouts.md b/content/en/docs/3.3/topics/using/timeouts.md deleted file mode 100644 index ae004102..00000000 --- a/content/en/docs/3.3/topics/using/timeouts.md +++ /dev/null @@ -1,66 +0,0 @@ -# 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/content/en/docs/3.3/tutorials/dev-portal-tutorial.md b/content/en/docs/3.3/tutorials/dev-portal-tutorial.md deleted file mode 100644 index d3c0d0a8..00000000 --- a/content/en/docs/3.3/tutorials/dev-portal-tutorial.md +++ /dev/null @@ -1,29 +0,0 @@ -# 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:///docs/` to see the -publicly visible Developer Portal. Make sure you include the trailing `/`. -This is a fully customizable portal that you can share with third parties who -need information about your APIs. diff --git a/content/en/docs/3.3/tutorials/getting-started.md b/content/en/docs/3.3/tutorials/getting-started.md deleted file mode 100644 index 1fb11cec..00000000 --- a/content/en/docs/3.3/tutorials/getting-started.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: "Getting Started with $productName$" -description: "Learn how to install $productName$ with either Helm or kubectl to get started routing traffic from the edge of your Kubernetes cluster to your services..." ---- - -import Alert from '@material-ui/lab/Alert'; -import GettingStartedEmissary21Tabs from './gs-tabs' - -# $productName$ quick start - -
-

Contents

- -- [1. Installation](#1-installation) - - [Connecting your installation to Ambassador Cloud](#connecting-your-installation-to-ambassador-cloud) -- [2. Routing traffic from the edge](#2-routing-traffic-from-the-edge) -- [What's next?](#img-classos-logo-srcimageslogopng-whats-next) - -
- -## 1. Installation - -We'll start by installing $productName$ into your cluster. - -**We recommend using Helm** but there are other options below to choose from. - - - -### Connecting your installation to Ambassador Cloud - -Now is a great moment to connect your new installation to Ambassador Cloud in order to fully leverage the power of $productName$ and the Developer Control Plane (DCP). - -1. Log in to [Ambassador Cloud](https://app.getambassador.io/cloud/services/) with GitHub, GitLab or Google and select your team account. - -2. At the top, click **Add Services** then click **Connection Instructions** in the "Connect your installation" section. - -3. Follow the prompts to name the cluster and click **Generate a Cloud Token**. - -4. Follow the prompts to install the cloud token into your cluster. - -5. When the token installation completes, your services will be listed in the DCP. - -Success! At this point, you have installed $productName$. Now let's get some traffic flowing to your services. - -## 2. Routing traffic from the edge - -$productName$ uses Kubernetes Custom Resource Definitions (CRDs) to declaratively define its desired state. The workflow you are going to build uses a simple demo app, a **`Listener` CRD**, and a **`Mapping` CRD**. The `Listener` CRD tells $productName$ what port to listen on, and the `Mapping` CRD tells $productName$ how to route incoming requests by host and URL path from the edge of your cluster to Kubernetes services. - -1. Start by creating a `Listener` resource for HTTP on port 8080: - - ``` - kubectl apply -f - < - This 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.
-
- Learn more about Listener.
- Learn more about Host. - - -2. Apply the YAML for the "Quote" service. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/quickstart/qotm.yaml - ``` - - The Service and Deployment are created in your default namespace. You can use 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](#connecting-your-installation-to-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` - - ![](../images/mapping-editor.png) - - 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 - <Victory! You have created your first $productName$ 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/content/en/docs/3.3/tutorials/gs-tabs.js b/content/en/docs/3.3/tutorials/gs-tabs.js deleted file mode 100644 index eb392504..00000000 --- a/content/en/docs/3.3/tutorials/gs-tabs.js +++ /dev/null @@ -1,131 +0,0 @@ -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 ( - - ); -} - -TabPanel.propTypes = { - children: PropTypes.node, - index: PropTypes.any.isRequired, - value: PropTypes.any.isRequired, -}; - -function a11yProps(index) { - return { - id: `simple-tab-${index}`, - 'aria-controls': `simple-tabpanel-${index}`, - }; -} - -const useStyles = makeStyles((theme) => ({ - root: { - flexGrow: 1, - backgroundColor: 'transparent', - }, -})); - -export default function GettingStartedEmissary21Tabs(props) { - const version = props.version; - const classes = useStyles(); - const [value, setValue] = React.useState(0); - - const handleChange = (event, newValue) => { - setValue(newValue); - }; - - return ( -
- - - } - label="Helm 3" - {...a11yProps(0)} - style={{ minWidth: '10%', textTransform: 'none' }} - /> - } - label="Kubernetes YAML" - {...a11yProps(1)} - style={{ minWidth: '10%', textTransform: 'none' }} - /> - - - - {/*Helm 3 install instructions*/} - - - {'# Add the Repo:' + - '\n' + - 'helm repo add datawire https://app.getambassador.io' + - '\n' + - 'helm repo update' + - '\n \n' + - '# Create Namespace and Install:' + - '\n' + - 'kubectl create namespace emissary && \\' + - '\n' + - `kubectl apply -f https://app.getambassador.io/yaml/emissary/${version}/emissary-crds.yaml` + - '\n' + - 'kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system' + - '\n' + - 'helm install emissary-ingress --namespace emissary datawire/emissary-ingress && \\' + - '\n' + - 'kubectl -n emissary wait --for condition=available --timeout=90s deploy -lapp.kubernetes.io/instance=emissary-ingress' + - '\n'} - - - - - {/*YAML install instructions*/} - - - {'kubectl create namespace emissary && \\' + - '\n' + - `kubectl apply -f https://app.getambassador.io/yaml/emissary/${version}/emissary-crds.yaml && \\` + - '\n' + - 'kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system' + - '\n' + - `kubectl apply -f https://app.getambassador.io/yaml/emissary/${version}/emissary-emissaryns.yaml && \\` + - '\n' + - 'kubectl -n emissary wait --for condition=available --timeout=90s deploy -lproduct=aes' + - '\n'} - - -
- ); -} diff --git a/content/en/docs/3.3/tutorials/gs-tabs2.js b/content/en/docs/3.3/tutorials/gs-tabs2.js deleted file mode 100644 index bfd95047..00000000 --- a/content/en/docs/3.3/tutorials/gs-tabs2.js +++ /dev/null @@ -1,174 +0,0 @@ -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'; - -function TabPanel(props) { - const { children, value, index, ...other } = props; - - return ( - - ); -} - -TabPanel.propTypes = { - children: PropTypes.node, - index: PropTypes.any.isRequired, - value: PropTypes.any.isRequired, -}; - -function a11yProps(index) { - return { - id: `simple-tab-${index}`, - 'aria-controls': `simple-tabpanel-${index}`, - }; -} - -const useStyles = makeStyles((theme) => ({ - root: { - flexGrow: 1, - backgroundColor: 'transparent', - }, -})); - -export default function SimpleTabs() { - const classes = useStyles(); - const [value, setValue] = React.useState(0); - - const handleChange = (event, newValue) => { - setValue(newValue); - }; - - return ( -
- - - - - - - - - - {/*Helm 3 token install instructions*/} - Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Helm. The slideout contains instructions with a - unique cloud-connect-token that is used to connect your - cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'helm upgrade ambassador --namespace ambassador datawire/ambassador \\' + - '\n' + - ' --set agent.cloudConnectToken=$TOKEN && \\' + - '\n' + - 'kubectl -n ambassador wait --for condition=available --timeout=90s deploy -lproduct=aes'} - - - - - {/*Helm 2 token install instructions*/} - Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Helm. The slideout contains instructions with a - unique cloud-connect-token that is used to connect your - cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'helm upgrade --namespace ambassador ambassador datawire/ambassador \\' + - '\n' + - ' --set crds.create=false --set agent.cloudConnectToken=$TOKEN && \\' + - '\n' + - 'kubectl -n ambassador wait --for condition=available --timeout=90s deploy -lproduct=aes'} - - - - - {/*YAML token install instructions*/} - Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Kubernetes YAML. The slideout contains instructions - with a unique cloud-connect-token that is used to connect - your cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'kubectl create configmap -n ambassador ambassador-agent-cloud-token \\' + - '\n' + - ' --from-literal=CLOUD_CONNECT_TOKEN=$TOKEN'} - - - - - {/*edgectl token install instructions*/} - Connecting $productName$ that was installed via edgectl is - identical to the Kubernetes YAML procedure. -
- Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Kubernetes YAML. The slideout contains instructions - with a unique cloud-connect-token that is used to connect - your cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'kubectl create configmap -n ambassador ambassador-agent-cloud-token \\' + - '\n' + - ' --from-literal=CLOUD_CONNECT_TOKEN=$TOKEN'} - - -
- ); -} diff --git a/content/en/docs/3.3/tutorials/quickstart-demo.md b/content/en/docs/3.3/tutorials/quickstart-demo.md deleted file mode 100644 index 70cbce8b..00000000 --- a/content/en/docs/3.3/tutorials/quickstart-demo.md +++ /dev/null @@ -1,176 +0,0 @@ -# $productName$ Tutorial - -In this article, you will explore some of the key features of $productName$ by walking through an example workflow and exploring the -Edge Policy Console. - -## Prerequisites - -You must have [$productName$ installed](../getting-started/) in your -Kubernetes cluster. - -## Routing Traffic from the Edge - -Like any other Kubernetes object, Custom Resource Definitions (CRDs) are used to -declaratively define $productName$’s desired state. The workflow you are going to -build uses a sample deployment and the `Mapping` CRD, which is the core resource -that you will use with $productName$ to manage your edge. It enables you to route -requests by host and URL path from the edge of your cluster to Kubernetes services. - -1. Copy the configuration below and save it to a file named `quote.yaml` so that -you can deploy these resources to your cluster. This basic configuration creates -the `quote` deployment and a service to expose that deployment on port 80. - - ```yaml - --- - apiVersion: apps/v1 - kind: Deployment - metadata: - name: quote - namespace: ambassador - spec: - replicas: 1 - selector: - matchLabels: - app: quote - strategy: - type: RollingUpdate - template: - metadata: - labels: - app: quote - spec: - containers: - - name: backend - image: docker.io/datawire/quote:$quoteVersion$ - ports: - - name: http - containerPort: 8080 - --- - apiVersion: v1 - kind: Service - metadata: - name: quote - namespace: ambassador - spec: - ports: - - name: http - port: 80 - targetPort: 8080 - selector: - app: quote - ``` - -1. Apply the configuration to the cluster with the command `kubectl apply -f quote.yaml`. - -1. Copy the configuration below and save it to a file called `quote-backend.yaml` -so that you can create a `Mapping` on your cluster. This `Mapping` tells $productName$ to route all traffic inbound to the `/backend/` path, on any host that can be used to reach $productName$, to the `quote` service. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Mapping - metadata: - name: quote-backend - namespace: ambassador - spec: - hostname: "*" - prefix: /backend/ - service: quote - ``` - -1. Apply the configuration to the cluster with the command -`kubectl apply -f quote-backend.yaml` - -1. Store the $productName$ `LoadBalancer` address to a local environment variable. -You will use this variable to test accessing your pod. - - ``` - export AMBASSADOR_LB_ENDPOINT=$(kubectl -n ambassador get svc ambassador -o "go-template={{range .status.loadBalancer.ingress}}{{or .ip .hostname}}{{end}}") - ``` - -1. Test the configuration by accessing the service through the $productName$ load -balancer. - - ``` - $ curl -Lk "https://$AMBASSADOR_LB_ENDPOINT/backend/" - { - "server": "idle-cranberry-8tbb6iks", - "quote": "Non-locality is the driver of truth. By summoning, we vibrate.", - "time": "2019-12-11T20:10:16.525471212Z" - } - ``` - -Success, you have created your first $productName$ `Mapping`, routing a -request from your cluster's edge to a service! - -Since the `Mapping` you just created controls how requests are routed, -changing the `Mapping` will immediately change the routing. To see this -in action, use `kubectl` to edit the `Mapping`: - -1. Run `kubectl edit Mapping quote-backend`. - -1. Change `prefix: /backend/` to `prefix: /quoteme/`. - -1. Save the file and let `kubectl` update your `Mapping`. - -1. Run `kubectl get Mappings --namespace ambassador`. You will see the -`quote-backend` `Mapping` has the updated prefix listed. Try to access the -endpoint again via `curl` with the updated prefix. - - ``` - $ kubectl get Mappings --namespace ambassador - NAME PREFIX SERVICE STATE REASON - quote-backend /quoteme/ quote - - $ curl -Lk "https://${AMBASSADOR_LB_ENDPOINT}/quoteme/" - { - "server": "snippy-apple-ci10n7qe", - "quote": "A principal idea is omnipresent, much like candy.", - "time": "2020-11-18T17:15:42.095153306Z" - } - ``` - -1. Change the prefix back to `/backend/` so that you can later use the `Mapping` -with other tutorials. - -## 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. In the Edge Policy Console, navigate to the **APIs** tab. You'll see the -OpenAPI documentation there for the "Quote Service API." Click **GET** to -expand out the documentation. - -1. Navigate to `https:///docs/` to see the -publicly visible Developer Portal. Make sure you include the trailing `/`. -This is a fully customizable portal that you can share with third parties who -need information about your APIs. - -## Next Steps - -Further explore some of the concepts you learned about in this article: -* [`Mapping` resource](../../topics/using/intro-mappings/): routes traffic from -the edge of your cluster to a Kubernetes service -* [`Host` resource](../../topics/running/host-crd/): sets the hostname by which -$productName$ will be accessed and secured with TLS certificates -* [Developer Portal](../../tutorials/dev-portal-tutorial/): -publishes an API catalog and OpenAPI documentation - -$productName$ has a comprehensive range of [features](/features/) to -support the requirements of any edge microservice. - -Learn more about [how developers use $productName$](../../topics/using/) to manage -edge policies. - -Learn more about [how site reliability engineers and operators run $productName$](../../topics/running/) -in production environments. - -To learn how $productName$ works, use cases, best practices, and more, check out -the [Quick Start](../getting-started) or read the [$productName$ Story](../../about/why-ambassador). - -For a custom configuration, you can install $productName$ -[manually](../../topics/install/yaml-install). diff --git a/content/en/docs/3.3/versions.yml b/content/en/docs/3.3/versions.yml deleted file mode 100644 index 9e78fe6c..00000000 --- a/content/en/docs/3.3/versions.yml +++ /dev/null @@ -1,35 +0,0 @@ -# branch info -branch: release/v3.3 - -# self -version: 3.3.1 -productName: "Emissary-ingress" -productNamePlural: "Emissary-ingresses" -productNamespace: emissary -productDeploymentName: emissary-ingress -productHelmName: emissary-ingress - -# OSS (self) -ossVersion: 3.3.1 -ossDocsVersion: "3.3" -ossChartVersion: 8.3.1 -OSSproductName: "Emissary-ingress" -OSSproductNamePlural: "Emissary-ingresses" - -# AES (not self) -aesVersion: 3.3.1 -aesDocsVersion: "3.3" -aesChartVersion: 8.3.1 -AESproductName: "Ambassador Edge Stack" -AESproductNamePlural: "Ambassador Edge Stacks" - -# other products -qotmVersion: 1.7 -quoteVersion: 0.5.0 - -# Most recent version from previous major versions -# This is mostly to ensure that the migration matrix stays up-to-date -versionTwoX: 2.5.1 -chartVersionTwoX: 7.6.1 -versionOneX: 1.14.4 -chartVersionOneX: 6.9.5 diff --git a/content/en/docs/3.4/_index.md b/content/en/docs/3.4/_index.md deleted file mode 100644 index 750c8aa2..00000000 --- a/content/en/docs/3.4/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: v3.4 docs -cascade: - version: v3.4 - versName: &name v3.4 - git_version_tag: v3.4.0 - exclude_search: true -linkTitle: *name -simple_list: true -weight: -340 # Weight for doc version vX.Y should be -XY0 ---- - -These docs cover everything from setting up and running Emissary-ingress to its operation and usage. diff --git a/content/en/docs/3.4/about/alternatives.md b/content/en/docs/3.4/about/alternatives.md deleted file mode 100644 index bafec087..00000000 --- a/content/en/docs/3.4/about/alternatives.md +++ /dev/null @@ -1,19 +0,0 @@ -# $productName$ vs. other software - -Alternatives to $productName$ fall into three basic categories: - -* Hosted API gateways, such as the [Amazon API gateway](https://aws.amazon.com/api-gateway/). -* Traditional API gateways, such as [Kong](https://konghq.org/). -* L7 proxies, such as [Traefik](https://traefik.io/), [NGINX](http://nginx.org/), [HAProxy](http://www.haproxy.org/), or [Envoy](https://www.envoyproxy.io), or Ingress controllers built on these proxies. - -Both hosted API gateways and traditional API gateways are: - -* Not self-service. The management interfaces on traditional API gateways are not designed for developer self-service, and provide limited safety and usability for developers. -* Not Kubernetes-native. They're typically configured using REST APIs, making it challenging to adopt cloud-native patterns such as GitOps and declarative configuration. -* [Designed for API management, rather than designed for microservices](../../topics/concepts/microservices-api-gateways). - -A Layer 7 proxy can be used as an API gateway, but typically requires additional bespoke development to support microservices use cases. In fact, many API gateways package the additional features needed for an API gateway on top of an L7 proxy. $productName$ uses Envoy, while Kong uses NGINX. If you're interested in deploying Envoy directly, we've written an [introductory tutorial](https://www.datawire.io/guide/traffic/getting-started-lyft-envoy-microservices-resilience/). - -## Istio - -[Istio](https://istio.io) is an open-source service mesh, built on Envoy. A service mesh is designed to manage East/West traffic (traffic between servers and your data center), while an API gateway manages North/South traffic (in and out of your data center). Documentation on how to deploy $productName$ with Istio is [here](../../howtos/istio). In general, we've found that North/South traffic is quite different from East/West traffic (i.e., you don't control the client in the North/South use case). diff --git a/content/en/docs/3.4/about/changes-2.x.md b/content/en/docs/3.4/about/changes-2.x.md deleted file mode 100644 index 389cc89b..00000000 --- a/content/en/docs/3.4/about/changes-2.x.md +++ /dev/null @@ -1,238 +0,0 @@ -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. - - - $productName$ 2.X supports only API versions getambassador.io/v2 - and getambassador.io/v3alpha1. If you are using any resources with - older API versions, you will need to upgrade them. - - -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 [structural CRDs](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. - - - Learn more about Listener.
- Learn more about Host. - - -### 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. - - - Learn more about Host. - - -### `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. - - - Learn more about Host.
- Learn more about Mapping. - - -### 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. - - - Learn more about Host. - - -### `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). - - - Learn more about Host.
- Learn more about TLSContext. - - -### `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). - - - Learn more about Mapping. - - -### `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. - - - Learn more about Mapping. - - -## 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). In $productName$ -2.X, you may switch back to Envoy V2 by setting the `AMBASSADOR_ENVOY_API_VERSION` -environment variable to "V2"; in $productName$ 3.X, support for the Envoy V2 API (and -the `AMBASSADOR_ENVOY_API_VERSION` environment variable) will be removed. - -### 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. - - - Learn more about Listener. - - -### `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/content/en/docs/3.4/about/changes-3.y.md b/content/en/docs/3.4/about/changes-3.y.md deleted file mode 100644 index 91105d28..00000000 --- a/content/en/docs/3.4/about/changes-3.y.md +++ /dev/null @@ -1,52 +0,0 @@ -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 AuthServices 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, -``` - - - Learn more about Envoy Proxy changes. - - -## 2. Envoy V2 Protocol Support Removed - -With the upgrade to Envoy **1.22**, the V2 Envoy Transport Protocol is no longer supported. -$productName$ 3.X **only** supports [V3 Envoy API](https://www.envoyproxy.io/docs/envoy/latest/api-v3/api). - - -The environment variable AMBASSADOR_ENVOY_API_VERSION has been removed and will no longer have the affect -of changing the transport protocol. - - - -The setting of 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. - diff --git a/content/en/docs/3.4/about/faq.md b/content/en/docs/3.4/about/faq.md deleted file mode 100644 index 513c75c5..00000000 --- a/content/en/docs/3.4/about/faq.md +++ /dev/null @@ -1,79 +0,0 @@ -# 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. -* 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! The core functionality of the $AESproductName$ is free and has no limits whatsoever. If you wish to use one of our additional, proprietary features such as Single Sign-On, you can get a free community license for up to 5 requests per second by registering your connected $AESproductName$ installation in [Ambassador Cloud](https://app.getambassador.io/cloud/). Please contact [sales](/contact-us/) if you need more than 5 RPS. - -For more details on core unlimited features and premium features, see the [editions page](/editions). - -### 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? - -[//]: # (+FIX+ Check for OSS) - -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$? - -[//]: # (+FIX+ Check for OSS) - -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 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/content/en/docs/3.4/about/features-and-benefits.md b/content/en/docs/3.4/about/features-and-benefits.md deleted file mode 100644 index a25d7752..00000000 --- a/content/en/docs/3.4/about/features-and-benefits.md +++ /dev/null @@ -1,43 +0,0 @@ -# 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 - -[//]: # (+FIX+ Forge is no more) - -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 - -[//]: # (+FIX+ we've come to realize that it's better to scale vertically) - -$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 using a custom authentication service. When configured, the $productName$ will check with your external authentication service prior to routing an incoming request. For more information, see the [authentication guide](../../topics/running/services/auth-service). - -## 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/content/en/docs/3.4/about/known-issues.md b/content/en/docs/3.4/about/known-issues.md deleted file mode 100644 index 6b89c65a..00000000 --- a/content/en/docs/3.4/about/known-issues.md +++ /dev/null @@ -1,9 +0,0 @@ -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. diff --git a/content/en/docs/3.4/about/support.md b/content/en/docs/3.4/about/support.md deleted file mode 100644 index 11927f95..00000000 --- a/content/en/docs/3.4/about/support.md +++ /dev/null @@ -1,27 +0,0 @@ -# Need help? - -If you need help deploying $productName$ at your organization, there are several different options available to you. - -## Support tiers - -### $productName$ community support - -When running $OSSproductName$, or $AESproductName$ with free community licenses, [join our Slack channel](http://a8r.io/slack) to talk with other users in the community and get your questions answered. - -If you can’t find an answer there, [contact us](/contact-us) to learn more about the support options available with $AESproductName$ Enterprise. - -### $AESproductName$ Enterprise - -With $AESproductName$ Enterprise, you have access to deployment and production support. To learn more, [contact sales](/contact-us). - -**Deployment and Update Support**: $AESproductName$ can accelerate your migration to Kubernetes, or your upgrade between versions of $AESproductName$. Deployment support helps you with the $AESproductName$ and Kubernetes migration, before you move to production. - -**Production Support**: We offer two types of production support contracts for users deploying the $AESproductName$ in production. We offer both business hour (8am - 5pm EST, M-F) and 24x7 Sev 1 support for the $AESproductName$. 24x7 Sev 1 support includes custom hotfix support for production outages if necessary. - -## File a Github Issue - -If you see a bug you want to fix, see room for documentation improvements, or have something else you want to change, you can [file an issue on github](https://github.com/datawire/ambassador/issues/new). - -## Pricing - -[Contact us](/contact-us) to learn how we can help, and for detailed pricing information. diff --git a/content/en/docs/3.4/about/why-ambassador.md b/content/en/docs/3.4/about/why-ambassador.md deleted file mode 100644 index 0d343983..00000000 --- a/content/en/docs/3.4/about/why-ambassador.md +++ /dev/null @@ -1,54 +0,0 @@ -# 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 an open-source, Kubernetes-native [microservices API gateway](../../topics/concepts/microservices-api-gateways) built on 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/content/en/docs/3.4/community.md b/content/en/docs/3.4/community.md deleted file mode 100644 index 759e4f0e..00000000 --- a/content/en/docs/3.4/community.md +++ /dev/null @@ -1,12 +0,0 @@ -# Community - -## Contributor's guide -Please review our [contributor's guide](https://github.com/emissary-ingress/emissary/blob/master/DEVELOPING.md) -on GitHub to learn how you can help make Emissary-ingress better. - -## Changelog -Our [changelog](https://github.com/emissary-ingress/emissary/blob/master/CHANGELOG.md) -describes new features, bug fixes, and updates to each version of Emissary-ingress. - -## Meetings -Check out our community [meeting schedule](https://github.com/emissary-ingress/emissary/blob/master/MEETING_SCHEDULE.md) for opportunities to interact with Emissary-ingress developers. diff --git a/content/en/docs/3.4/doc-links.yml b/content/en/docs/3.4/doc-links.yml deleted file mode 100644 index 58b81ad9..00000000 --- a/content/en/docs/3.4/doc-links.yml +++ /dev/null @@ -1,229 +0,0 @@ -- 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: $productName$ 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: 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/basic-auth - - title: Rate limiting - items: - - title: Rate limiting service - link: /topics/running/services/rate-limit-service/ - - title: Basic rate limiting - link: /topics/using/rate-limits/ - - 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: Distrbuted 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: 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: 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: Diagnostics - link: /topics/running/diagnostics -- 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: Licenses - link: licenses diff --git a/content/en/docs/3.4/features-icons/basic-authentication.svg b/content/en/docs/3.4/features-icons/basic-authentication.svg deleted file mode 100644 index 2bd19edf..00000000 --- a/content/en/docs/3.4/features-icons/basic-authentication.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_897228_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.4/features-icons/canary-release.svg b/content/en/docs/3.4/features-icons/canary-release.svg deleted file mode 100644 index f8de57d9..00000000 --- a/content/en/docs/3.4/features-icons/canary-release.svg +++ /dev/null @@ -1,27 +0,0 @@ - - - - Group 25 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.4/features-icons/cors.svg b/content/en/docs/3.4/features-icons/cors.svg deleted file mode 100644 index e559d924..00000000 --- a/content/en/docs/3.4/features-icons/cors.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_111967_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.4/features-icons/datadog.png b/content/en/docs/3.4/features-icons/datadog.png deleted file mode 100644 index eea05f8c..00000000 Binary files a/content/en/docs/3.4/features-icons/datadog.png and /dev/null differ diff --git a/content/en/docs/3.4/features-icons/datadog.svg b/content/en/docs/3.4/features-icons/datadog.svg deleted file mode 100644 index e46e8118..00000000 --- a/content/en/docs/3.4/features-icons/datadog.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Screen Shot 2018-04-05 at 8.22.25 AM - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.4/features-icons/diagnostics.svg b/content/en/docs/3.4/features-icons/diagnostics.svg deleted file mode 100644 index 940e1bc2..00000000 --- a/content/en/docs/3.4/features-icons/diagnostics.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_196445_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.4/features-icons/distributed-tracing.png b/content/en/docs/3.4/features-icons/distributed-tracing.png deleted file mode 100644 index 6b69e28c..00000000 Binary files a/content/en/docs/3.4/features-icons/distributed-tracing.png and /dev/null differ diff --git a/content/en/docs/3.4/features-icons/grpc.png b/content/en/docs/3.4/features-icons/grpc.png deleted file mode 100644 index b2f5a0d9..00000000 Binary files a/content/en/docs/3.4/features-icons/grpc.png and /dev/null differ diff --git a/content/en/docs/3.4/features-icons/prometheus.svg b/content/en/docs/3.4/features-icons/prometheus.svg deleted file mode 100644 index d5252a66..00000000 --- a/content/en/docs/3.4/features-icons/prometheus.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - prometheus_logo_grey - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.4/features-icons/rate-limiting.svg b/content/en/docs/3.4/features-icons/rate-limiting.svg deleted file mode 100644 index f1b6eacb..00000000 --- a/content/en/docs/3.4/features-icons/rate-limiting.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - Group 10 - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.4/features-icons/regex-routing.svg b/content/en/docs/3.4/features-icons/regex-routing.svg deleted file mode 100644 index 113b53b5..00000000 --- a/content/en/docs/3.4/features-icons/regex-routing.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_699774_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.4/features-icons/request-transformers.svg b/content/en/docs/3.4/features-icons/request-transformers.svg deleted file mode 100644 index 0b13e2dc..00000000 --- a/content/en/docs/3.4/features-icons/request-transformers.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_96239_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.4/features-icons/shadowing.svg b/content/en/docs/3.4/features-icons/shadowing.svg deleted file mode 100644 index 9e85eee1..00000000 --- a/content/en/docs/3.4/features-icons/shadowing.svg +++ /dev/null @@ -1,15 +0,0 @@ - - - - shadow - Created with Sketch. - - - - - - - - - - diff --git a/content/en/docs/3.4/features-icons/statsd.png b/content/en/docs/3.4/features-icons/statsd.png deleted file mode 100644 index 28374438..00000000 Binary files a/content/en/docs/3.4/features-icons/statsd.png and /dev/null differ diff --git a/content/en/docs/3.4/features-icons/statsd.svg b/content/en/docs/3.4/features-icons/statsd.svg deleted file mode 100644 index cabc90db..00000000 --- a/content/en/docs/3.4/features-icons/statsd.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - 88eb31f74479e422e4e9abfc6c2b00ee - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.4/features-icons/third-party-auth.svg b/content/en/docs/3.4/features-icons/third-party-auth.svg deleted file mode 100644 index 5359a24a..00000000 --- a/content/en/docs/3.4/features-icons/third-party-auth.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_511233_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.4/features-icons/timeouts.svg b/content/en/docs/3.4/features-icons/timeouts.svg deleted file mode 100644 index 47f63056..00000000 --- a/content/en/docs/3.4/features-icons/timeouts.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_587034_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.4/features-icons/tls-termination.svg b/content/en/docs/3.4/features-icons/tls-termination.svg deleted file mode 100644 index 6a631a96..00000000 --- a/content/en/docs/3.4/features-icons/tls-termination.svg +++ /dev/null @@ -1,17 +0,0 @@ - - - - noun_63544_cc - Created with Sketch. - - - - - - - - - - - - diff --git a/content/en/docs/3.4/features-icons/url-rewrite.svg b/content/en/docs/3.4/features-icons/url-rewrite.svg deleted file mode 100644 index 023e2e05..00000000 --- a/content/en/docs/3.4/features-icons/url-rewrite.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1295942_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.4/features-icons/websockets.svg b/content/en/docs/3.4/features-icons/websockets.svg deleted file mode 100644 index af17b9c0..00000000 --- a/content/en/docs/3.4/features-icons/websockets.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - noun_50814_cc - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.4/howtos/active-health-checking.md b/content/en/docs/3.4/howtos/active-health-checking.md deleted file mode 100644 index fb5decdd..00000000 --- a/content/en/docs/3.4/howtos/active-health-checking.md +++ /dev/null @@ -1,78 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Active Health Checking - -$productName$ provides support for active health checking of upstreams via the `Mapping` resource. Active health checking will configure Envoy to make requests to the upstream at a configurable interval. If the upstream does not respond with an expected status code then the upstream will be marked as unhealthy and Envoy will no longer route requests to that upstream until they respond successfully to the health check. - -This feature can only be used with the [endpoint resolver](../../topics/running/resolvers#the-kubernetes-endpoint-resolver). This is necessary because the endpoint resolver allows Envoy to be aware of each individual pod in a deployment as opposed to the [kubernetes service resolver](../../topics/running/resolvers#the-kubernetes-service-resolver) where Envoy is only aware of the upstream as a single endpoint. When envoy is aware of the multiple pods in a deployment then it will allow the active health checks to mark an individual pod as unhealthy while the remaining pods are able to serve requests. - - -Active health checking configuration wil only function with the endpoint resolver. If configuration for active health checking is provided on a Mapping that does not use the endpoint resolver then the health checking configuration will be ignored. - - -## Active Health Checking Configuration - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: "example-mapping" - namespace: "example-namespace" -spec: - hostname: "*" - prefix: /example/ - service: quote - health_checks: list[object] # optional - - unhealthy_threshold: int # optional (default: 2) - healthy_threshold: int # optional (default: 1) - interval: duration # optional (default: 5s) - timeout: duration # optional (default: 3s) - health_check: object # required - http: - path: string # required - hostname: string # optional - remove_request_headers: list[string] # optional - add_request_headers: list[object] # optional - - example-header-1: - append: bool # optional (default: true) - value: string # required - expected_statuses: list[object] # optional - - max: int (100-599) # required (only when using expected_statuses) - min: int (100-599) # required (only when using expected_statuses) - - - health_check: object # required - grpc: - authority: string # optional - upstream_name: string # required -... -``` - -### `health_checks` configuration - -`health_checks` Configures a list of health checks to be run for the `Mapping` and provides several config options for how the health check requests should be run. - -- `unhealthy_threshold`: The number of unexpected responses for an upstream pod to be marked as unhealthy. Regardless of the configuration of `unhealthy_threshold`, a single `503` response will mark the upstream as unhealthy until it passes the required number of health checks. This field is optional and defaults to `2`. -- `healthy_threshold`: The number of expected responses for an unhealthy upstream pod to be marked as healthy and resume handling traffic. This field is optional and defaults to `1`. -- `interval`: Specifies the interval for how frequently the health check request should be made. It is divided amongst the pods in a deployment. For example, an `interval` of `1s` on a deployment of 5 pods would result in each pod receiving a health check request about every 5 seconds. This field is optional and defaults to `5s` when not configured. -- `timeout`: Configures the timeout for the health check requests to an upstream. If a health check request fails the timeout it will be considred a failed check and count towards the `unhealthy_threshold`. This field is optional and defaults to `3s`. -- `health_check`: This field is required and provides the configuration for how the health check requests should be made. Either `grpc` or `http` may be configured for this field depending on whether an HTTP or gRPC health check is desired. - -### HTTP `health_check` Configuration - -`health_check.http` configures HTTP health checks to the upstream. - -- `path`: This field is required and configures the path on the upstream service that the health checks request should be made to. -- `hostname`: Configures the value of the host header in the health check request. This field is optional and defaults to using the name of the Envoy cluster this health check is associated with. -- `expected_statuses`: Configures a range of response statuses from Min to Max (both inclusive). If the upstream returns any status in this range then it will be considered a passed health check. Thies field is optional and by default only `5xx` responses count as a failed health check and contribute towards the `unhealthy_threshold`. - - `max`: End of the statuses to include. Must be between 100 and 599 (inclusive). - - `min`: Start of the statuses to include. Must be between 100 and 599 (inclusive). -- `remove_request_headers`: Configures a list of HTTP headers that should be removed from each health check request sent to the upstream. -- `request_headers_to_add`: Configures a list of HTTP headers that should be added to each health check request sent to the upstream. - -### gRPC `health_check` Configuration - -`health_check.grpc` configures gRPC health checks to the upstream. Only two fields are configurable for gRPC health checks. - -- `authority`: Configures the value of the :authority header in the gRPC health check request. This field is optional and if left empty the upstream name will be used. -- `upstream_name`: This field is required and configures the UpstreamName name parameter which will be sent to gRPC service in the health check message. diff --git a/content/en/docs/3.4/howtos/basic-auth.md b/content/en/docs/3.4/howtos/basic-auth.md deleted file mode 100644 index 70ce27ce..00000000 --- a/content/en/docs/3.4/howtos/basic-auth.md +++ /dev/null @@ -1,191 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Basic authentication (for $productName$) - -[//]: # (+FIX+ link to "authentication and authorization" concept) - - - This guide applies to $OSSproductName$, use of this guide with $AESproductName$ is not supported. $AESproductName$ does authentication using the Filter resource instead of the AuthService resource as described below. - - -$productName$ can authenticate incoming requests before routing them to a backing -service. In this tutorial, we'll configure $productName$ to use an external third -party authentication service. We're assuming also that you are running the -quote application in your cluster as described in the -[$productName$ tutorial](../../tutorials/quickstart-demo/). - -## Before you get started - -This tutorial assumes you have already followed the $productName$ [Installation](../../topics/install/) guide. If you haven't done that already, you should do so now. - -Once complete, you'll have a Kubernetes cluster running $productName$. Let's walk through adding authentication to this setup. - -## 1. Deploy the authentication service - -$productName$ delegates the actual authentication logic to a third party authentication service. We've written a [simple authentication service](https://github.com/datawire/ambassador-auth-service) that: - -- listens for requests on port 3000; -- expects all URLs to begin with `/extauth/`; -- performs HTTP Basic Auth for all URLs starting with `/backend/get-quote/` (other URLs are always permitted); -- accepts only user `username`, password `password`; and -- makes sure that the `x-qotm-session` header is present, generating a new one if needed. - -$productName$ routes _all_ requests through the authentication service: it relies on the auth service to distinguish between requests that need authentication and those that do not. If $productName$ cannot contact the auth service, it will return a 503 for the request; as such, **it is very important to have the auth service running before configuring $productName$ to use it.** - -Here's the YAML we'll start with: - -```yaml ---- -apiVersion: v1 -kind: Service -metadata: - name: example-auth -spec: - type: ClusterIP - selector: - app: example-auth - ports: - - port: 3000 - name: http-example-auth - targetPort: http-api ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: example-auth -spec: - replicas: 1 - strategy: - type: RollingUpdate - selector: - matchLabels: - app: example-auth - template: - metadata: - labels: - app: example-auth - spec: - containers: - - name: example-auth - image: docker.io/datawire/ambassador-auth-service:2.0.0 - imagePullPolicy: Always - ports: - - name: http-api - containerPort: 3000 - resources: - limits: - cpu: "0.1" - memory: 100Mi -``` - -Note that the cluster does not yet contain any $productName$ AuthService definition. This is intentional: we want the service running before we tell $productName$ about it. - -The YAML above is published at getambassador.io, so if you like, you can just do - -``` -kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/demo/demo-auth.yaml -``` - -to spin everything up. (Of course, you can also use a local file, if you prefer.) - -Wait for the pod to be running before continuing. The output of `kubectl get pods` should look something like - -``` -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -example-auth-6c5855b98d-24clp 1/1 Running 0 4m -``` -Note that the `READY` field says `1/1` which means the pod is up and running. - -## 2. Configure $productName$ authentication - -Once the auth service is running, we need to tell $productName$ about it. The easiest way to do that is point it to the `example-auth` service with the following: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: AuthService -metadata: - name: authentication -spec: - auth_service: "example-auth:3000" - path_prefix: "/extauth" - allowed_request_headers: - - "x-qotm-session" - allowed_authorization_headers: - - "x-qotm-session" -``` - -This configuration tells $productName$ about the auth service, notably that it needs the `/extauth` prefix, and that it's OK for it to pass back the `x-qotm-session` header. Note that `path_prefix` and `allowed_*_headers` are optional. - -If the auth service uses a framework like [Gorilla Toolkit](http://www.gorillatoolkit.org) which enforces strict slashes as HTTP path separators, it is possible to end up with an infinite redirect where the auth service's framework redirects any request with non-conformant slashing. This would arise if the above example had `path_prefix: "/extauth/"`, the auth service would see a request for `/extauth//backend/get-quote/` which would then be redirected to `/extauth/backend/get-quote/` rather than actually be handled by the authentication handler. For this reason, remember that the full path of the incoming request including the leading slash, will be appended to `path_prefix` regardless of non-conformant slashing. - -You can apply this file from getambassador.io with - -``` -kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/demo/demo-auth-enable.yaml -``` - -or, again, apply it from a local file if you prefer. - -Note that the cluster does not yet contain any $productName$ AuthService definition. - -## 3. Test authentication - -If we `curl` to a protected URL: - -``` -$ curl -Lv $AMBASSADORURL/backend/get-quote/ -``` - -We get a 401 since we haven't authenticated. - -``` -* TCP_NODELAY set -* Connected to 54.165.128.189 (54.165.128.189) port 32281 (#0) -> GET /backend/get-quote/ HTTP/1.1 -> Host: 54.165.128.189:32281 -> User-Agent: curl/7.63.0 -> Accept: */* -> -< HTTP/1.1 401 Unauthorized -< www-authenticate: Basic realm="Ambassador Realm" -< content-length: 0 -< date: Thu, 23 May 2019 15:24:55 GMT -< server: envoy -< -* Connection #0 to host 54.165.128.189 left intact -``` - -If we authenticate to the service, we will get a quote successfully: - -``` -$ curl -Lv -u username:password $AMBASSADORURL/backend/get-quote/ - -* TCP_NODELAY set -* Connected to 54.165.128.189 (54.165.128.189) port 32281 (#0) -* Server auth using Basic with user 'username' -> GET /backend/get-quote/ HTTP/1.1 -> Host: 54.165.128.189:32281 -> Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= -> User-Agent: curl/7.63.0 -> Accept: */* -> -< HTTP/1.1 200 OK -< content-type: application/json -< date: Thu, 23 May 2019 15:25:06 GMT -< content-length: 172 -< x-envoy-upstream-service-time: 0 -< server: envoy -< -{ - "server": "humble-blueberry-o2v493st", - "quote": "Nihilism gambles with lives, happiness, and even destiny itself!", - "time": "2019-05-23T15:25:06.544417902Z" -* Connection #0 to host 54.165.128.189 left intact -} -``` - -## More - -For more details about configuring authentication, see the [`External` filter](/docs/edge-stack/latest/topics/using/filters/) documentation. diff --git a/content/en/docs/3.4/howtos/cert-manager.md b/content/en/docs/3.4/howtos/cert-manager.md deleted file mode 100644 index d742decd..00000000 --- a/content/en/docs/3.4/howtos/cert-manager.md +++ /dev/null @@ -1,230 +0,0 @@ -# Using cert-manager - -[//]: # (+FIX+ link to "TLS and certificates" concept) - -$AESproductName$ has simple and easy built-in support for automatically [using ACME] with the -`http-01` challenge to create and renew TLS certificates. However, this support is not available -in $OSSproductName$, and it is limited to the ACME `http-01` challenge type. If you're running -$OSSproductName$, or if you require more flexible certificate management (such as using ACME's -`dns-01` challenge, or using a non-ACME certificate source), external certificate management -tools are also supported. - -[using ACME]: ../../topics/running/host-crd - -One such tool is Jetstack's [cert-manager](https://github.com/jetstack/cert-manager), which is a general-purpose tool -for managing certificates in Kubernetes. Cert-manager will automatically create and renew TLS certificates and store -them as Kubernetes secrets for easy use in a cluster. $productName$ will automatically watch for secret -changes and reload certificates upon renewal. - -> **Note:** This document assumes cert-manager v0.15 or greater. This document has been updated to use CRD standards -> specified in v0.15. [Legacy CRD support](https://cert-manager.io/docs/installation/upgrading/upgrading-0.14-0.15/) -> was removed in cert-manager v0.15, see their [upgrading](https://cert-manager.io/docs/installation/upgrading/) -> document for more info. - -## Install cert-manager - -There are many different ways to [install cert-manager](https://cert-manager.io/docs/installation/). For simplicity, we will use Helm. - -1. Create the cert-manager CRDs. - ``` - kubectl apply -f https://github.com/jetstack/cert-manager/releases/latest/download/cert-manager.crds.yaml - ``` - -2. Add the `jetstack` Helm repository. - ``` - helm repo add jetstack https://charts.jetstack.io && helm repo update - ``` - -3. Install cert-manager. - - ``` - kubectl create ns cert-manager - helm install cert-manager --namespace cert-manager jetstack/cert-manager - ``` - -## Issuing certificates - -cert-manager issues certificates from a CA such as [Let's Encrypt](https://letsencrypt.org/). It does this using the ACME protocol which supports various challenge mechanisms for verifying ownership of the domain. - -### Issuer - -An `Issuer` or `ClusterIssuer` identifies which Certificate Authority cert-manager will use to issue a certificate. `Issuer` is a namespaced resource allowing you to use different CAs in each namespace, a `ClusterIssuer` is used to issue certificates in any namespace. Configuration depends on which ACME [challenge](#challenge) you are using. - -### Certificate - -A [Certificate](https://cert-manager.io/docs/concepts/certificate/) is a namespaced resource that references an `Issuer` or `ClusterIssuer` for issuing certificates. `Certificate`s define the DNS name(s) a key and certificate should be issued for, as well as the secret to store those files (e.g. `ambassador-certs`). Configuration depends on which ACME [challenge](#challenge) you are using. - -By duplicating issuers, certificates, and secrets one can support multiple domains with [SNI](../../topics/running/tls/sni). - -## Challenge - -cert-manager supports two kinds of ACME challenges that verify domain ownership in different ways: HTTP-01 and DNS-01. - -### DNS-01 challenge - -The DNS-01 challenge verifies domain ownership by proving you have control over its DNS records. Issuer configuration will depend on your [DNS provider](https://cert-manager.io/docs/configuration/acme/dns01/#supported-dns01-providers). This example uses [AWS Route53](https://cert-manager.io/docs/configuration/acme/dns01/route53/). - -1. Create the IAM policy specified in the cert-manager [AWS Route53](https://cert-manager.io/docs/configuration/acme/dns01/route53/) documentation. - -2. Note the `accessKeyID` and create a `secret` named `prod-route53-credentials-secret` in the cert-manager namespace that has a key value: `secret-access-key` from your AWS IaM credentials. - -3. Create and apply a `ClusterIssuer`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: ClusterIssuer - metadata: - name: letsencrypt-prod - spec: - acme: - email: email@example.com - server: https://acme-v02.api.letsencrypt.org/directory - privateKeySecretRef: - name: letsencrypt-prod - solvers: - - selector: - dnsZones: - - "myzone.route53.com" - dns01: - route53: - region: us-east-1 - accessKeyID: {accessKeyID} - hostedZoneID: {Hosted Zone ID} # optional, allows you to reduce the scope of permissions in Amazon IAM - secretAccessKeySecretRef: - name: prod-route53-credentials-secret - key: secret-access-key - ``` - -4. Create and apply a `Certificate`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: Certificate - metadata: - name: myzone.route53.com - # cert-manager will put the resulting Secret in the same Kubernetes - # namespace as the Certificate. You should create the certificate in - # whichever namespace you want to configure a Host. - spec: - secretName: ambassador-certs - issuerRef: - name: letsencrypt-prod - kind: ClusterIssuer - commonName: myzone.route53.com - dnsNames: - - myzone.route53.com - ``` - -5. Verify the secret is created. - - ``` - $ kubectl get secrets -n ambassador - NAME TYPE DATA AGE - ambassador-certs kubernetes.io/tls 2 1h - ``` - -### HTTP-01 challenge - -The HTTP-01 challenge verifies ownership of the domain by sending a request for a specific file on that domain. cert-manager accomplishes this by sending a request to a temporary pod with the prefix `/.well-known/acme-challenge/`. To perform this challenge: - -1. Create and apply a `ClusterIssuer`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: ClusterIssuer - metadata: - name: letsencrypt-prod - spec: - acme: - email: email@example.com - server: https://acme-v02.api.letsencrypt.org/directory - privateKeySecretRef: - name: letsencrypt-prod - solvers: - - http01: - ingress: - class: nginx - selector: {} - ``` - -2. Create and apply a `Certificate`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: Certificate - metadata: - name: ambassador-certs - # cert-manager will put the resulting Secret in the same Kubernetes - # namespace as the Certificate. You should create the certificate in - # whichever namespace you want to configure a Host. - namespace: ambassador - spec: - secretName: ambassador-certs - issuerRef: - name: letsencrypt-prod - kind: ClusterIssuer - dnsNames: - - example.com - ``` - -3. Apply both the `ClusterIssuer` and `Certificate` - - After applying both of these YAML manifests, you will notice that cert-manager has spun up a temporary pod named `cm-acme-http-solver-xxxx` but no certificate has been issued. Check the cert-manager logs and you will see a log message that looks like this: - - ``` - $ kubectl logs cert-manager-756d6d885d-v7gmg - ... - Preparing certificate default/ambassador-certs with issuer - Calling GetOrder - Calling GetAuthorization - Calling HTTP01ChallengeResponse - Cleaning up old/expired challenges for Certificate default/ambassador-certs - Calling GetChallenge - wrong status code '404' - Looking up Ingresses for selector certmanager.k8s.io/acme-http-domain=161156668,certmanager.k8s.io/acme-http-token=1100680922 - Error preparing issuer for certificate default/ambassador-certs: http-01 self check failed for domain "example.com - ``` - -4. Create a Mapping for the `/.well-known/acme-challenge/` route. - - cert-manager uses an `Ingress` to issue the challenge to `/.well-known/acme-challenge/` that is incompatible with Ambassador. We will need to create a `Mapping` so the cert-manager can reach the temporary pod. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Mapping - metadata: - name: acme-challenge-mapping - spec: - hostname: "*" - prefix: /.well-known/acme-challenge/ - rewrite: "" - service: acme-challenge-service - - --- - apiVersion: v1 - kind: Service - metadata: - name: acme-challenge-service - spec: - ports: - - port: 80 - targetPort: 8089 - selector: - acme.cert-manager.io/http01-solver: "true" - ``` - - Apply the YAML and wait a couple of minutes. cert-manager will retry the challenge and issue the certificate. - -5. Verify the secret is created: - - ``` - $ kubectl get secrets - NAME TYPE DATA AGE - ambassador-certs kubernetes.io/tls 2 1h - ambassador-token-846d5 kubernetes.io/service-account-token 3 2h - ``` diff --git a/content/en/docs/3.4/howtos/client-cert-validation.md b/content/en/docs/3.4/howtos/client-cert-validation.md deleted file mode 100644 index 10fe639d..00000000 --- a/content/en/docs/3.4/howtos/client-cert-validation.md +++ /dev/null @@ -1,110 +0,0 @@ -# Client certificate validation - -[//]: # (+FIX+ link to "TLS and client certs" concept) - -Sometimes, for additional security or authentication purposes, you will want -the server to validate who the client is before establishing an encrypted -connection. - -To support this, $productName$ can be configured to use a provided CA certificate -to validate certificates sent from your clients. This allows for client-side -mTLS where both $productName$ and the client provide and validate each other's -certificates. - -## Prerequisites - -- [openssl](https://www.openssl.org/source/) For creating client certificates -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [$productName$](../../tutorials/getting-started) -- [cURL](https://curl.haxx.se/download.html) - - -## Configuration - -1. Create a certificate and key. - - This can be done with a single command with `openssl`: - - ``` - openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 - ``` - - Enter a passcode for PEM files and fill in the certificate information. - Since this certificate will only be shared between a client and $productName$, - the Common Name must be set to something. Everything else can be left blank. - - **Note:** If using MacOS, - [you must](https://curl.haxx.se/mail/archive-2014-10/0053.html) - add the certificate and key as a PKCS encoded file to your Keychain. To do - this: - - 1. Encode `cert.pem` and `key.pem` created above in PKCS format - - ``` - openssl pkcs12 -inkey key.pem -in cert.pem -export -out certificate.p12 - ``` - - 2. Open "Keychain Access" on your system and select "File"->"Import Items..." - - 3. Navigate to your working directory and select the `certificate.p12` file - we just created above. - -2. Create a secret to hold the client CA certificate. - - ``` - kubectl create secret generic client-cacert --from-file=tls.crt=cert.pem - ``` - -3. Configure $productName$ to use this certificate for client certificate validation. - - First create a `Host` to manage your domain: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Host - metadata: - name: example-host - spec: - hostname: host.example.com - acmeProvider: - email: julian@example.com - ``` - - Then create a `TLSContext` to configure advanced TLS options like client - certificate validation: - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: TLSContext - metadata: - name: example-host-context - spec: - hosts: - - host.example.com - secret: host.example.com - ca_secret: client-cacert - cert_required: false # Optional: Configures $productName$ to reject the request if the client does not provide a certificate. Default: false - ``` - - **Note**: Client certificate validation requires $productName$ be configured to terminate TLS - - $productName$ is now be configured to validate certificates that the client provides. - -4. Test that $productName$ is validating the client certificates with `curl` - - **Linux**: - ``` - curl -v --cert cert.pem --key key.pem https://host.example.com/ - ``` - - **MacOS**: - ``` - curl -v --cert certificate.p12:[password] https://host.example.com/ - ``` - - Looking through the verbose output, you can see we are sending a client - certificate and $productName$ is validating it. - - If you need further proof, simply create a new set of certificates and - try sending the curl with those. You will see $productName$ deny the request. diff --git a/content/en/docs/3.4/howtos/configure-communications.md b/content/en/docs/3.4/howtos/configure-communications.md deleted file mode 100644 index 1ac09d2c..00000000 --- a/content/en/docs/3.4/howtos/configure-communications.md +++ /dev/null @@ -1,763 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -Configuring $productName$ Communications -======================================== - -For $productName$ to do its job of managing network communications for your services, it first needs to know how its own communications should be set up. This is handled by a combination of resources: the `Listener`, the `Host`, and the `TLSContext`. - -- `Listener`: defines where, and how, $productName$ should listen for requests from the network. -- `Host`: defines which hostnames $productName$ should care about, and how to handle different kinds of requests for those hosts. `Host`s can be associated with one or more `Listener`s. -- `TLSContext`: defines whether, and how, $productName$ will manage TLS certificates and options. `TLSContext`s can be associated with one or more `Host`s. - -Once the basic communications setup is in place, $productName$ `Mapping`s and `TCPMapping`s can be associated with `Host`s to actually do routing. - - - Remember that Listener and Host resources are  - required for a functioning $productName$ installation that can route traffic!
- Learn more about Listener.
- Learn more about Host. - - - - Remember than $productName$ does not make sure that a wildcard Host exists! If the - wildcard behavior is needed, a Host with a hostname of "*" - must be defined by the user. - - - - Several different resources work together to configure communications. A working knowledge of all of them - can be very useful:
- Learn more about Listener.
- Learn more about Host.
- Learn more about Mapping.
- Learn more about TCPMapping.
- Learn more about TLSContext. - - -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]: ../../topics/running/tls -[certificates]: ../../topics/running/tls#certificates-and-secrets -[check the logs]: ../../topics/running/debugging#review-logs - -Examples / Cookbook -------------------- - -### Basic HTTP and HTTPS - -A useful configuration is to support either HTTP or HTTPS, in this case on either port 8080 or port 8443. This -tends to make it as easy as possible to communicate with the services behind the $productName$ instance. It uses -two `Listener`s and at least one `Host`. - - -#### `Listener`s: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: http-listener -spec: - port: 8080 - protocol: HTTPS # NOT A TYPO, see below - securityModel: XFP - hostBinding: - namespace: - from: SELF # See below ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: - namespace: - from: SELF # See below -``` - -- Both `Listener`s use `protocol: HTTPS` to allow Envoy to inspect incoming connections, determine - whether or not TLS is in play, and set `X-Forwarded-Proto` appropriately. The `securityModel` then specifies - that `X-Forwarded-Proto` will determine whether requests will be considered secure or insecure. - -- The `hostBinding` shown here will allow any `Host` in the same namespace as the `Listener`s - to be associated with both `Listener`s; in turn, that will allow access to that `Host`'s - `Mapping`s from either port. For greater control, use a `selector` instead. - -- Note that the `Listener`s do not specify anything about TLS certificates. The `Host` - handles that; see below. - - - Learn more about Listener - - -#### `Host` - -This example will assume that we expect to be reachable as `foo.example.com`, and that the `foo.example.com` -certificate is stored in the Kubernetes `Secret` named `foo-secret`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: "foo.example.com" - tlsSecret: - name: foo-secret - requestPolicy: - insecure: - action: Redirect -``` - -- The `tlsSecret` specifies the certificate in use for TLS termination. -- The `requestPolicy` specifies routing HTTPS and redirecting HTTP to HTTPS. -- Since the `Host` does not specify a `selector`, only `Mapping`s with a `hostname` that matches - `foo.example.com` will be associated with this `Host`. -- **Note well** that simply defining a `TLSContext` is not sufficient to terminate TLS: you must define either - a `Host` or an `Ingress`. -- Note that if no `Host` is present, but a TLS secret named `fallback-secret` is available, the system will - currently define a `Host` using `fallback-secret`. **This behavior is subject to change.** - - - Learn more about Host - - -### HTTP-Only - -Another straightforward configuration is to support only HTTP, in this case on port 8080. This uses a single -`Listener` and a single `Host`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: http-listener -spec: - port: 8080 - protocol: HTTP - securityModel: INSECURE - hostBinding: - namespace: - from: SELF # See below ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: "foo.example.com" - requestPolicy: - insecure: - action: Route -``` - -- Here, we listen only on port 8080, and only for HTTP. HTTPS will be rejected. -- Since requests are only allowed using HTTP, we declare all requests `INSECURE` by definition. -- The `Host` specifies routing HTTP, rather than redirecting it. - - - - Learn more about Listener
- Learn more about Host - - -### TLS using ACME ($AESproductName$ only) - -This scenario uses ACME to get certificates for `foo.example.com` and `bar.example.com`. HTTPS traffic to either -host is routed; HTTP traffic to `foo.example.com` will be redirected to HTTPS, but HTTP traffic to `bar.example.com` -will be rejected outright. - -Since this example uses ACME, **it is only supported in $AESproductName$**. - -For demonstration purposes, we show this example listening for HTTPS on port 9999, using `X-Forwarded-Proto`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener-9999 -spec: - port: 9999 - protocol: HTTPS - securityModel: XFP - hostBinding: # Edit as needed - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - acmeProvider: - email: julian@example.com ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - acmeProvider: - email: julian@example.com - requestPolicy: - insecure: - action: Reject -``` - -(`Mapping`s are not shown.) - -- Our `Listener`s will accept HTTPS and HTTP on port 9999, and the protocol used will dictate whether - the requests are secure (HTTPS) or insecure (HTTP). -- `foo-host` defaults to ACME with Let's Encrypt, since `acmeProvider.authority` is not provided. -- `foo-host` defaults to redirecting insecure requests, since the default for `requestPolicy.insecure.action` is `Redirect`. -- `bar-host` uses Let's Encrypt as well, but it will reject insecure requests. - -**If you use ACME for multiple Hosts, add a wildcard Host too.** -This is required to manage a known issue. This issue will be resolved in a future Ambassador Edge Stack release. - - - Learn more about Listener
- Learn more about Host - - -### Multiple TLS Certificates - -This scenario uses TLS without ACME. Each of our two `Host`s uses a distinct TLS certificate. HTTPS -traffic to either`foo.example.com` or `bar.example.com` is routed, but this time `foo.example.com` will redirect -HTTP requests, while `bar.example.com` will route them. - -Since this example does not use ACME, it is supported in $productName$ as well as $AESproductName$. - -For demonstration purposes, we show this example listening for HTTPS on port 4848, using `X-Forwarded-Proto`. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: foo-example-secret -data: - tls.crt: -certificate PEM- - tls.key: -secret key PEM- ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: bar-example-secret -data: - tls.crt: -certificate PEM- - tls.key: -secret key PEM- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener-4848 -spec: - port: 4848 - protocol: HTTPS - securityModel: XFP - hostBinding: # Edit as needed - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - tlsSecret: - name: foo-example-secret ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - tlsSecret: - name: bar-example-secret - requestPolicy: - insecure: - action: Route -``` - -- `foo-host` and `bar-host` simply reference the `tlsSecret` to use for termination. - - If the secret involved contains a wildcard cert, or a cert with multiple SAN, both `Host`s could - reference the same `tlsSecret`. -- `foo-host` relies on the default insecure routing action of `Redirect`. -- `bar-host` must explicitly specify routing HTTP. - - - - Learn more about Listener
- Learn more about Host - - -### Using a `TLSContext` - -If you need to share other TLS settings between two `Host`s, you can reference a `TLSContext` as well as -the `tlsSecret`. This is the same as the previous example, but we use a `TLSContext` to set `ALPN` information, -and we assume that the `Secret` contains a wildcard cert. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: wildcard-example-secret -data: - tls.crt: -wildcard here- - tls.key: -wildcard here- ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-context -spec: - secret: wildcard-example-secret - alpn_protocols: [h2, istio] ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener-4848 -spec: - port: 4848 - protocol: HTTPS - securityModel: XFP - hostBinding: # Edit as needed - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - tlsContext: - name: example-context - tlsSecret: - name: wildcard-example-secret ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - tlsContext: - name: example-context - tlsSecret: - name: wildcard-example-secret - requestPolicy: - insecure: - action: Route -``` - -- Note that specifying the `tlsSecret` is still necessary, even when `tlsContext` is specified. - - - - Learn more about Listener
- Learn more about Host - - -### ACME With a TLSContext ($AESproductName$ Only) - -In $AESproductName$, you can use a `TLSContext` with ACME as well. This example is the same as "TLS using ACME", -but we use a `TLSContext` to set `ALPN` information. Again, ACME is only supported in $AESproductName$. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-context -spec: - secret: example-acme-secret - alpn_protocols: [h2, istio] ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - acmeProvider: - email: julian@example.com - tlsContext: - name: example-context - tlsSecret: - name: example-acme-secret -``` - -- Note that we don't provide the `Secret`: the ACME client will create it for us. - - - - Learn more about Listener
- Learn more about Host - - -### Using an L7 Load Balancer to Terminate TLS - -In this scenario, a layer 7 load balancer ahead of $productName$ will terminate TLS, so $productName$ will always see HTTP with a known good `X-Forwarded-Protocol`. We'll use that to route HTTPS and redirect HTTP. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: lb-listener -spec: - port: 8443 - protocol: HTTP - securityModel: XFP - l7Depth: 1 - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: "foo.example.com" - requestPolicy: - insecure: - action: Redirect -``` - -- We set `l7Depth` to 1 to indicate that there's a single trusted L7 load balancer ahead of us. -- We specifically set this Listener to HTTP-only, but we stick with port 8443 just because we expect people setting up TLS at all to expect to use port 8443. (There's nothing special about the port number, pick whatever you like.) -- Our `Host` does not specify a `tlsSecret`, so $productName$ will not try to terminate TLS. -- Since the `Listener` still pays attention to `X-Forwarded-Proto`, both secure and insecure requests - are possible, and we use the `Host` to route HTTPS and redirect HTTP. - - - - Learn more about Listener
- Learn more about Host - - -### Using a Split L4 Load Balancer to Terminate TLS - -Here, we assume that $productName$ is behind a load balancer setup that handles TLS at layer 4: - -- Incoming cleartext traffic is forwarded to $productName$ on port 8080. -- Incoming TLS traffic is terminated at the load balancer, then forwarded to $productName$ _as cleartext_ on port 8443. -- This might involve multiple L4 load balancers, but the actual number doesn't matter. -- The actual port numbers we use don't matter either, as long as $productName$ and the load balancer(s) agree on which port is for which traffic. - -We're going to route HTTPS for both `foo.example.com` and `bar.example.com`, redirect HTTP for `foo.example.com`, and reject HTTP for `bar.example.com`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: split-lb-one-listener -spec: - protocol: HTTP - port: 8080 - securityModel: INSECURE - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: split-lb-two-listener -spec: - protocol: HTTP - port: 8443 - securityModel: SECURE - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - requestPolicy: - insecure: - action: Reject -``` - -- Since L4 load balancers cannot set `X-Forwarded-Protocol`, we don't use it at all here: instead, we dictate that 8080 and 8443 both speak cleartext HTTP, but everything arriving at port 8080 is insecure and everything at port 8443 is secure. - - - - Learn more about Listener
- Learn more about Host - - -### Listening on Multiple Ports - -There's no reason you need to use ports 8080 and 8443, or that you're limited to two ports. Here we'll use ports 9001 and 9002 for HTTP, and port 4001 for HTTPS. We'll route traffic irrespective of protocol. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-9001 -spec: - protocol: HTTP - port: 9001 - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-9002 -spec: - protocol: HTTP - port: 9002 - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-4001 -spec: - protocol: HTTPS - port: 4001 - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: route-host -spec: - requestPolicy: - insecure: - action: Route -``` - -- We can use `X-Forwarded-Proto` for all our `Listener`s: the HTTP-only `Listener`s will set it correctly. -- Each `Listener` can specify only one port, but there's no hardcoded limit on the number of `Listener`s you can have. - - - - Learn more about Listener
- Learn more about Host - - -### Using Labels to Associate `Host`s and `Listener`s - -In the examples above, the `Listener`s all associate with any `Host` in their namespace. In this -example, we will use Kubernetes labels to control the association instead. - -Here, we'll listen for HTTP to `foo.example.com` on port 8888, and for either HTTP or HTTPS to `bar.example.com` on -port 9999 (where we'll redirect HTTP to HTTPS). Traffic to `baz.example.com` will work on both ports, and we'll route -HTTP for it rather than redirecting. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-8888 -spec: - protocol: HTTP - port: 8888 - securityModel: XFP - hostBinding: - selector: - matchLabels: - tenant: foo ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-9999 -spec: - protocol: HTTPS - port: 9999 - securityModel: XFP - hostBinding: - selector: - matchLabels: - tenant: bar ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: bar-secret -data: - tls.crt: -wildcard here- - tls.key: -wildcard here- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host - labels: - tenant: foo -spec: - hostname: foo.example.com - requestPolicy: - insecure: - action: Route ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host - labels: - tenant: bar -spec: - hostname: bar.example.com - tlsSecret: - name: bar-secret ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: baz-host - labels: - tenant: foo - tenant: bar -spec: - hostname: baz.example.com - tlsSecret: - name: bar-secret - requestPolicy: - insecure: - action: Route -``` - -- Note the `labels` on each `Host`, which the `hostBinding` on the `Listener` can reference. - - Note also that only label selectors are supported at the moment. - - - - Learn more about Listener
- Learn more about Host - - -### Wildcard `Host`s and `Mapping`s - -In a `Mapping`, the `host` is now treated as a glob rather than an exact match, with the goal of vastly reducing the need for `host_regex`. (The `hostname` in a `Host` has always been treated as a glob). - -- **Note that only prefix and suffix matches are supported**, so `*.example.com` and `foo.*` are both fine, but `foo.*.com` will not work -- you'll need to use `host_regex` if you really need that. (This is an Envoy limitation.) - -In this example, we'll accept both HTTP and HTTPS, but: - -- Cleartext traffic to any host in `lowsec.example.com` will be routed. -- Cleartext traffic to any host in `normal.example.com` will be redirected. -- Any other cleartext traffic will be rejected. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: example-secret -data: - tls.crt: -wildcard for *.example.com here- - tls.key: -wildcard for *.example.com here- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-8443 -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: lowsec-host -spec: - hostname: "*.lowsec.example.com" - tlsSecret: - name: example-secret - requestPolicy: - insecure: - action: Route ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: normal-host -spec: - hostname: "*.normal.example.com" - tlsSecret: - name: example-secret - requestPolicy: # We could leave this out since - insecure: # redirecting is the default, but - action: Redirect # it's spelled out for clarity. ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: catchall-host -spec: - hostname: "*.example.com" - tlsSecret: - name: example-secret - requestPolicy: - insecure: - action: Reject -``` - -- We'll listen for HTTP or HTTPS on port 8443. -- The three `Host`s apply different insecure routing actions depending on the hostname. -- You could also do this with `host_regex`, but using `host` with globs will give better performance. - - Being able to _not_ associate a given `Mapping` with a given `Host` when the `Mapping`'s - `host` doesn't match helps a lot when you have many `Host`s. - - Reliably determining if a regex (for the `Mapping`) matches a glob (for the `Host`) isn't really possible, so we can't prune `host_regex` `Mapping`s at all. - - - Learn more about Listener
- Learn more about Host - diff --git a/content/en/docs/3.4/howtos/consul.md b/content/en/docs/3.4/howtos/consul.md deleted file mode 100644 index d75e35ce..00000000 --- a/content/en/docs/3.4/howtos/consul.md +++ /dev/null @@ -1,564 +0,0 @@ - -import Alert from '@material-ui/lab/Alert'; - -# Consul integration - -
-

Contents

- -- [Consul integration](#consul-integration) - - [Architecture overview](#architecture-overview) - - [Installing Consul](#installing-consul) - - [Installing $productName$](#installing-consul) - - [Using Consul for service discovery](#using-consul-for-service-discovery) - - [Using Consul for authorization and encryption](#using-consul-for-authorization-and-encryption) - - [Environment variables](#environment-variables) - - [More information](#more-information) - -
- -[Consul](https://www.consul.io) is a widely used service mesh. -$productName$ natively supports service discovery and unauthenticated -communication to services in Consul. Additionally, the *Ambassador -Consul Connector* enables $productName$ to encrypt and authenticate -its communication via mTLS with services in Consul that make use of -[Consul's *Connect* feature](https://www.consul.io/docs/connect). - -## Architecture overview - -Using Consul with $productName$ is particularly useful when deploying -$productName$ in hybrid cloud environments where you deploy -applications on VMs and Kubernetes. In this environment, Consul -enables $productName$ to securely route over TLS to any application -regardless of where it is deployed. - -In this architecture, Consul serves as the source of truth for your -entire data center, tracking available endpoints, service -configuration, and secrets for TLS encryption. New applications and -services automatically register themselves with Consul using the -Consul agent or API. When you send a request through $productName$, -$productName$ sends the request to an endpoint based on the data in -Consul. - -![ambassador-consul](../images/consul-ambassador.png) - -This guide first instructs you on registering a service with Consul -and using $productName$ to dynamically route requests to that service -based on Consul's service discovery data, and subsequently instructs -you on using using the Ambassador Consul Connector to use Consul for -authorizing and encrypting requests. - -## Installing Consul - -If you already have Consul installed in your cluster, then go ahead -and skip to the next section. - -1. Before you install Consul, make sure to check the Consul - documentation for any setup steps specific to your platform. Below - you can find setup guides for some of the more popular Kubernetes - platforms. This step is primarily to ensure you have the proper - permissions to set up Consul. You can skip these guides if your - cluster is already configured to grant you the necessary - permissions. - - - [Microsoft Azure Kubernetes Service (AKS)](https://learn.hashicorp.com/tutorials/consul/kubernetes-aks-azure?utm_source=consul.io&utm_medium=docs) - - [Amazon Elastic Kubernetes Service (EKS)](https://learn.hashicorp.com/tutorials/consul/kubernetes-eks-aws?utm_source=consul.io&utm_medium=docs) - - [Google Kubernetes Engine (GKE)](https://learn.hashicorp.com/tutorials/consul/kubernetes-gke-google?utm_source=consul.io&utm_medium=docs) - - - - If you did not find your Kubernetes platform above, check the - [Consul documentation here](https://www.consul.io/docs/k8s) to see - if there are specific setup instructions for your platform. - - - -2. Add the Hashicorp repository for installing Consul with Helm. If - you do not have Helm installed, you can find an [installation guide - here](https://helm.sh/docs/intro/install/). - - ```shell - helm repo add hashicorp https://helm.releases.hashicorp.com - ``` - -3. Create a new `consul-values.yaml` YAML file for the Consul - installation values and copy the values below into that file. - - ```yaml - global: - datacenter: dc1 - - ui: - service: - type: 'LoadBalancer' - - syncCatalog: - enabled: true - - server: - replicas: 1 - bootstrapExpect: 1 - - connectInject: - enabled: true - ``` - - - - Note: you are free to change the value of the `datacenter` field in - the install values. This is the the name of your Consul - Datacenter. - - - -4. Install Consul with Helm using the `consul-values.yaml` values file - you just created. - - ```shell - helm install -f consul-values.yaml hashicorp hashicorp/consul - ``` - -## Installing $productName$ - -If you have not already installed $productName$ in to your cluster, -then go to the [quick start guide](../../tutorials/getting-started) -before continuing any further in this guide. - -## Using Consul for service discovery - -This section of the guide instructs you on configuring $productName$ -to look for services registered to Consul, registering a demo -application with Consul, and configuring $productName$ to route to -this application using endpoint data from Consul. - -In this tutorial, you deploy the application in Kubernetes. However, -this application can be deployed anywhere in your data center, such as -on a VM. - -1. Configure $productName$ to look for services registered to Consul - by creating the `ConsulResolver`. Use `kubectl` to apply the - following manifest: - - ```shell - kubectl apply -f < - - **Note:** If you changed the name of your `datacenter` in the - Consul install values, make sure to change it in the resolver above - to match the name of your datacenter. - - If you changed the name of the helm install from `hashicorp` to - another value, make sure to update the value of the `address` field - in your resolver to match it. - - If you are having trouble figuring out what your `address` field - should be, it follow this format: - `http://{consul_server_pod}.{consul_server_service}.{namespace}.svc.cluster.local:{consul_port}`. - The default Consul port should be `8500` unless you changed it. - - - - This tells $productName$ that Consul is a service discovery endpoint. - - You must set the resolver to your `ConsulResolver` on a - per-`Mapping` basis, otherwise for that `Mapping` $productName$ - uses the default resolver. That is, in order for a `Mapping` to - make use of a service registered in Consul, you need to add - `resolver: consul-dc1` to that `Mapping`. - - For more information about resolver configuration, see the - [resolver reference documentation](../../topics/running/resolvers). - (If you're using Consul deployed elsewhere in your data center, - make sure the `address` points to your Consul FQDN or IP address). - -2. Deploy the Quote demo application. Use `kubectl` to - apply the following manifest: - - ```shell - kubectl apply -f < - - The `SERVICE_NAME` environment variable in the `quote-consul` - `Deployment` specifies the service name for Consul. The default - value is set to "quote-consul", so you only need to include it if - you want to change the service name. - - - - The Quote application contains code to automatically - register itself with Consul, using the `CONSUL_IP` and `POD_IP` - environment variables specified within the `quote-consul` container - spec. - - When you apply this manifest, it registers the `Pod` in the - `quote-consul` `Deployment` as a Consul service with the name - `quote-consul` and the IP address of the `Pod`. - - - - The `"consul.hashicorp.com/connect-inject": "false"` annotation - tells Consul that for this `Deployment` you do not want to use the - sidecar proxy that is part of Consul's Connect feature. Without - Consul's sidecar, the service needs to include code to make a - request to Consul to register the service. The manifest includes - the environment variables `CONSUL_IP`, `POD_IP`, and `SERVICE_NAME` - to provide the Quote service with enough information - to build that request and send it to Consul. To see how this code - works, see our [our Git repo for the Quote - service](https://github.com/datawire/quote). - - - -3. Verify the `quote-consul` `Deployment`'s `Pod` has been registered - with Consul. You can verify this by accessing the Consul UI. - - First use `kubectl port-forward` to make the UI available on your - local workstation: - - ```shell - kubectl port-forward service/hashicorp-consul-ui 8500:80 - ``` - - Then, while the port-forward is running, go to - http://localhost:8500/ in a web browser. You should see a service - named `quote-consul`. - - After you have verified that you see the `quote-consul` service in - your web browser, you may kill the port-forward. - - - - Port forwarding not working for you? Make sure the service name - matches your Consul UI service by checking `kubectl get svc -A` - - - -4. Configure $productName$ to make use of this `quote-consul` service. - Use `kubectl` to apply the following manifest: - - ```shell - kubectl apply -f < - -**Congratulations!** You're successfully routing traffic to the Quote -application, the location of which is registered in -Consul. - - - -## Using Consul for authorization and encryption - -In this part of the guide, you'll install a different version of the -demo application that now uses Consul's *Connect* feature to authorize -its incoming connections using mTLS, and install *Ambassador Consul -Connector* to enable $productName$ to authenticate to such services. - -The following steps assume you've already set up Consul for service -discovery, as detailed above. - -1. The Ambassador Consul Connector retrieves the TLS certificate - issued by the Consul CA and stores it in a Kubernetes `Secret` for - $productName$ to use. Deploy the Ambassador Consul Connector with - `kubectl`: - - ```shell - kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/consul/ambassador-consul-connector.yaml - ``` - - This installs in to your cluster: - - - RBAC resources. - - The Ambassador Consul Connector service. - - A `TLSContext` named `ambassador-consul` to load the - `ambassador-consul-connect` `Secret` into $productName$. - -2. Deploy a new version of the demo application, and configure it to - inject the Consul Connect sidecar by setting - `"consul.hashicorp.com/connect-inject"` to `true`. Note that in - this version of the configuration, you do not have to configure - environment variables for the location of the Consul server. Use - `kubectl` to apply the following manifest: - - ```yaml - kubectl apply -f - < - - Note: Annotations are used to attach metadata to Kubernetes - objects. You can use annotations to link external information to - objects, working in a similar, yet different, fashion to labels. - For more information on annotations, refer to the [Annotating - Kubernetes Services for - Humans](https://kubernetes.io/blog/2021/04/20/annotating-k8s-for-humans/) - article, or get started with annotations in your own cluster with - the [Ambassador Cloud Quick start - guide](https://www.getambassador.io/docs/cloud/latest/service-catalog/quick-start/). - - - - This deploys a demo application `Deployment` called `quote-connect` - (different than the `quote-consul` `Deployment` in the previous - section) with the Consul Connect sidecar proxy. The Connect - sidecar registers the application with Consul, requires TLS to - access the application, and exposes other [Consul Service - Segmentation](https://www.consul.io/docs/connect) features. - - The annotation `consul.hashicorp.com/connect-inject` being set to - `true` in this `Deployment` tells Consul that you want this - `Deployment` to use the Consul Connect sidecar. The sidecar - proxies requests to the service that it is attached to. Keep this - in mind mind when debug requests to the service. - -4. Verify the `quote-connect` `Deployment`'s `Pod` has been registered - with Consul. You can verify this by accessing the Consul UI. - - First use `kubectl port-forward` to make the UI available on your - local workstation: - - ```shell - kubectl port-forward service/hashicorp-consul-ui 8500:80 - ``` - - Then, while the port-forward is running, open - http://localhost:8500/ in a web browser. You should see a service - named `quote-connect`. - - After you have verified that you see the `quote-connect` service in - your web browser, you may kill the port-forward. - -5. Create a `Mapping` to configure $productName$ route to the - `quote-connect` service in Consul. Use `kubectl` to apply the - following manifest: - - ```shell - kubectl apply -f < - -**Congratulations!** You successfully configured the service to work -with the Consul Connect sidecar. - - - -### Environment variables - -The Ambassador Consul Connector can be configured with the following -environment variables. The defaults are best for most use-cases. - -| Environment Variable | Description | Default | -|------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------| -| `_AMBASSADOR_ID` | Set 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`) | `""` | -| `_CONSUL_HOST` | Set the IP or DNS name of the target Consul HTTP API server | `127.0.0.1` | -| `_CONSUL_PORT` | Set the port number of the target Consul HTTP API server | `8500` | -| `_AMBASSADOR_TLS_SECRET_NAME` | Set the name of the Kubernetes `v1.Secret` created by this program that contains the Consul-generated TLS certificate. | `$AMBASSADOR_ID-consul-connect` | -| `_AMBASSADOR_TLS_SECRET_NAMESPACE` | Set the namespace of the Kubernetes `v1.Secret` created by this program. | (same Namespace as the Pod running this integration) | - -## More information - -For more about $productName$'s integration with Consul, read the -[service discovery configuration](../../topics/running/resolvers) -documentation. diff --git a/content/en/docs/3.4/howtos/dist-tracing.md b/content/en/docs/3.4/howtos/dist-tracing.md deleted file mode 100644 index bc40df8f..00000000 --- a/content/en/docs/3.4/howtos/dist-tracing.md +++ /dev/null @@ -1,49 +0,0 @@ -# Explore distributed tracing and Kubernetes monitoring - -The Kubernetes monitoring and distributed tracing landscape is hard to grasp. Although this conceptual approach to [observability is nothing new](https://blog.getambassador.io/distributed-tracing-with-java-microdonuts-kubernetes-and-the-ambassador-api-gateway-ace15b62a89e) — companies like New Relic revolutionized single-application performance monitoring (APM) over a decade ago — it took a few years and the [Dapper publication](https://research.google/pubs/pub36356/) for this idea to migrate to distributed applications. The importance of this technology is only increasing, as more and more of us are building [“deep systems”](https://lightstep.com/deep-systems/). - -As the industry is slowly but surely maturing, standardization is underway. Standardization means proprietary vendor solutions and open source projects are able to collaborate, making our lives easier. For newcomers, understanding the plethora of options, concepts, specifications, and implementations available is still a daunting task: - -* How are Zipkin and Jaeger related? -* What is header propagation? -* Which headers format should I use? -* Who owns the initialization of a trace context? -* How are the data points collected? - -The [K8s Initializer](https://app.getambassador.io/initializer/) can make it easy to enable distributed tracing in any microservices-based system by offering an opinionated and preconfigured application stack that will get you up and running in no time. This way, you can focus on understanding your service topology and interactions rather than waste days on attempting to understand competing standard integrations and tuning configuration switches. - -## One-Click Tracing Configuration with the K8s Initializer - -The K8s Initializer is a tool we built for you to quickly bootstrap any Kubernetes cluster with your own application-ready playground. It will generate YAML manifests for ingress, observability, and more in just a few clicks. Once installed on a local or remote Kubernetes cluster, the generated Kubernetes manifest resources will give you a perfect sandbox environment to deploy your own applications and explore standard integrations. - -Specifically for observability and distributed tracing, the K8s Initializer bundles a Jaeger installation to collect and visualize traces along with a pre-configured Ambassador Edge Stack acting as the ingress controller that will create a trace context on every request. A single selection is required. - -As per the option we selected, we’ll be generating Zipkin-format traces and use B3 headers for propagation between our services. There you have it! Instrument your Java, Python, Golang or Node.js applications with Zipkin and B3 header propagation libraries, then configure your code to send the trace data to the `jaeger-collector.monitoring:9411` service endpoint. - -All that is left to do is making a few requests and visualizing the trace data in the Jaeger UI. - -## Visualizing Trace Data - -As we installed the Ambassador Edge Stack as our ingress controller for Kubernetes via the K8s Initializer, it will instrument parent trace spans for each request coming into our Kubernetes cluster from the internet. The K8s Initializer also pre-configured Ambassador to exposes the Jaeger UI on a subpath: `https://$AMBASSADOR_IP/jaeger/` - -Simply by visiting this URL on our installation, we are able to visualize the generated and collected trace information emitted by our Ambassador installation: - -![Jaeger screenshot](../images/jaeger.png) - -## Tracing the Future: OpenTelemetry - -The [OpenTelemetry project](https://opentelemetry.io/) was created with the intent of stopping the proliferation of API standards and libraries one might need to support for all their observability needs, effectively replacing the Zipkin-API, OpenCensus, OpenTracing and more competing implementations. - -> OpenTelemetry provides a single set of APIs, libraries, agents, and collector services to capture distributed traces and metrics from your application. You can analyze them using Prometheus, Jaeger, and other observability tools.
--[https://opentelemetry.io/](https://opentelemetry.io/) - -It’s at this point in the conversation that someone inevitably mentions that XKCD... - -![XKCD #927](../images/xkcd.png) - -OpenTelemetry ultimately supports multiple formats in its [OpenTelemetry-Collector](https://github.com/open-telemetry/opentelemetry-collector), easing the transition from one technology to another when installed as a middleware and translator to relay trace data to other collectors. Along with many of its long-awaited features, it supports multiple trace exporters for Jaeger, Zipkin and proprietary APIs. - -## Learn More -In this tutorial, we’ve shown you how to monitor your Kubernetes application with distributed tracing in just a few clicks with the K8s Initializer. To learn more about these tools and distributed tracing, we also recommend [A Complete Guide to Distributed Tracing by the Lightstep Team](https://lightstep.com/distributed-tracing/). - -We also have guides to setup Edge Stack with [Datadog](../tracing-datadog/), [Zipkin](../tracing-zipkin/), and [Prometheus and Grafana](../prometheus). diff --git a/content/en/docs/3.4/howtos/external-dns.md b/content/en/docs/3.4/howtos/external-dns.md deleted file mode 100644 index f0f51dbb..00000000 --- a/content/en/docs/3.4/howtos/external-dns.md +++ /dev/null @@ -1,130 +0,0 @@ -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 - -Start by checking the [ExternalDNS repo's deployment instructions](https://github.com/kubernetes-sigs/external-dns#deploying-to-a-cluster) to get information about the supported DNS providers and steps to setup ExternalDNS for your provider. Each DNS provider will have its own required steps as well as annotations, arguments, and permissions needed for the following configuration. - - -### Installation - -Configuration for a `ServiceAccount`, `ClusterRole`, and `ClusterRoleBinding` are necessary for the ExternalDNS deployment to support compatability 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 above for annotations and arguments for your DNS Provider. - - -1. Create a YAML file named `externaldns-config.yaml`, and copy the following configuration into it. - - - Ensure that the apiGroups include "getambassador.io" following "networking.k8s.io" and the resources include "hosts" after "ingresses". - - - ```yaml - --- - apiVersion: v1 - kind: ServiceAccount - metadata: - name: external-dns - annotations: - eks.amazonaws.com/role-arn: {ARN} # AWS ARN role - --- - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRole - metadata: - name: external-dns - rules: - - apiGroups: [""] - resources: ["services","endpoints","pods"] - verbs: ["get","watch","list"] - - apiGroups: ["extensions","networking.k8s.io", "getambassador.io"] - resources: ["ingresses", "hosts"] - verbs: ["get","watch","list"] - - apiGroups: [""] - resources: ["nodes"] - verbs: ["list","watch"] - --- - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRoleBinding - metadata: - name: external-dns-viewer - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: external-dns - subjects: - - kind: ServiceAccount - name: external-dns - namespace: default - --- - apiVersion: apps/v1 - kind: Deployment - metadata: - name: external-dns - spec: - strategy: - type: Recreate - selector: - matchLabels: - app: external-dns - template: - metadata: - labels: - app: external-dns - annotations: - iam.amazonaws.com/role: {ARN} # AWS ARN role - spec: - serviceAccountName: external-dns - containers: - - name: external-dns - image: registry.opensource.zalan.do/teapot/external-dns:latest - args: - - --source=ambassador-host - - --domain-filter=example.net # will make ExternalDNS see only the hosted zones matching provided domain, omit to process all available hosted zones - - --provider=aws - - --policy=upsert-only # would prevent ExternalDNS from deleting any records, omit to enable full synchronization - - --aws-zone-type=public # only look at public hosted zones (valid values are public, private or no value for both) - - --registry=txt - - --txt-owner-id= {Hosted Zone ID} # Insert Route53 Hosted Zone ID here - ``` - -2. Review the arguments section from the ExternalDNS deployment - - Configure or remove arguments to fit your needs. Additional arguments required for your DNS provider can be found by checking the [ExternalDNS repo's deployment instructions](https://github.com/kubernetes-sigs/external-dns#deploying-to-a-cluster). - - * `--source=ambassador-host` - required across all DNS providers to tell ExternalDNS to look for hostnames in the $productName$ `Host` configurations. - -3. Apply the above config with the following command to deploy ExternalDNS to your cluster and configure support for $productName$ - - ```shell - kubectl apply -f externaldns-ambassador.yaml - ``` - - - For the above example, ensure that you are using an EKS cluster, or register your cluster with AWS so that ExternalDNS can view and edit your AWS Hosted Zones. If you are using a cluster outside EKS and not registered with AWS you will see permissions errors from the ExternalDNS pod when attempting to list the Hosted Zones. - - -## Usage - -After applying the above configuration, ExternalDNS is ready to use. Configure a `Host` with the following annotation to allow ExternalDNS to get the IP address of your $productName$'s LoadBalancer and register it with your DNS provider. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: your-hostname - annotations: - external-dns.ambassador-service: $productDeploymentName$.$productNamespace$ -spec: - acmeProvider: - authority: none - hostname: your-hostname.example.com -``` - - -Victory! ExternalDNS is now running and configured to report $productName$'s IP and hostname with your DNS provider. diff --git a/content/en/docs/3.4/howtos/filter-dev-guide.md b/content/en/docs/3.4/howtos/filter-dev-guide.md deleted file mode 100644 index eefe8b6b..00000000 --- a/content/en/docs/3.4/howtos/filter-dev-guide.md +++ /dev/null @@ -1,97 +0,0 @@ -# Developing custom filters for routing - -Sometimes you may want $AESproductName$ to manipulate an incoming request. Some example use cases: - -* Inspect an incoming request, and add a custom header that can then be used for routing -* Add custom Authorization headers -* Validate an incoming request fits an OpenAPI specification before passing the request to a target service - -$AESproductName$ supports these use cases by allowing you to execute custom logic in `Filters`. Filters are written in Golang, and managed by $AESproductName$. If you want to write a filter in a language other than Golang, $AESproductName$ also has an HTTP/gRPC interface for Filters called `External`. - -## Prerequisites - -`Plugin` `Filter`s are built as [Go plugins](https://golang.org/pkg/plugin/) and loaded directly into the $AESproductName$ container so they can run in-process with the rest of $AESproductName$. - -To build a `Plugin` `Filter` into the $AESproductName$ container you will need -- Linux or MacOS host (Windows Subsystem for Linux is ok) -- [Docker](https://docs.docker.com/install/) -- [rsync](https://rsync.samba.org/) - -The `Plugin` `Filter` is built by `make` which uses Docker to create a stable build environment in a container and `rsync` to copy files between the container and your host machine. - -See the [README](https://github.com/datawire/apro-example-plugin) for more information on how the `Plugin` works. - -## Creating and deploying filters - -We've created an example filter that you can customize for your particular use case. - -1. Start with the example filter: `git clone - https://github.com/datawire/apro-example-plugin/`. - -2. Make code changes to `param-plugin.go`. Note: If you're developing a non-trivial filter, see the rapid development section below for a faster way to develop and test your filter. - -3. Run `make DOCKER_REGISTRY=...`, setting `DOCKER_REGISTRY` to point - to a registry you have access to. This will generate a Docker image - named `$DOCKER_REGISTRY/amb-sidecar-plugin:VERSION`. - -4. Push the image to your Docker registry: `docker push $DOCKER_REGISTRY/amb-sidecar-plugin:VERSION`. - -5. Configure $AESproductName$ to use the plugin by creating a `Filter` - and `FilterPolicy` CRD, as per the [filter reference](/docs/edge-stack/latest/topics/using/filters/). - -6. Update the standard $AESproductName$ manifest to use your Docker - image instead of the standard sidecar. - - ```patch - value: '60' - - name: AMBASSADOR_INTERNAL_URL - value: https://127.0.0.1:8443 - - image: docker.io/datawire/aes:$version$ - + image: DOCKER_REGISTRY/aes-plugin:VERSION - imagePullPolicy: Always - livenessProbe: - httpGet: - ``` - -## Rapid development of a custom filter - -During development, you may want to sidestep the deployment process for a faster development loop. The `aes-plugin-runner` helps you rapidly develop $AESproductName$ filters locally. - -To install the runner, download the latest version: - -Mac 64-bit | -Linux 64-bit - -Note that the plugin runner must match the version of $AESproductName$ that you are running. Place the binary somewhere in your `$PATH`. - -Information about open-source code used in `aes-plugin-runner` can be found by running `aes-plugin-runner --version`. - -Now, you can quickly test and develop your filter. - -1. In your filter directory, type: `aes-plugin-runner :8080 ./param-plugin.so`. -2. Test the filter by running `curl`: - - ``` - $ curl -Lv localhost:8080?db=2 - * Rebuilt URL to: localhost:8080/?db=2 - * Trying ::1... - * TCP_NODELAY set - * Connected to localhost (::1) port 8080 (#0) - > GET /?db=2 HTTP/1.1 - > Host: localhost:8080 - > User-Agent: curl/7.54.0 - > Accept: */* - > - < HTTP/1.1 200 OK - < X-Dc: Even - < Date: Mon, 25 Feb 2019 19:58:38 GMT - < Content-Length: 0 - < - * Connection #0 to host localhost left intact - ``` - -Note in the example above the `X-Dc` header is added. This lets you inspect the changes the filter is making to your HTTP header. - -## Further reading - -For more details about configuring filters and the `plugin` interface, see the [filter reference](/docs/edge-stack/latest/topics/using/filters/). diff --git a/content/en/docs/3.4/howtos/grpc.md b/content/en/docs/3.4/howtos/grpc.md deleted file mode 100644 index 3967ddf7..00000000 --- a/content/en/docs/3.4/howtos/grpc.md +++ /dev/null @@ -1,403 +0,0 @@ -# gRPC Connections - -$productName$ makes it easy to access your services from outside your application. This includes gRPC services, although a little bit of additional configuration is required: by default, Envoy connects to upstream services using HTTP/1.x and then upgrades to HTTP/2 whenever possible. However, gRPC is built on HTTP/2 and most gRPC servers do not speak HTTP/1.x at all. $productName$ must tell its underlying Envoy that your gRPC service only wants to speak to that HTTP/2, using the `grpc` attribute of a `Mapping`. - -## Writing a gRPC service for $productName$ - -There are many examples and walkthroughs on how to write gRPC applications so that is not what this article will aim to accomplish. If you do not yet have a service written you can find examples of gRPC services in all supported languages here: [gRPC Quickstart](https://grpc.io/docs/quickstart/) - -This document will use the [gRPC python helloworld example](https://github.com/grpc/grpc/tree/master/examples/python/helloworld) to demonstrate how to configure a gRPC service with $productName$. - -Follow the example up through [Run a gRPC application](https://grpc.io/docs/languages/python/quickstart/#run-a-grpc-application) to get started. - -### Dockerize - -After building our gRPC application and testing it locally, we need to package it as a Docker container and deploy it to Kubernetes. - -To run a gRPC application, we need to include the client/server and the protocol buffer definitions. - -For gRPC with python, we need to install `grpcio` and the common protos. - -```Dockerfile -FROM python:2.7 - -WORKDIR /grpc - -ENV PATH "$PATH:/grpc" - -COPY greeter_server.py /grpc -COPY helloworld_pb2.py /grpc -COPY helloworld_pb2_grpc.py /grpc - -RUN python -m pip install grpcio -RUN python -m pip install grpcio-tools googleapis-common-protos - -CMD ["python", "./greeter_server.py"] - -EXPOSE 50051 -``` - -Create the container and test it: - -``` -$ docker build -t /grpc_example -$ docker run -p 50051:50051 /grpc_example -``` - -Where `` is your Docker user or registry. - -Switch to another terminal and from the same directory, run the `greeter_client`. The output should be the same as running it outside of the container. - -``` -$ docker run -p 50051:50051 /grpc_example -Greeter client received: Hello, you! -``` - -Once you verify the container works, push it to your Docker registry: - -``` -$ docker push /grpc_example -``` - -### Mapping gRPC services - -$productName$ `Mapping`s are based on URL prefixes; for gRPC, the URL prefix is the full-service name, including the package path (`package.service`). These are defined in the `.proto` definition file. In the example [proto definition file](https://github.com/grpc/grpc/blob/master/examples/protos/helloworld.proto) we see: - -``` -package helloworld; - -// The greeting service definition. -service Greeter { ... } -``` - -so the URL `prefix` is `helloworld.Greeter` and the mapping would be: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py -spec: - hostname: "*" - grpc: True - prefix: /helloworld.Greeter/ - rewrite: /helloworld.Greeter/ - service: grpc-example -``` - -Note the `grpc: true` line - this is what tells Envoy to use HTTP/2 so the request can communicate with your backend service. Also note that you'll need `prefix` and `rewrite` the same here, since the gRPC service needs the package and service to be in the request to do the right thing. - -### Deploying to Kubernetes - -`grpc_example.yaml` - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - acmeProvider: - authority: none - requestPolicy: - insecure: - action: Route ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py -spec: - hostname: "*" - grpc: True - prefix: /helloworld.Greeter/ - rewrite: /helloworld.Greeter/ - service: grpc-example - ---- -apiVersion: v1 -kind: Service -metadata: - labels: - service: grpc-example - name: grpc-example -spec: - type: ClusterIP - ports: - - name: grpc-greet - port: 80 - targetPort: grpc-api - selector: - service: grpc-example ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: grpc-example -spec: - replicas: 1 - selector: - matchLabels: - service: grpc-example - template: - metadata: - labels: - service: grpc-example - spec: - containers: - - name: grpc-example - image: /grpc_example - ports: - - name: grpc-api - containerPort: 50051 - restartPolicy: Always -``` - -The Host is declared here because we are using gRPC without TLS. Since $productName$ terminates TLS by default, in the Host we add a `requestPolicy` which allows insecure connections. After adding the $productName$ mapping to the service, the rest of the Kubernetes deployment YAML file is pretty straightforward. We need to identify the container image to use, expose the `containerPort` to listen on the same port the Docker container is listening on, and map the service port (80) to the container port (50051). - -> For more information on insecure routing, please refer to the [`Host` documentation](../../topics/running/host-crd#secure-and-insecure-requests). - - -Once you have the YAML file and the correct Docker registry, deploy it to your cluster with `kubectl`. - -``` -$ kubectl apply -f grpc_example.yaml -``` - -### Testing the Deployment - -Make sure to test your Kubernetes deployment before making more advanced changes (like adding TLS). To test any service with $productName$, we will need the hostname of the running $productName$ service which you can get with: - -``` -$ kubectl get service ambassador -o wide -``` -Which should return something similar to: - -``` -NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE -ambassador 10.11.12.13 35.36.37.38 80:31656/TCP 1m -``` -where `EXTERNAL-IP` is the `$AMBASSADORHOST` and 80 is the `$PORT`. - -You will need to open the `greeter_client.py` and change `localhost:50051` to `$AMBASSADORHOST:$PORT` - -```diff -- with grpc.insecure_channel('localhost:50051') as channel: -+ with grpc.insecure_channel(‘$AMBASSADORHOST:$PORT’) as channel: - stub = helloworld_pb2_grpc.GreeterStub(channel) - response = stub.SayHello(helloworld_pb2.HelloRequest(name='you')) - print("Greeter client received: " + response.message) -``` - -After making that change, simply run the client again and you will see the gRPC service in your cluster respond: - -``` -$ python greeter_client.py -Greeter client received: Hello, you! -``` - -### gRPC and TLS - -There is some extra configuration required to connect to a gRPC service through $productName$ over an encrypted channel. Currently, the gRPC call is being sent over cleartext to $productName$ which proxies it to the gRPC application. - -![](../images/grpc-tls.png) - -If you want to add TLS encryption to your gRPC calls, first you need to tell $productName$ to add [ALPN protocols](../../topics/running/tls) which are required by HTTP/2 to do TLS. - -For example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls -spec: - hosts: - - "*" - secret: ambassador-cert - alpn_protocols: h2 -``` - -Next, you need to change the client code slightly and tell it to open a secure RPC channel with $productName$. - -```diff -- with grpc.insecure_channel(‘$AMBASSADORHOST:$PORT’) as channel: -+ with grpc.secure_channel(‘$AMBASSADORHOST:$PORT’, grpc.ssl_channel_credentials()) as channel: - stub = helloworld_pb2_grpc.GreeterStub(channel) - response = stub.SayHello(helloworld_pb2.HelloRequest(name='you')) - print("Greeter client received: " + response.message) -``` - -`grpc.ssl_channel_credentials(root_certificates=None, private_key=None, certificate_chain=None)`returns the root certificate that will be used to validate the certificate and public key sent by $productName$. The default values of `None` tells the gRPC runtime to grab the root certificate from the default location packaged with gRPC and ignore the private key and certificate chain fields. Generally, passing no arguments to the method that requests credentials gives the same behavior. Refer to the languages [API Reference](https://grpc.io/docs/) if this is not the case. - -$productName$ is now terminating TLS from the gRPC client and proxying the call to the application over cleartext. - -![](../images/gRPC-TLS-Ambassador.png) - -If you want to configure authentication in another language, [gRPC provides examples](https://grpc.io/docs/guides/auth.html) with proper syntax for other languages. - -#### Working with Host headers that include the port - -Some gRPC clients automatically include the port in the Host header. This is a problem when using TLS because the certificate will match `myurl.com` but the Host header will be `myurl.com:443`, resulting in the error `rpc error: code = Unimplemented desc =`. If you run into this issue, there are two ways to solve it depending on your use case, both using the Module resource. - -The first is to set the `strip_matching_host_port` [property](../../topics/running/ambassador#strip-matching-host-port) to `true`. However, this only works if the port in the header matches the port that Envoy listens on (8443 by default). In the default installation of $productName$, the public port is 443, which then maps internally to 8443, so this only works for custom installations where the public service port matches the port in the Listener resource. - -The second solution is to use the following [Lua script](../../topics/running/ambassador#lua-scripts), which always strips the port: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador - namespace: ambassador -spec: - config: - lua_scripts: | - function envoy_on_request(request_handle) - local authority = request_handle:headers():get(":authority") - if(string.find(authority, ":") ~= nil) - then - local authority_index = string.find(authority, ":") - local stripped_authority = string.sub(authority, 1, authority_index - 1) - request_handle:headers():replace(":authority", stripped_authority) - end - end -``` - -#### Originating TLS with gRPC service - -![](../images/gRPC-TLS-Originate.png) - -$productName$ can originate TLS with your gRPC service so the entire RPC channel is encrypted. To configure this, first get some TLS certificates and configure the server to open a secure channel with them. Using self-signed certs this can be done with OpenSSL and adding a couple of lines to the server code. - -```diff -def serve(): - server = grpc.server(futures.ThreadPoolExecutor(max_workers=10)) -+ with open('certs/server.key', 'rb') as f: -+ private_key = f.read() -+ with open('certs/server.crt', 'rb') as f: -+ cert_chain = f.read() -+ server_creds = grpc.ssl_server_credentials( ( (private_key, cert_chain), ) ) - helloworld_pb2_grpc.add_GreeterServicer_to_server(Greeter(), server) -- server.add_insecure_port('[::]:50052') -+ server.add_secure_port('[::]:50052', server_creds) - server.start() -``` - -Rebuild your docker container **making sure the certificates are included** and follow the same steps of testing and deploying to Kubernetes. You will need to make a small change to the client code to test locally. - -```diff -- with grpc.insecure_channel(‘localhost:$PORT’) as channel: -+ with grpc.secure_channel(‘localhost:$PORT’, grpc.ssl_channel_credentials(open('certs/server.crt', 'rb').read())) as channel: - stub = helloworld_pb2_grpc.GreeterStub(channel) - response = stub.SayHello(helloworld_pb2.HelloRequest(name='you')) - print("Greeter client received: " + response.message) -``` - -Once deployed we will need to tell $productName$ to originate TLS to the application. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py-tls -spec: - hostname: "*" - grpc: True - tls: upstream - prefix: /hello.Greeter/ - rewrite: /hello.Greeter/ - service: https://grpc-py - ---- -apiVersion: v1 -kind: Service -metadata: - labels: - service: grpc-py - name: grpc-py -spec: - type: ClusterIP - ports: - - name: grpc-greet - port: 443 - targetPort: grpc-api - selector: - service: grpc-py -``` - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: upstream -spec: - alpn_protocols: h2 - secret: ambassador-cert -``` - -We need to tell $productName$ to route to the `service:` over https and have the service listen on `443`. We also need to tell $productName$ to use ALPN protocols when originating TLS with the application, the same way we did with TLS termination. This is done by setting `alpn_protocols: ["h2"]` in a `TLSContext` telling the service to use that tls-context in the mapping by setting `tls: upstream`. - -Refer to the [TLS document](../../topics/running/tls/origination#advanced-configuration-using-a-tlscontext) for more information on TLS origination. - -### gRPC headers - -gRPC services use [HTTP/2 headers](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md). This means that some header-based routing rules will need to be rewritten to support HTTP/2 headers. For example, `host: subdomain.host.com` needs to be rewritten using the `headers: ` attribute with the `:authority` header: - -``` -headers: - :authority: subdomain.host.com -``` - -## Note - -### Ingress controllers - -Some [Kubernetes ingress controllers](https://kubernetes.io/docs/concepts/services-networking/ingress/) do not support HTTP/2 fully. As a result, if you are running $productName$ with an ingress controller in front, you may find that gRPC requests fail even with correct $productName$ configuration. - -A simple way around this is to use $productName$ with a `LoadBalancer` service, rather than an Ingress controller. You can also consider using [$productName$ as your Ingress Controller](../../topics/running/ingress-controller). - -### Mappings with hosts - -As with any `Mapping`, your gRPC service's `Mapping` may include a `host`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py -spec: - hostname: "*" - grpc: true - prefix: /helloworld.Greeter/ - rewrite: /helloworld.Greeter/ - service: grpc-example - host: api.example.com -``` - -Some gRPC client libraries produce requests where the `host` or `:authority` header includes the port number. For example, a request to the above service might include `host: api.example.com:443` instead of just `host: api.example.com`. To avoid having $productName$ return a 404 (not found) response to these requests due to the mismatched host, you may want to set `strip_matching_host_port` in the [Ambassador module](../../topics/running/ambassador#strip-matching-host-port). - -Alternately, you may find it cleaner to make sure your gRPC client does not include the port in the `host` header. Here is an example using gRPC/Go. - -```go -hostname := "api.example.com" -port := "443" -config := &tls.Config{ServerName: hostname} -creds := credentials.NewTLS(config) -opts := []grpc.DialOption{ - grpc.WithTransportCredentials(creds), -// ... -} -conn, err := grpc.Dial(hostname+":"+port, opts...) -// ... -``` - -## gRPC-Web - -$productName$ also supports the [gRPC-Web](../../topics/running/ambassador#grpc) protocol for browser-based gRPC applications. diff --git a/content/en/docs/3.4/howtos/http3-aks.md b/content/en/docs/3.4/howtos/http3-aks.md deleted file mode 100644 index 2f9be012..00000000 --- a/content/en/docs/3.4/howtos/http3-aks.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "$productName$ - HTTP/3 support for Azure Kubernetes Service (AKS)" -description: "How to configure HTTP/3 support for Azure Kubernetes Service (AKS). This guide shows how to setup the LoadBalancer service for AKS to support both TCP and UDP communications." ---- - -# Azure Kubernetes Service Engine HTTP/3 configuration - -This guide shows how to setup HTTP/3 support for Azure Kubernetes Service (AKS). The instructions provided in this page are a continuation of the [HTTP/3 in $productName$](../../topics/running/http3) documentation. - -## Configuring an external load balancer for AKS - -To configure an external load balancer for AKS, you need to: - -1. Reserve a public static IP address. -2. Create two `LoadBalancer` services, one for TCP and one for UDP. -3. Assign the public static IP address to the `loadBalancerIP` field. - -An example of the two load balancer services described above looks as follows: - -```yaml -# selectors and labels removed for clarity -apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$ - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - --- - apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$-udp - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http3 - port: 443 # Default support for HTTP/3 requires you to use 443 for the external client-facing port. - targetPort: 8443 - protocol: UDP - -``` - -In the above example, AKS generates two `LoadBalancer` services, one for UDP and the other for TCP. - - -You should verify that the Managed Identity or Serivce Principal has permissions to assign the IP address to the newly created LoadBalancer services. Refer to the Azure Docs - Managed Identity for more information. - diff --git a/content/en/docs/3.4/howtos/http3-eks.md b/content/en/docs/3.4/howtos/http3-eks.md deleted file mode 100644 index d09a1af5..00000000 --- a/content/en/docs/3.4/howtos/http3-eks.md +++ /dev/null @@ -1,252 +0,0 @@ ---- -title: "HTTP/3 with Amazon Elastic Kubernetes Service (EKS) | $productName$" -description: "How to configure HTTP/3 support for Amazon Elastic Kubernetes Service (EKS). This guide shows how to setup the LoadBalancer service for EKS to support both TCP and UDP communications." ---- - -# Amazon Elastic Kubernetes Service HTTP/3 configuration - -This guide shows how to setup HTTP/3 support for Amazon Elastic Kubernetes Service (EKS) The instructions provided in this page are a continuation of the [HTTP/3 in $productName$](../../topics/running/http3) documentation. - -## Create a network load balancer (NLB) - - The virtual private cloud (VPC) for your load balancer needs one public subnet in each availability zone where you have targets. - - ```shell - SUBNET_IDS=( ) - - aws elbv2 create-load-balancer \ - --name ${CLUSTER_NAME}-nlb \ - --type network \ - --subnets ${SUBNET_IDS} - ``` - -## Create a NodePort service - -Now create a `NodePort` service for $productName$ installation with two entries. Use `port: 443` to include support for both TCP and UDP traffic. - ```yaml - # Selectors and labels removed for clarity. - apiVersion: v1 - kind: Service - metadata: - name: $productDeploymentName$-http3 - namespace: $productNamespace$ - spec: - type: NodePort - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - nodePort: 30080 - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - nodePort: 30443 - - name: http3 - port: 443 - targetPort: 8443 - protocol: UDP - nodePort: 30443 - ``` - -## Create target groups - -Run the following command with the variables for your VPC ID and cluster name: - - ```shell - VPC_ID= - CLUSTER_NAME= - - aws elbv2 create-target-group --name ${CLUSTER_NAME}-tcp-tg \ - --protocol TCP --port 30080 --vpc-id ${VPC_ID} \ - --health-check-protocol TCP \ - --health-check-port 30080 \ - --target-type instance - - aws elbv2 create-target-group --name ${CLUSTER_NAME}-tcp-udp-tg \ - --protocol TCP_UDP --port 30443 --vpc-id ${VPC_ID} \ - --health-check-protocol TCP \ - --health-check-port 30443 \ - --target-type instance - ``` - -## Register your instances - -Next, register your cluster's instance with the the instance IDs and Amazon Resource Names (ARN). - -To get your cluster's instance IDs, enter the following command: - ```shell - aws ec2 describe-instances \ - --filters Name=tag:eks:cluster-name,Values=${CLUSTER_NAME} \ - --output text - --query 'Reservations[*].Instances[*].InstanceId' \ - ``` - -To get your ARNs, enter the following command: - ```shell - TCP_TG_NAME=${CLUSTER_NAME}-tcp-tg-name - TCP_UDP_TG_NAME=${CLUSTER_NAME}-tcp-udp-tg-name - - aws elbv2 describe-target-groups \ - --query 'TargetGroups[?TargetGroupName==`'${TCP_TG_NAME}'`].TargetGroupArn' \ - --output text - aws elbv2 describe-target-groups \ - --query 'TargetGroups[?TargetGroupName==`'${TCP_UDP_TG_NAME}'`]. TargetGroupArn' \ - --output text - ``` - -Register the instances with the target groups and load balancer using the instance IDs and ARNs you retrieved. - ```shell - INSTANCE_IDS=( ) - REGION= - TG_NAME= - TCP_TG_ARN=arn:aws:elasticloadbalancing:${REGION}:079.....:targetgroup/${TG_NAME}/... - TCP_UDP_TG_ARN=arn:aws:elasticloadbalancing:${REGION}:079.....:targetgroup/${TG_NAME}/... - - aws elbv2 register-targets --target-group-arn ${TCP_TG_ARN} --targets ${INSTANCE_IDS} - aws elbv2 register-targets --target-group-arn ${TCP_UDP_TG_ARN} --targets ${INSTANCE_IDS} - ``` - -## Create listeners in AWS. - -Register your cluster's instance with the instance IDs and ARNs. - -To get the load balancer's ARN, enter the following command: - ```shell - aws elbv2 describe-load-balancers --name ${CLUSTER_NAME}-nlb \ - --query 'LoadBalancers[0].LoadBalancerArn' \ - --output text - ``` - -Create a TCP listener on port 80 that that forwards to the TargetGroup {TCP_TG_ARN}. - ```shell - aws elbv2 create-listener --load-balancer-arn ${LB_ARN} \ - --protocol TCP --port 80 \ - --default-actions Type=forward,TargetGroupArn=${TCP_TG_ARN} - ``` - - Create a TCP_UDP listener on port 443 that forwards to the TargetGroup {TCP_UDP_TG_ARN}. - ```shell - aws elbv2 create-listener --load-balancer-arn ${LB_ARN} \ - --protocol TCP_UDP --port 443 \ - --default-actions Type=forward,TargetGroupArn=${TCP_UDP_TG_ARN} - ``` - -## Update the security groups - -Now you need to update your security groups to receive traffic. This security group covers all node groups attached to the EKS cluster: - ```shell - aws eks describe-cluster --name ${CLUSTER_NAME} | grep clusterSecurityGroupId - ``` - -Now authorize the cluster security group to allow internet traffic: - ```shell - for x in ${CLUSTER_SG}; do \ - aws ec2 authorize-security-group-ingress --group-id $$x --protocol tcp --port 30080 --cidr 0.0.0.0/0; \ - aws ec2 authorize-security-group-ingress --group-id $$x --protocol tcp --port 30443 --cidr 0.0.0.0/0; \ - aws ec2 authorize-security-group-ingress --group-id $$x --protocol udp --port 30443 --cidr 0.0.0.0/0; \ - done - ``` - -## Get the DNS name for the load balancers - -Enter the following command to get the DNS name for your load balancers and create a CNAME record at your domain provider: - ```shell - aws elbv2 describe-load-balancers --name ${CLUSTER_NAME}-nlb \ - --query 'LoadBalancers[0].DNSName' \ - --output text - ``` - -## Create Listener resources - -Now you need to create the `Listener` resources for $productName$. The first `Listener` in the example below handles traffic for HTTP/1.1 and HTTP/2, while the second `Listener` handles all HTTP/3 traffic. - - ```yaml - kubectl apply -f - < - acmeProvider: - authority: none - tlsSecret: - name: tls-cert # The QUIC network protocol requires TLS with a valid certificate - tls: - min_tls_version: v1.3 - max_tls_version: v1.3 - alpn_protocols: h2,http/1.1 - EOF - ``` - -## Apply the quote service and a Mapping to test the HTTP/3 configuration. - -Finally, apply the quote service to a $productName$ `Mapping`. - - ```shell - kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$version$/quickstart/qotm.yaml - kubectl apply -f - </backend/ - ``` -Your domain now shows that it is being served with HTTP/3. diff --git a/content/en/docs/3.4/howtos/http3-gke.md b/content/en/docs/3.4/howtos/http3-gke.md deleted file mode 100644 index 677e89e3..00000000 --- a/content/en/docs/3.4/howtos/http3-gke.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: "$productName$ - HTTP/3 support for Google Kubernetes Engine (GKE)" -description: "How to configure HTTP/3 support for Google Kubernetes Engine (GKE). This guide shows how to setup the LoadBalancer service for GKE to support both TCP and UDP communications." ---- - -# Google Kubernetes Service Engine HTTP/3 configuration - -This guide shows how to setup HTTP/3 support for Google Kubernetes Engine (GKE). The instructions provided in this page are a continuation of the [HTTP/3 in $productName$](../../topics/running/http3) documentation. - -## Configuring an external load balancer for GKE - -Currently, GKE only supports adding feature flags to `alpha` clusters, and doesn't support the creation of mixed protocol services of type `LoadBalancer`. To configure an external load balancer for GKE, you need to: - -1. Reserve a public static IP address. -2. Create two `LoadBalancer` services, one for TCP and one for UDP. -3. Assign the public static IP address to the `loadBalancerIP` field. - -An example of the two load balancer services described above looks as follows: - -```yaml -# selectors and labels removed for clarity -apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$ - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - --- - apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$-udp - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http3 - port: 443 # Default support for HTTP/3 requires you to use 443 for the external client-facing port. - targetPort: 8443 - protocol: UDP - -``` - -In the above example, GKE generates two `LoadBalancer` services, one for UDP and the other for TCP. diff --git a/content/en/docs/3.4/howtos/index.md b/content/en/docs/3.4/howtos/index.md deleted file mode 100644 index f16cdd46..00000000 --- a/content/en/docs/3.4/howtos/index.md +++ /dev/null @@ -1,25 +0,0 @@ -# "How-to" guides - -These guides are designed to help users quickly accomplish common tasks. The guides assume a certain level of understanding of $productName$. Many of these guides are contributed by third parties; we welcome contributions via Pull Request at https://github.com/emissary-ingress/emissary. - -* Integrating with Service Mesh. $productName$ natively integrates with many service meshes. - * [HashiCorp Consul](consul) - * [Istio](istio) - * [Linkerd](linkerd2) -* Distributed tracing. $productName$ natively supports a number of distributed tracing systems to enable developers to visualize request flow in microservice and service-oriented architectures. - * [Datadog](tracing-datadog) - * [Zipkin](tracing-zipkin) -* Monitoring. $productName$ integrates with a number of different monitoring/metrics providers. - * [Prometheus](prometheus) -* [Developing Custom Filters](filter-dev-guide) -* Frameworks and Protocols. $productName$ supports a wide range of protocols and cloud-native frameworks. - * [gRPC](grpc) - * [Knative Serverless Framework](knative) - * [WebSockets](websockets) -* Security. $productName$ supports a number of strategies for securing Kubernetes services. - * [Protecting the Diagnostics Interface](protecting-diag-access) - * [HTTPS and TLS termination](tls-termination) - * [Certificate Manager](cert-manager) can be used to automatically obtain and renew TLS certificates; $AESproductName$ natively integrates this functionality. - * [Client Certificate Validation](client-cert-validation) - * [Basic Authentication](basic-auth) is a tutorial on how to use the external authentication API to code your own authentication service. - * [Basic Rate Limiting](rate-limiting-tutorial) diff --git a/content/en/docs/3.4/howtos/istio.md b/content/en/docs/3.4/howtos/istio.md deleted file mode 100644 index e26571b7..00000000 --- a/content/en/docs/3.4/howtos/istio.md +++ /dev/null @@ -1,445 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Istio integration - -$productName$ and Istio: Edge Proxy and Service Mesh together in one. $productName$ is deployed at the edge of your network and routes incoming traffic to your internal services (aka "north-south" traffic). [Istio](https://istio.io/) is a service mesh for microservices, and is designed to add application-level Layer (L7) observability, routing, and resilience to service-to-service traffic (aka "east-west" traffic). Both Istio and $productName$ are built using [Envoy](https://www.envoyproxy.io). - -$productName$ and Istio can be deployed together on Kubernetes. In this configuration, $productName$ manages -traditional edge functions such as authentication, TLS termination, and edge routing. Istio mediates communication -from $productName$ to services, and communication between services. - -This allows the operator to have the best of both worlds: a high performance, modern edge service ($productName$) combined with a state-of-the-art service mesh (Istio). While Istio has introduced a [Gateway](https://istio.io/latest/docs/tasks/traffic-management/ingress/ingress-control/) abstraction, $productName$ still has a much broader feature set for edge routing than Istio. For more on this topic, see our blog post on [API Gateway vs Service Mesh](https://blog.getambassador.io/api-gateway-vs-service-mesh-104c01fa4784). - -This guide explains how to take advantage of both $productName$ and Istio to have complete control and observability over how requests are made in your cluster: - -- [Install Istio](#install-istio) and configure auto-injection -- [Install $productName$ with Istio integration](#install-edge) -- [Configure an mTLS `TLSContext`](#configure-an-mtls-tlscontext) -- [Route to services using mTLS](#route-to-services-using-mtls) - -If desired, you may also - -- [Enable strict mTLS](#enable-strict-mtls) -- [Configure Prometheus metrics collection](#configure-prometheus-metrics-collection) -- [Configure Istio distributed tracing](#configure-istio-distributed-tracing) - -To follow this guide, you need: - -- A Kubernetes cluster version 1.15 and above -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- Istio version 1.10 or higher - -## Install Istio - -Start by [installing Istio](https://istio.io/docs/setup/getting-started/). Any supported installation method for -Istio will work for use with $productName$. - -### Configure Istio Auto-Injection - -Istio functions by supplying a sidecar container running Envoy with every service in the mesh (including -$productName$). The sidecar is what enforces Istio policies for traffic to and from the service, notably -including mTLS encryption and certificate handling. As such, it is very important that the sidecar be -correctly supplied for every service in the mesh! - -While it is possible to manage sidecars by hand, it is far easier to allow Istio to automatically inject -the sidecar as necessary. To do this, set the `istio-injection` label on each Kubernetes Namespace for -which you want auto-injection: - -```yaml -kubectl label namespace $namespace istio-injection=enabled --overwrite -``` - - - The following example uses the `istio-injection` label to arrange for auto-injection in the - `$productNamespace$` Namespace below. You can manage sidecar injection by hand if you wish; what - is critical is that every service that participates in the Istio mesh have the Istio - sidecar. - - -## Install $productName$ with Istio Integration - -Properly integrating $productName$ with Istio provides support for: - -* [Mutual TLS (mTLS)](../../topics/running/tls/mtls/), with certificates managed by Istio, to allow end-to-end encryption -for east-west traffic; -* Automatic generation of Prometheus metrics for services; and -* Istio distributed tracing for end-to-end observability. - -The simplest way to enable everything is to install $productName$ using [Helm](https://helm.sh), though -you can use manual installation with YAML if you wish. - -### Installation with Helm (Recommended) - -To install with Helm, write the following YAML to a file called `istio-integration.yaml`: - -```yaml -# Listeners are required in $productName$ 2.0. -# This will create the two default Listeners for HTTP on port 8080 and HTTPS on port 8443. -createDefaultListeners: true - -# These are annotations that will be added to the $productName$ pods. -podAnnotations: - # These first two annotations tell Istio not to try to do port management for the - # $productName$ pod itself. Though these annotations are placed on the $productName$ - # pods, they are interpreted by Istio. - traffic.sidecar.istio.io/includeInboundPorts: "" # do not intercept any inbound ports - traffic.sidecar.istio.io/includeOutboundIPRanges: "" # do not intercept any outbound traffic - - # We use proxy.istio.io/config to tell the Istio proxy to write newly-generated mTLS certificates - # into /etc/istio-certs, which will be mounted below. Though this annotation is placed on the - # $productName$ pods, it is interpreted by Istio. - proxy.istio.io/config: | - proxyMetadata: - OUTPUT_CERTS: /etc/istio-certs - - # We use sidecar.istio.io/userVolumeMount to tell the Istio sidecars to mount the istio-certs - # volume at /etc/istio-certs, allowing the sidecars to see the generated certificates. Though - # this annotation is placed on the $productName$ pods, it is interpreted by Istio. - sidecar.istio.io/userVolumeMount: '[{"name": "istio-certs", "mountPath": "/etc/istio-certs"}]' - -# We define a single storage volume called "istio-certs". It starts out empty, and Istio -# uses it to communicate mTLS certs between the Istio proxy and the Istio sidecars (see the -# annotations above). -volumes: - - emptyDir: - medium: Memory - name: istio-certs - -# We also tell $productName$ to mount the "istio-certs" volume at /etc/istio-certs in the -# $productName$ pod. This gives $productName$ access to the mTLS certificates, too. -volumeMounts: - - name: istio-certs - mountPath: /etc/istio-certs/ - readOnly: true - -# Finally, we need to set some environment variables for $productName$. -env: - # AMBASSADOR_ISTIO_SECRET_DIR tells $productName$ to look for Istio mTLS certs, and to - # make them available as a secret named "istio-certs". - AMBASSADOR_ISTIO_SECRET_DIR: "/etc/istio-certs" - - # AMBASSADOR_ENVOY_BASE_ID is set to prevent collisions with the Istio sidecar's Envoy, - # which runs with base-id 0. - AMBASSADOR_ENVOY_BASE_ID: "1" -``` - -To install $productName$ with Helm, use these values to configure Istio integration: - -1. Create the `$productNamespace$` Namespace: - - ```yaml - kubectl create namespace $productNamespace$ - ``` - -2. Enable Istio auto-injection for it: - - ```yaml - kubectl label namespace $productNamespace$ istio-injection=enabled --overwrite - ``` - -3. Make sure the Helm repo is configured: - - ```bash - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - -4. Use Helm to install $productName$ in $productNamespace$: - - ```bash - helm install $productHelmName$ --namespace $productNamespace$ -f istio-integration.yaml datawire/$productHelmName$ && \ - kubectl -n $productNamespace$ wait --for condition=available --timeout=90s deploy -lapp.kubernetes.io/instance=$productDeploymentName$ - ``` - -### Installation Using YAML - -To install using YAML files, you need to manually incorporate the contents of the `istio-integration.yaml` -file shown above into your deployment YAML: - -* `pod-annotations` should be configured as Kubernetes `annotations` on the $productName$ Pods; -* `volumes`, `volumeMounts`, and `env` contents should be included in the $productDeploymentName$ Deployment; and -* you must also label the $productNamespace$ Namespace for auto-injection as described above. - -### Configuring an Existing Installation - -If you have already installed $productName$ and want to enable Istio: - -1. Install Istio. -2. Label the $productNamespace$ namespace for Istio auto-injection, as above. -2. Edit the $productName$ Deployments to contain the `annotations`, `volumes`, `volumeMounts`, and `env` elements - shown above. - * If you installed with Helm, you can use `helm upgrade` with `-f istio-integration.yaml` to modify the - installation for you. -3. Restart the $productName$ pods. - -## Configure an mTLS `TLSContext` - -After configuring $productName$ for Istio integration, the Istio mTLS certificates are available within -$productName$: - -- Both the `istio-proxy` sidecar and $productName$ mount the `istio-certs` volume at `/etc/istio-certs`. -- The `istio-proxy` sidecar saves the mTLS certificates into `/etc/istio-certs` (per the `OUTPUT_CERTS` - environment variable). -- $productName$ reads the mTLS certificates from `/etc/istio-certs` (per the `AMBASSADOR_ISTIO_SECRET_DIR` - environment variable) and creates a Secret named `istio-certs`. - - - At present, the Secret name istio-certs cannot be changed. - - -To make use of the `istio-certs` Secret, create a `TLSContext` referencing it: - - ```shell - $ kubectl apply -f - < - You must either explicitly specify port 80 in your 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 - <This guide applies to $OSSproductName$. It will not work correctly -on $AESproductName$. - -$productName$ can validate incoming requests before routing them to a backing service. In this tutorial, we'll configure $productName$ to use a simple third party rate limit service. (If you don't want to implement your own rate limiting service, $AESproductName$ integrates a [powerful, flexible rate limiting service](/docs/edge-stack/latest/topics/using/rate-limits/rate-limits/).) - -## Before you get started - -This tutorial assumes you have already followed the $productName$ [Installation](../../topics/install/) and [Quickstart Tutorial](../../tutorials/quickstart-demo) guides. If you haven't done that already, you should do so now. - -Once completed, you'll have a Kubernetes cluster running $productName$ and the Quote service. Let's walk through adding rate limiting to this setup. - -## 1. Deploy the rate limit service - -$productName$ delegates the actual rate limit logic to a third party service. We've written a [simple rate limit service](https://github.com/emissary-ingress/ratelimit-example) that: - -- listens for requests on port 5000; -- handles gRPC `shouldRateLimit` requests; -- allows requests with the `x-emissary-test-allow: "true"` header; and -- marks all other requests as `OVER_LIMIT`; - -Here's the YAML we'll start with: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: RateLimitService -metadata: - name: ratelimit - namespace: default -spec: - service: "ratelimit-example.default:5000" - protocol_version: v3 - domain: emissary - failure_mode_deny: true ---- -apiVersion: v1 -kind: Service -metadata: - name: ratelimit-example -spec: - selector: - app: ratelimit-example - ports: - - name: http - port: 5000 - targetPort: http ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: ratelimit-example -spec: - replicas: 1 - selector: - matchLabels: - app: ratelimit-example - template: - metadata: - labels: - app: ratelimit-example - spec: - containers: - - name: ratelimit-example - image: docker.io/emissaryingress/ratelimit-example:v3 - imagePullPolicy: Always - ports: - - name: http - containerPort: 5000 - resources: - limits: - memory: "64Mi" - cpu: "100m" -``` - -Once this configuration is applied Kubernetes will startup the example ratelimit service and $productName$ will be configured to use the rate limit service. The `RateLimitService` configuration tells $productName$ to: - -- Send `ShouldRateLimit` check request to `ratelimit-example.default:5000` -- Configure Envoy to talk with the example ratelimit service using transport protocol `v3` (*only supported version*) -- Set the labels `domain` to `emissary` (*labels discussed below*) - -If $productName$ cannot contact the rate limit service, it can either fail open or closed. The default is to fail open but in the example `RateLimitService` above we toggled it via the `failure_mode_deny: true` setting. - -## 2. Configure $productName$ Mappings - -$productName$ only validates requests on `Mapping`s which set labels to use for rate limiting, so you'll need to apply `labels` to your `Mapping`s to enable rate limiting. For more information -on the labelling process, see the [Rate Limits configuration documentation](../../topics/using/rate-limits/). - - - These labels require Mapping resources with apiVersion getambassador.io/v2 or newer — if you're updating an old installation, check the - apiVersion! - - -Labels are added to a `Mapping` using the `labels` field and `domain` configured in the `RateLimitService`. For example: - -```yaml -labels: - emissary: - - request_label_group: - - x-emissary-test-allow: - request_headers: - key: "x-emissary-test-allow" - header_name: "x-emissary-test-allow" -``` - -If we were to apply it the `Mapping` definition for the `quote-backend` service outlined in the quick-start then it would look like this: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: "*" - prefix: /backend/ - service: quote - labels: - emissary: - - request_label_group: - - x-emissary-test-allow: - request_headers: - key: "x-emissary-test-allow" - header_name: "x-emissary-test-allow" -``` - -Note that the `key` could be anything you like, but our example rate limiting service expects it to match the name of the header. Also note that since our `RateLimitService` expects to use labels in the -`emissary` domain, our `Mapping` must match. - -## 2. Test rate limiting - -If we `curl` to a rate-limited URL: - -```shell -curl -i -H "x-emissary-test-allow: probably" http://$LB_ENDPOINT/backend/ -``` - -We get a `429` status code, since we are being rate limited. - -```shell -HTTP/1.1 429 Too Many Requests -content-type: text/html; charset=utf-8 -content-length: 0 -``` - -If we set the correct header value to the service request, we will get a quote successfully: - -```shell -$ curl -i -H "x-emissary-test-allow: true" http://$LB_ENDPOINT/backend/ - -TCP_NODELAY set -* Connected to 35.196.173.175 (35.196.173.175) port 80 (#0) -> GET /backed HTTP/1.1 -> Host: 35.196.173.175 -> User-Agent: curl/7.54.0 -> Accept: */* -> -< HTTP/1.1 200 OK -< content-type: application/json -< date: Thu, 23 May 2019 15:25:06 GMT -< content-length: 172 -< x-envoy-upstream-service-time: 0 -< server: envoy -< -{ - "server": "humble-blueberry-o2v493st", - "quote": "Nihilism gambles with lives, happiness, and even destiny itself!", - "time": "2019-05-23T15:25:06.544417902Z" -* Connection #0 to host 54.165.128.189 left intact -} -``` - -## More - -For more details about configuring the external rate limit service, read the [rate limit documentation](../../topics/using/rate-limits/). diff --git a/content/en/docs/3.4/howtos/route.md b/content/en/docs/3.4/howtos/route.md deleted file mode 100644 index f52ab880..00000000 --- a/content/en/docs/3.4/howtos/route.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -description: "$productName$ uses the Mapping resource to map a resource, like a URL prefix, to a Kubernetes service or web service." ---- - -import Alert from '@material-ui/lab/Alert'; - -# Get traffic from the edge - -
-

Contents

- -* [Examples](#examples) -* [Applying a Mapping Resource](#applying-a-mapping-resource) -* [Resources](#resources) -* [Services](#services) -* [Extending Mappings](#extending-mappings) -* [Best Practices](#best-practices) -* [What's next?](#img-classos-logo-srcimageslogopng-whats-next) - -
- -The core $productName$ resource used to manage cluster ingress is the `Mapping` resource. - -**A `Mapping` resource routes a URL path (or prefix) to a service (either a Kubernetes service or other web service).** - - - Remember that Listener and Host resources are  - required for a functioning $productName$ installation that can route traffic!
- Learn more about Listener.
- Learn more about Host. - - -## Examples - -This `Mapping` would route requests to `https:///webapp/` to the `webapp-svc` Service. **This is not a -complete example on its own; see below.** - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: webapp-mapping -spec: - prefix: /webapp/ - service: webapp-svc -``` - -| Name | Type | Description | -| :--- | :--- | :--- | -| `metadata.name` | String | Identifies the Mapping. | -| `spec.prefix` | String | The URL prefix identifying your resource. [See below](#resources) on how $productName$ handles resources. | -| `spec.service` | String | The service handling the resource. If a Kubernetes service, it must include the namespace (in the format `service.namespace`) if the service is in a different namespace than $productName$. [See below](#services) on service name formatting.| - -Here's another example using a web service that maps requests to `/httpbin/` to `http://httpbin.org` (again, **this is not a -complete example on its own; see below**): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin-mapping -spec: - prefix: /httpbin/ - service: http://httpbin.org - hostname: '*' -``` - -### Complete example configuration - -For demonstration purposes, here's a possible way of combining a `Listener`, a `Host`, and both `Mapping`s above that is complete and functional: - -- it will accept HTTP or HTTPS on port 8443; -- $productName$ is terminating TLS; -- HTTPS to `foo.example.com` will be routed as above; -- HTTP to `foo.example.com` will be redirected to HTTPS; -- HTTP or HTTPS to other hostnames will be rejected; and -- the associations between the `Listener`, the `Host`, and the `Mappings` use Kubernetes `label`s. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: foo-example-secret -data: - tls.crt: -certificate PEM- - tls.key: -secret key PEM- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-8443 -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: - selector: - matchLabels: - exampleName: basic-https ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host - labels: - exampleName: basic-https -spec: - hostname: "foo.example.com" - tlsSecret: - name: foo-example-secret - selector: - matchLabels: - exampleName: basic-https ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: webapp-mapping - labels: - exampleName: basic-https -spec: - prefix: /webapp/ - service: webapp-svc - hostname: 'foo.example.com' ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin-mapping - labels: - exampleName: basic-https -spec: - prefix: /httpbin/ - service: http://httpbin.org - hostname: 'foo.example.com' - -``` - -Note the addition of `label`s and `selector`s to explicitly specify which resources should associate in this example. - - - Learn more about Listener.
- Learn more about Host. - - -## Applying a Mapping resource - -A Mapping resource can be managed using the same workflow as any other Kubernetes resources (like a Service or Deployment). For example, if the above Mapping is saved into a file called `httpbin-mapping.yaml`, the following command will apply the configuration directly to $productName$: - -``` -kubectl apply -f httpbin-mapping.yaml -``` - -For production use, best practice is to store the file in a version control system and apply the changes with a continuous deployment pipeline. The Ambassador Operating Model provides more detail. - -## Resources - -To $productName$, a resource is a group of one or more URLs that all share a common prefix in the URL path. For example, these URLs all share the `/resource1/` path prefix, so `/resource1/` can be considered a single resource: - -* `https://ambassador.example.com/resource1/foo` -* `https://ambassador.example.com/resource1/bar` -* `https://ambassador.example.com/resource1/baz/zing` - -On the other hand, these URLs share only the prefix `/` -- you _could_ tell $productName$ to treat them as a single resource, but it's probably not terribly useful. - -* `https://ambassador.example.com/resource1/foo` -* `https://ambassador.example.com/resource2/bar` -* `https://ambassador.example.com/resource3/baz/zing` - -Note that the length of the prefix doesn't matter; a prefix like `/v1/this/is/my/very/long/resource/name/` is valid. - -Also note that $productName$ does not actually require the prefix to start and end with `/` -- however, in practice, it's a good idea. Specifying a prefix of `/man` would match all of the following, which probably is not what was intended: - -* `https://ambassador.example.com/man/foo` -* `https://ambassador.example.com/mankind` -* `https://ambassador.example.com/man-it-is/really-hot-today` - -## Services - -$productName$ routes traffic to a service. A service is defined as `[scheme://]service[.namespace][:port]`. Everything except for the service is optional. - -- `scheme` can be either `http` or `https`; if not present, the default is `http`. -- `service` is the name of a service (typically the service name in Kubernetes or Consul); it is not allowed to contain the `.` character. -- `namespace` is the namespace in which the service is running. Starting with $productName$ 1.0.0, if not supplied, it defaults to the namespace in which the Mapping resource is defined. The default behavior can be configured using the [Module resource](../../topics/running/ambassador). When using a Consul resolver, `namespace` is not allowed. -- `port` is the port to which a request should be sent. If not specified, it defaults to `80` when the scheme is `http` or `443` when the scheme is `https`. Note that the [resolver](../../topics/running/resolvers) may return a port in which case the `port` setting is ignored. - -While using service.namespace.svc.cluster.local may work for Kubernetes resolvers, the preferred syntax is service.namespace. - - -## Extending Mappings - -Mapping resources support a rich set of annotations to customize the specific routing behavior. Here's an example service for implementing the [CQRS pattern](https://docs.microsoft.com/en-us/azure/architecture/patterns/cqrs) (using HTTP): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-get -spec: - prefix: /cqrs/ - method: GET - service: getcqrs - hostname: '*' ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-put -spec: - prefix: /cqrs/ - method: PUT - service: putcqrs - hostname: '*' -``` - -## Best Practices - -$productName$'s configuration is assembled from multiple YAML blocks which are managed by independent application teams. This implies that certain best practices should be followed. - -#### $productName$'s configuration should be under version control. - -While you can always read back the $productName$'s configuration from Kubernetes or its diagnostic service, the $productName$ will not do versioning for you. - -#### $productName$ tries to not start with a broken configuration, but it's not perfect. - -Gross errors will result in the $productName$ refusing to start, in which case `kubectl logs` will be helpful. However, it's always possible to map a resource to the wrong service, or use the wrong `rewrite` rules. $productName$ can't detect that on its own, although its [diagnostic service](../../topics/running/diagnostics/) can help you figure it out. - -#### Be careful of mapping collisions. - -If two different developers try to map `/myservice/` to something, this can lead to unexpected behavior. $productName$'s [canary deployment](../../topics/using/canary/) logic means that it's more likely that traffic will be split between them than that it will throw an error -- again, the diagnostic service can help you here. - -#### Unless specified, mapping attributes cannot be applied to any other resource type. - -## 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/content/en/docs/3.4/howtos/tls-termination.md b/content/en/docs/3.4/howtos/tls-termination.md deleted file mode 100644 index 2bbdf4c4..00000000 --- a/content/en/docs/3.4/howtos/tls-termination.md +++ /dev/null @@ -1,192 +0,0 @@ -# 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/content/en/docs/3.4/howtos/tracing-datadog.md b/content/en/docs/3.4/howtos/tracing-datadog.md deleted file mode 100644 index d627e29f..00000000 --- a/content/en/docs/3.4/howtos/tracing-datadog.md +++ /dev/null @@ -1,63 +0,0 @@ -# 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/content/en/docs/3.4/howtos/tracing-lightstep.md b/content/en/docs/3.4/howtos/tracing-lightstep.md deleted file mode 100644 index 30353e71..00000000 --- a/content/en/docs/3.4/howtos/tracing-lightstep.md +++ /dev/null @@ -1,230 +0,0 @@ -# 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. - - - Please note that the 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. - - -## Before you get started - -This tutorial assumes you have already followed the $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. Setup Lightstep - -If you don't already have a Lightstep account be sure to create one [here](https://lightstep.com/). Then create a Project and be sure to create and save the Access Token information. You can find your Access Token information under the Project settings. - -## 2. Deploy the OpenTelemetry Collector - -The next step is to deploy the OpenTelemetry Collector. The purpose of the OpenTelemetry Collector is to receive the requested trace data and then export it to Lightstep. - -For the purposes of this tutorial, we are going to create and use the `monitoring` namespace. This can be done with the following command. - -```bash - kubectl create namespace monitoring -``` - -Next we are going to setup our configuration for the OpenTelemetry Collector. First, we use a Kubernetes secret to store our Lightstep Access Token that we saved in step one. It is important for us to encode the secret in Base64. How you want to do this securely is up to you, for the purposes of this tutorial we will use the online tool [Base64Encode.org](https://www.base64encode.org/). Once the secret is encoded, please apply the following YAML and be sure to update the value of the `lightstep_access_token` with your encoded token. - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: otel - namespace: monitoring -type: Opaque -data: - lightstep_access_token: YOUR_BASE64_ENCODED_TOKEN_HERE -``` - -Next, please add the following YAML to a file named `opentelemetry.yaml`. This configuration will create 3 resources. A ConfigMap that will store our configuration options, an OpenTelemetry Deployment that uses the [OpenTelemetry Collector Contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib) container image, and an associated Service for our Distributed Tracing. - -```yaml ---- ---- -apiVersion: v1 -kind: ConfigMap -metadata: - name: otel-collector-conf - namespace: monitoring - labels: - app: opentelemetry - component: otel-collector-conf -data: - otel-collector-config: | - receivers: - zipkin: {} - processors: - batch: - memory_limiter: - # Same as --mem-ballast-size-mib CLI argument - ballast_size_mib: 683 - # 80% of maximum memory up to 2G - limit_mib: 1500 - # 25% of limit up to 2G - spike_limit_mib: 512 - check_interval: 5s - queued_retry: - extensions: - health_check: {} - zpages: {} - exporters: - otlp: - endpoint: ingest.lightstep.com:443 - headers: {"lightstep-access-token":"${LIGHTSTEP_ACCESS_TOKEN}"} - service: - extensions: [health_check, zpages] - pipelines: - traces: - receivers: [zipkin] - processors: [memory_limiter, batch, queued_retry] - exporters: - - otlp ---- -apiVersion: v1 -kind: Service -metadata: - name: otel-collector - namespace: monitoring - labels: - app: opentelemetry - component: otel-collector -spec: - ports: - - name: otlp # Default endpoint for OpenTelemetry receiver. - port: 55680 - - name: zipkin # Default endpoint for Zipkin trace receiver. - port: 9411 - selector: - component: otel-collector ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: otel-collector - namespace: monitoring - labels: - app: opentelemetry - component: otel-collector -spec: - selector: - matchLabels: - app: opentelemetry - component: otel-collector - minReadySeconds: 5 - progressDeadlineSeconds: 120 - replicas: 1 - template: - metadata: - labels: - app: opentelemetry - component: otel-collector - spec: - containers: - - command: - - "/otelcontribcol" - - "--config=/conf/otel-collector-config.yaml" - - "--mem-ballast-size-mib=683" # Memory Ballast size should be max 1/3 to 1/2 of memory. - image: otel/opentelemetry-collector-contrib:0.11.0 - name: otel-collector - resources: - limits: - cpu: 1000m - memory: 2Gi - requests: - cpu: 200m - memory: 400Mi - ports: - - containerPort: 55680 # Default endpoint for OpenTelemetry receiver. - - containerPort: 9411 # Default endpoint for Zipkin receiver. - env: - - name: LIGHTSTEP_ACCESS_TOKEN - valueFrom: - secretKeyRef: - name: otel - key: lightstep_access_token - volumeMounts: - - name: otel-collector-config-vol - mountPath: /conf - livenessProbe: - httpGet: - path: / - port: 13133 - readinessProbe: - httpGet: - path: / - port: 13133 - volumes: - - configMap: - name: otel-collector-conf - items: - - key: otel-collector-config - path: otel-collector-config.yaml - name: otel-collector-config-vol -``` - -Be sure to apply this configuration with the following command: - -```bash - kubectl apply -f opentelemetry.yaml -``` - -At this point, the OpenTelemetry Collector should be setup properly and ready to send data to Lightstep. - -## 3. Configure the TracingService - -Now that the OpenTelemetry Collector is setup for collecting data, the next step will be for us to setup our [TracingService](../../topics/running/services/tracing-service). We will be using the Zipkin driver to send our request trace data to the OpenTelemetry Collector for Distributed Tracing. Please apply the following YAML. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TracingService -metadata: - name: tracing-zipkin - namespace: ambassador -spec: - service: otel-collector.monitoring:9411 - driver: zipkin -``` - -As a final step we want to restart $productName$ as this is necessary to add the distributed tracing headers. This command will restart all the Pods (assuming $productName$ is installed in the ambassador namespace): - -```bash - kubectl -n ambassador rollout restart deploy -``` - - - Restarting $productName$ is required after deploying a Tracing Service for changes to take effect. - - -## 4. Testing our Distributed Tracing - -Finally, we are going to test our Distributed Tracing. 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. - -```bash - curl -Li http://$LB_ENDPOINT/backend/ -``` - -At this point, we should be able to view and check our traces on the [Lightstep app](https://app.lightstep.com/). You can do so by clicking on the Explorer tab and searching for a trace. - -## Migrating from the Lightstep Tracing Driver - - - Please be sure to follow these steps prior to upgrading to $productName$ version 3.4.0. - - -As of $productName$ version 3.4.0, the Lightstep tracing driver will no longer be supported. This is due to the upgrade to Envoy version 1.24, where the team at LightStep has completely removed support for the LightStep Tracing driver in favor of using the OpenTelemetry Collector. In order to continue to use Lightstep to visualize our traces, we can follow similar steps to the above tutorial. - -First, make sure that the OpenTelemetry Collector is installed. This can be done by following the same commands as step 2 of this page. Please be sure to create/update the Kubernetes secret to include your Lightstep Access Token. - -Then, we simply need to edit our TracingService to point to the OpenTelemetry Collector (instead of the ingest endpoint of Lightstep) and to use the Zipkin driver. Please note that $productName$ can only support 1 TracingService per instance. Because of this, we must edit our previous TracingService rather than applying a second one. - -If you were using the Lightstep tracing driver, you may have your Lightstep Access Token information set in your TracingService config. Using a Kubernetes Secret, we no longer need to reference the token here. - -Once our TracingService configuration has been updated, a restart of $productName$ is necessary for Lightstep to recieve our Distributed Tracing information. This can be done with the following command: - -```bash - kubectl -n ambassador rollout restart deploy -``` diff --git a/content/en/docs/3.4/howtos/tracing-zipkin.md b/content/en/docs/3.4/howtos/tracing-zipkin.md deleted file mode 100644 index 37ddc902..00000000 --- a/content/en/docs/3.4/howtos/tracing-zipkin.md +++ /dev/null @@ -1,129 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Distributed tracing with Zipkin - -In this tutorial, we'll configure $productName$ to initiate a trace on some sample requests, and use Zipkin 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. Deploy Zipkin - -In this tutorial, you will use a simple deployment of the open-source [Zipkin](https://github.com/openzipkin/zipkin/wiki) distributed tracing system to store and visualize $productName$-generated traces. The trace data will be stored in memory within the Zipkin container, and you will be able to explore the traces via the Zipkin web UI. - -First, add the following YAML to a file named `zipkin.yaml`. This configuration will create a Zipkin Deployment that uses the [openzipkin/zipkin](https://hub.docker.com/r/openzipkin/zipkin/) container image and also an associated Service. We will also include a `TracingService` that configures $productName$ to use the Zipkin service (running on the default port of 9411) to provide tracing support. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TracingService -metadata: - name: tracing -spec: - service: "zipkin:9411" - driver: zipkin - config: {} ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: zipkin -spec: - replicas: 1 - selector: - matchLabels: - app: zipkin - template: - metadata: - labels: - app: zipkin - spec: - containers: - - name: zipkin - image: openzipkin/zipkin - env: - # note: in-memory storage holds all data in memory, purging older data upon a span limit. - # you should use a proper storage in production environments - - name: STORAGE_TYPE - value: mem ---- -apiVersion: v1 -kind: Service -metadata: - labels: - name: zipkin - name: zipkin -spec: - ports: - - port: 9411 - targetPort: 9411 - selector: - app: zipkin -``` - -Next, deploy this configuration into your cluster: - -``` -$ kubectl apply -f zipkin.yaml -``` - -As a final step we want to restart $productName$ as this is necessary to add the tracing header. This command will restart all the Pods (assuming $productName$ is installed in the ambassador namespace): - -``` -$ kubectl -n ambassador rollout restart deploy -``` - - Restarting $productName$ is required after deploying a Tracing Service for changes to take effect. - - -## 2. 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/backend/ -``` - -## 3. Test traces - -To test things out, we'll need to access the Zipkin UI. If you're on Kubernetes, get the name of the Zipkin pod: - -``` -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -ambassador-5ffcfc798-c25dc 2/2 Running 0 1d -prometheus-prometheus-0 2/2 Running 0 113d -zipkin-868b97667c-58v4r 1/1 Running 0 2h -``` - -And then use `kubectl port-forward` to access the pod: - -``` -$ kubectl port-forward zipkin-868b97667c-58v4r 9411 -``` - -Open your web browser to `http://localhost:9411` for the Zipkin UI. - -If you're on `minikube` you can access the `NodePort` directly, and this ports number can be obtained via the `minikube services list` command. If you are using `Docker for Mac/Windows`, you can use the `kubectl get svc` command to get the same information. - -``` -$ minikube service list -|-------------|----------------------|-----------------------------| -| NAMESPACE | NAME | URL | -|-------------|----------------------|-----------------------------| -| default | ambassador-admin | http://192.168.99.107:30319 | -| default | ambassador | http://192.168.99.107:31893 | -| default | zipkin | http://192.168.99.107:31043 | -|-------------|----------------------|-----------------------------| -``` - -Open your web browser to the Zipkin dashboard `http://192.168.99.107:31043/zipkin/`. - -In the Zipkin UI, click on the "Find Traces" button to get a listing instrumented traces. Each of the traces that are displayed can be clicked on, which provides further information about each span and associated metadata. - -## Learn more - -For more details about configuring the external tracing service, read the documentation on [external tracing](../../topics/running/services/tracing-service). diff --git a/content/en/docs/3.4/howtos/websockets.md b/content/en/docs/3.4/howtos/websockets.md deleted file mode 100644 index 25cac7da..00000000 --- a/content/en/docs/3.4/howtos/websockets.md +++ /dev/null @@ -1,43 +0,0 @@ -# WebSocket connections - -$productName$ makes it easy to access your services from outside your -application, and this includes services that use WebSockets. Only a -small amount of additional configuration is required, which is as -simple as telling the Mapping to allow "upgrading" from the HTTP protocol to -the "websocket" protocol: - -```yaml -allow_upgrade: -- websocket -``` - -## Example WebSocket service - -The example configuration below demonstrates the addition of the `allow_upgrade:` attribute to support websockets. The use of `use_websocket` is now deprecated. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: my-service-mapping -spec: - hostname: "*" - prefix: /my-service/ - service: my-service - allow_upgrade: - - websocket - ---- -kind: Service -apiVersion: v1 -metadata: - name: my-service -spec: - selector: - app: MyApp - ports: - - protocol: TCP - port: 80 - targetPort: 9376 -``` diff --git a/content/en/docs/3.4/images/Auth0_JWT.png b/content/en/docs/3.4/images/Auth0_JWT.png deleted file mode 100644 index e18155f5..00000000 Binary files a/content/en/docs/3.4/images/Auth0_JWT.png and /dev/null differ diff --git a/content/en/docs/3.4/images/Auth0_domain_clientID.png b/content/en/docs/3.4/images/Auth0_domain_clientID.png deleted file mode 100644 index a7f8edf6..00000000 Binary files a/content/en/docs/3.4/images/Auth0_domain_clientID.png and /dev/null differ diff --git a/content/en/docs/3.4/images/Auth0_method_callback_origins.png b/content/en/docs/3.4/images/Auth0_method_callback_origins.png deleted file mode 100644 index 8d31138e..00000000 Binary files a/content/en/docs/3.4/images/Auth0_method_callback_origins.png and /dev/null differ diff --git a/content/en/docs/3.4/images/aes-success.png b/content/en/docs/3.4/images/aes-success.png deleted file mode 100644 index 66f28d3f..00000000 Binary files a/content/en/docs/3.4/images/aes-success.png and /dev/null differ diff --git a/content/en/docs/3.4/images/ambassador-arch.png b/content/en/docs/3.4/images/ambassador-arch.png deleted file mode 100644 index 5a5cb652..00000000 Binary files a/content/en/docs/3.4/images/ambassador-arch.png and /dev/null differ diff --git a/content/en/docs/3.4/images/ambassador-logo.svg b/content/en/docs/3.4/images/ambassador-logo.svg deleted file mode 100644 index 1f0e06a8..00000000 --- a/content/en/docs/3.4/images/ambassador-logo.svg +++ /dev/null @@ -1,49 +0,0 @@ - - - - ambassador logo@1x - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.4/images/ambassador_oidc_flow.jpg b/content/en/docs/3.4/images/ambassador_oidc_flow.jpg deleted file mode 100644 index 4f1c0c7e..00000000 Binary files a/content/en/docs/3.4/images/ambassador_oidc_flow.jpg and /dev/null differ diff --git a/content/en/docs/3.4/images/apple.png b/content/en/docs/3.4/images/apple.png deleted file mode 100644 index 8b8277f1..00000000 Binary files a/content/en/docs/3.4/images/apple.png and /dev/null differ diff --git a/content/en/docs/3.4/images/auth-flow.png b/content/en/docs/3.4/images/auth-flow.png deleted file mode 100644 index e1ba4387..00000000 Binary files a/content/en/docs/3.4/images/auth-flow.png and /dev/null differ diff --git a/content/en/docs/3.4/images/authentication-icon.svg b/content/en/docs/3.4/images/authentication-icon.svg deleted file mode 100644 index 342e8a3d..00000000 --- a/content/en/docs/3.4/images/authentication-icon.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_897228_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.4/images/blackbird.png b/content/en/docs/3.4/images/blackbird.png deleted file mode 100644 index 1f10e5cc..00000000 Binary files a/content/en/docs/3.4/images/blackbird.png and /dev/null differ diff --git a/content/en/docs/3.4/images/canary-release-overview.png b/content/en/docs/3.4/images/canary-release-overview.png deleted file mode 100644 index c683a23d..00000000 Binary files a/content/en/docs/3.4/images/canary-release-overview.png and /dev/null differ diff --git a/content/en/docs/3.4/images/configure-icon.svg b/content/en/docs/3.4/images/configure-icon.svg deleted file mode 100644 index 0f556840..00000000 --- a/content/en/docs/3.4/images/configure-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_858572_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.4/images/consul-ambassador.png b/content/en/docs/3.4/images/consul-ambassador.png deleted file mode 100644 index c4911624..00000000 Binary files a/content/en/docs/3.4/images/consul-ambassador.png and /dev/null differ diff --git a/content/en/docs/3.4/images/container-inner-dev-loop.png b/content/en/docs/3.4/images/container-inner-dev-loop.png deleted file mode 100644 index 06586cd6..00000000 Binary files a/content/en/docs/3.4/images/container-inner-dev-loop.png and /dev/null differ diff --git a/content/en/docs/3.4/images/datawire-logo.svg b/content/en/docs/3.4/images/datawire-logo.svg deleted file mode 100644 index fb45872c..00000000 --- a/content/en/docs/3.4/images/datawire-logo.svg +++ /dev/null @@ -1,27 +0,0 @@ - - - - Group 3 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.4/images/diagnostics-example.png b/content/en/docs/3.4/images/diagnostics-example.png deleted file mode 100644 index 6c825b0c..00000000 Binary files a/content/en/docs/3.4/images/diagnostics-example.png and /dev/null differ diff --git a/content/en/docs/3.4/images/diagnostics.png b/content/en/docs/3.4/images/diagnostics.png deleted file mode 100644 index 29248703..00000000 Binary files a/content/en/docs/3.4/images/diagnostics.png and /dev/null differ diff --git a/content/en/docs/3.4/images/docker-compose.png b/content/en/docs/3.4/images/docker-compose.png deleted file mode 100644 index b8829521..00000000 Binary files a/content/en/docs/3.4/images/docker-compose.png and /dev/null differ diff --git a/content/en/docs/3.4/images/docker.png b/content/en/docs/3.4/images/docker.png deleted file mode 100644 index 1f35e5ea..00000000 Binary files a/content/en/docs/3.4/images/docker.png and /dev/null differ diff --git a/content/en/docs/3.4/images/edge-stack-1.13.4.png b/content/en/docs/3.4/images/edge-stack-1.13.4.png deleted file mode 100644 index 954ac1a9..00000000 Binary files a/content/en/docs/3.4/images/edge-stack-1.13.4.png and /dev/null differ diff --git a/content/en/docs/3.4/images/edge-stack-1.13.7-json-logging.png b/content/en/docs/3.4/images/edge-stack-1.13.7-json-logging.png deleted file mode 100644 index 4a47cbdf..00000000 Binary files a/content/en/docs/3.4/images/edge-stack-1.13.7-json-logging.png and /dev/null differ diff --git a/content/en/docs/3.4/images/edge-stack-1.13.7-memory.png b/content/en/docs/3.4/images/edge-stack-1.13.7-memory.png deleted file mode 100644 index 9c415ba3..00000000 Binary files a/content/en/docs/3.4/images/edge-stack-1.13.7-memory.png and /dev/null differ diff --git a/content/en/docs/3.4/images/edge-stack-1.13.7-tcpmapping-consul.png b/content/en/docs/3.4/images/edge-stack-1.13.7-tcpmapping-consul.png deleted file mode 100644 index c455a47f..00000000 Binary files a/content/en/docs/3.4/images/edge-stack-1.13.7-tcpmapping-consul.png and /dev/null differ diff --git a/content/en/docs/3.4/images/edge-stack-1.13.8-cloud-bugfix.png b/content/en/docs/3.4/images/edge-stack-1.13.8-cloud-bugfix.png deleted file mode 100644 index 6beaf653..00000000 Binary files a/content/en/docs/3.4/images/edge-stack-1.13.8-cloud-bugfix.png and /dev/null differ diff --git a/content/en/docs/3.4/images/emissary-1.13.10-cors-origin.png b/content/en/docs/3.4/images/emissary-1.13.10-cors-origin.png deleted file mode 100644 index b7538e5f..00000000 Binary files a/content/en/docs/3.4/images/emissary-1.13.10-cors-origin.png and /dev/null differ diff --git a/content/en/docs/3.4/images/fast-icon.svg b/content/en/docs/3.4/images/fast-icon.svg deleted file mode 100644 index 354542ee..00000000 --- a/content/en/docs/3.4/images/fast-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1187990_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.4/images/features-icons/basic-authentication.svg b/content/en/docs/3.4/images/features-icons/basic-authentication.svg deleted file mode 100644 index 2bd19edf..00000000 --- a/content/en/docs/3.4/images/features-icons/basic-authentication.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_897228_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.4/images/features-icons/canary-release.svg b/content/en/docs/3.4/images/features-icons/canary-release.svg deleted file mode 100644 index f8de57d9..00000000 --- a/content/en/docs/3.4/images/features-icons/canary-release.svg +++ /dev/null @@ -1,27 +0,0 @@ - - - - Group 25 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.4/images/features-icons/cors.svg b/content/en/docs/3.4/images/features-icons/cors.svg deleted file mode 100644 index e559d924..00000000 --- a/content/en/docs/3.4/images/features-icons/cors.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_111967_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.4/images/features-icons/datadog.png b/content/en/docs/3.4/images/features-icons/datadog.png deleted file mode 100644 index eea05f8c..00000000 Binary files a/content/en/docs/3.4/images/features-icons/datadog.png and /dev/null differ diff --git a/content/en/docs/3.4/images/features-icons/datadog.svg b/content/en/docs/3.4/images/features-icons/datadog.svg deleted file mode 100644 index e46e8118..00000000 --- a/content/en/docs/3.4/images/features-icons/datadog.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Screen Shot 2018-04-05 at 8.22.25 AM - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.4/images/features-icons/diagnostics.svg b/content/en/docs/3.4/images/features-icons/diagnostics.svg deleted file mode 100644 index 940e1bc2..00000000 --- a/content/en/docs/3.4/images/features-icons/diagnostics.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_196445_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.4/images/features-icons/distributed-tracing.png b/content/en/docs/3.4/images/features-icons/distributed-tracing.png deleted file mode 100644 index 6b69e28c..00000000 Binary files a/content/en/docs/3.4/images/features-icons/distributed-tracing.png and /dev/null differ diff --git a/content/en/docs/3.4/images/features-icons/grpc.png b/content/en/docs/3.4/images/features-icons/grpc.png deleted file mode 100644 index b2f5a0d9..00000000 Binary files a/content/en/docs/3.4/images/features-icons/grpc.png and /dev/null differ diff --git a/content/en/docs/3.4/images/features-icons/prometheus.svg b/content/en/docs/3.4/images/features-icons/prometheus.svg deleted file mode 100644 index d5252a66..00000000 --- a/content/en/docs/3.4/images/features-icons/prometheus.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - prometheus_logo_grey - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.4/images/features-icons/rate-limiting.svg b/content/en/docs/3.4/images/features-icons/rate-limiting.svg deleted file mode 100644 index f1b6eacb..00000000 --- a/content/en/docs/3.4/images/features-icons/rate-limiting.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - Group 10 - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.4/images/features-icons/regex-routing.svg b/content/en/docs/3.4/images/features-icons/regex-routing.svg deleted file mode 100644 index 113b53b5..00000000 --- a/content/en/docs/3.4/images/features-icons/regex-routing.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_699774_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.4/images/features-icons/request-transformers.svg b/content/en/docs/3.4/images/features-icons/request-transformers.svg deleted file mode 100644 index 0b13e2dc..00000000 --- a/content/en/docs/3.4/images/features-icons/request-transformers.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_96239_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.4/images/features-icons/shadowing.svg b/content/en/docs/3.4/images/features-icons/shadowing.svg deleted file mode 100644 index 9e85eee1..00000000 --- a/content/en/docs/3.4/images/features-icons/shadowing.svg +++ /dev/null @@ -1,15 +0,0 @@ - - - - shadow - Created with Sketch. - - - - - - - - - - diff --git a/content/en/docs/3.4/images/features-icons/statsd.png b/content/en/docs/3.4/images/features-icons/statsd.png deleted file mode 100644 index 28374438..00000000 Binary files a/content/en/docs/3.4/images/features-icons/statsd.png and /dev/null differ diff --git a/content/en/docs/3.4/images/features-icons/statsd.svg b/content/en/docs/3.4/images/features-icons/statsd.svg deleted file mode 100644 index cabc90db..00000000 --- a/content/en/docs/3.4/images/features-icons/statsd.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - 88eb31f74479e422e4e9abfc6c2b00ee - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.4/images/features-icons/third-party-auth.svg b/content/en/docs/3.4/images/features-icons/third-party-auth.svg deleted file mode 100644 index 5359a24a..00000000 --- a/content/en/docs/3.4/images/features-icons/third-party-auth.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_511233_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.4/images/features-icons/timeouts.svg b/content/en/docs/3.4/images/features-icons/timeouts.svg deleted file mode 100644 index 47f63056..00000000 --- a/content/en/docs/3.4/images/features-icons/timeouts.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_587034_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.4/images/features-icons/tls-termination.svg b/content/en/docs/3.4/images/features-icons/tls-termination.svg deleted file mode 100644 index 6a631a96..00000000 --- a/content/en/docs/3.4/images/features-icons/tls-termination.svg +++ /dev/null @@ -1,17 +0,0 @@ - - - - noun_63544_cc - Created with Sketch. - - - - - - - - - - - - diff --git a/content/en/docs/3.4/images/features-icons/url-rewrite.svg b/content/en/docs/3.4/images/features-icons/url-rewrite.svg deleted file mode 100644 index 023e2e05..00000000 --- a/content/en/docs/3.4/images/features-icons/url-rewrite.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1295942_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.4/images/features-icons/websockets.svg b/content/en/docs/3.4/images/features-icons/websockets.svg deleted file mode 100644 index af17b9c0..00000000 --- a/content/en/docs/3.4/images/features-icons/websockets.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - noun_50814_cc - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.4/images/features-table.jpg b/content/en/docs/3.4/images/features-table.jpg deleted file mode 100644 index 3de2eb4f..00000000 Binary files a/content/en/docs/3.4/images/features-table.jpg and /dev/null differ diff --git a/content/en/docs/3.4/images/gRPC-TLS-Ambassador.png b/content/en/docs/3.4/images/gRPC-TLS-Ambassador.png deleted file mode 100644 index 0189253e..00000000 Binary files a/content/en/docs/3.4/images/gRPC-TLS-Ambassador.png and /dev/null differ diff --git a/content/en/docs/3.4/images/gRPC-TLS-Originate.png b/content/en/docs/3.4/images/gRPC-TLS-Originate.png deleted file mode 100644 index 1b62010d..00000000 Binary files a/content/en/docs/3.4/images/gRPC-TLS-Originate.png and /dev/null differ diff --git a/content/en/docs/3.4/images/github-login.png b/content/en/docs/3.4/images/github-login.png deleted file mode 100644 index cfd4d4bf..00000000 Binary files a/content/en/docs/3.4/images/github-login.png and /dev/null differ diff --git a/content/en/docs/3.4/images/global-features-bg.svg b/content/en/docs/3.4/images/global-features-bg.svg deleted file mode 100644 index a39c5232..00000000 --- a/content/en/docs/3.4/images/global-features-bg.svg +++ /dev/null @@ -1,34 +0,0 @@ - - - - ambassador_logo@2x - Created with Sketch. - - - - - - - - diff --git a/content/en/docs/3.4/images/grafana.png b/content/en/docs/3.4/images/grafana.png deleted file mode 100644 index 03912506..00000000 Binary files a/content/en/docs/3.4/images/grafana.png and /dev/null differ diff --git a/content/en/docs/3.4/images/grpc-tls.png b/content/en/docs/3.4/images/grpc-tls.png deleted file mode 100644 index 4d705ff0..00000000 Binary files a/content/en/docs/3.4/images/grpc-tls.png and /dev/null differ diff --git a/content/en/docs/3.4/images/helm-navy.png b/content/en/docs/3.4/images/helm-navy.png deleted file mode 100644 index a9710143..00000000 Binary files a/content/en/docs/3.4/images/helm-navy.png and /dev/null differ diff --git a/content/en/docs/3.4/images/helm.png b/content/en/docs/3.4/images/helm.png deleted file mode 100644 index 1c5af71b..00000000 Binary files a/content/en/docs/3.4/images/helm.png and /dev/null differ diff --git a/content/en/docs/3.4/images/highly-available-icon.svg b/content/en/docs/3.4/images/highly-available-icon.svg deleted file mode 100644 index 9cb3eff9..00000000 --- a/content/en/docs/3.4/images/highly-available-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1205522_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.4/images/jaeger.png b/content/en/docs/3.4/images/jaeger.png deleted file mode 100644 index 3b821c09..00000000 Binary files a/content/en/docs/3.4/images/jaeger.png and /dev/null differ diff --git a/content/en/docs/3.4/images/kubernetes.png b/content/en/docs/3.4/images/kubernetes.png deleted file mode 100644 index a392a886..00000000 Binary files a/content/en/docs/3.4/images/kubernetes.png and /dev/null differ diff --git a/content/en/docs/3.4/images/left-arrow.svg b/content/en/docs/3.4/images/left-arrow.svg deleted file mode 100644 index 75cdc7f1..00000000 --- a/content/en/docs/3.4/images/left-arrow.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Path 2 - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.4/images/linux.png b/content/en/docs/3.4/images/linux.png deleted file mode 100644 index 1832c594..00000000 Binary files a/content/en/docs/3.4/images/linux.png and /dev/null differ diff --git a/content/en/docs/3.4/images/logo.png b/content/en/docs/3.4/images/logo.png deleted file mode 100644 index 701f63ba..00000000 Binary files a/content/en/docs/3.4/images/logo.png and /dev/null differ diff --git a/content/en/docs/3.4/images/mapping-editor.png b/content/en/docs/3.4/images/mapping-editor.png deleted file mode 100644 index f8b751a1..00000000 Binary files a/content/en/docs/3.4/images/mapping-editor.png and /dev/null differ diff --git a/content/en/docs/3.4/images/network-architecture.png b/content/en/docs/3.4/images/network-architecture.png deleted file mode 100644 index 3217b3e1..00000000 Binary files a/content/en/docs/3.4/images/network-architecture.png and /dev/null differ diff --git a/content/en/docs/3.4/images/penguin-background.svg b/content/en/docs/3.4/images/penguin-background.svg deleted file mode 100644 index 7affc0d5..00000000 --- a/content/en/docs/3.4/images/penguin-background.svg +++ /dev/null @@ -1,102 +0,0 @@ - - - - @2xambassador_logo - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.4/images/pro-iap.png b/content/en/docs/3.4/images/pro-iap.png deleted file mode 100644 index 787265d8..00000000 Binary files a/content/en/docs/3.4/images/pro-iap.png and /dev/null differ diff --git a/content/en/docs/3.4/images/quote.svg b/content/en/docs/3.4/images/quote.svg deleted file mode 100644 index bab6e871..00000000 --- a/content/en/docs/3.4/images/quote.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - “ - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.4/images/right-arrow.svg b/content/en/docs/3.4/images/right-arrow.svg deleted file mode 100644 index 627144c6..00000000 --- a/content/en/docs/3.4/images/right-arrow.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Path 2 Copy - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.4/images/routing-icon.svg b/content/en/docs/3.4/images/routing-icon.svg deleted file mode 100644 index bd860b13..00000000 --- a/content/en/docs/3.4/images/routing-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1062254_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.4/images/self-service-features-bg.svg b/content/en/docs/3.4/images/self-service-features-bg.svg deleted file mode 100644 index 40bc400a..00000000 --- a/content/en/docs/3.4/images/self-service-features-bg.svg +++ /dev/null @@ -1,93 +0,0 @@ - - - - Group 8 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - SELF-SERVICE FEATURES - - - - diff --git a/content/en/docs/3.4/images/shadowing.png b/content/en/docs/3.4/images/shadowing.png deleted file mode 100644 index 097ecbd5..00000000 Binary files a/content/en/docs/3.4/images/shadowing.png and /dev/null differ diff --git a/content/en/docs/3.4/images/speedometers.png b/content/en/docs/3.4/images/speedometers.png deleted file mode 100644 index 7ce2c2a2..00000000 Binary files a/content/en/docs/3.4/images/speedometers.png and /dev/null differ diff --git a/content/en/docs/3.4/images/tp-architecture.png b/content/en/docs/3.4/images/tp-architecture.png deleted file mode 100644 index 20ae3589..00000000 Binary files a/content/en/docs/3.4/images/tp-architecture.png and /dev/null differ diff --git a/content/en/docs/3.4/images/tp-tutorial-1.png b/content/en/docs/3.4/images/tp-tutorial-1.png deleted file mode 100644 index ee68dc7d..00000000 Binary files a/content/en/docs/3.4/images/tp-tutorial-1.png and /dev/null differ diff --git a/content/en/docs/3.4/images/tp-tutorial-2.png b/content/en/docs/3.4/images/tp-tutorial-2.png deleted file mode 100644 index 129dc6ee..00000000 Binary files a/content/en/docs/3.4/images/tp-tutorial-2.png and /dev/null differ diff --git a/content/en/docs/3.4/images/tp-tutorial-3.png b/content/en/docs/3.4/images/tp-tutorial-3.png deleted file mode 100644 index 946629fc..00000000 Binary files a/content/en/docs/3.4/images/tp-tutorial-3.png and /dev/null differ diff --git a/content/en/docs/3.4/images/tp-tutorial-4.png b/content/en/docs/3.4/images/tp-tutorial-4.png deleted file mode 100644 index cb6e7a9d..00000000 Binary files a/content/en/docs/3.4/images/tp-tutorial-4.png and /dev/null differ diff --git a/content/en/docs/3.4/images/trad-inner-dev-loop.png b/content/en/docs/3.4/images/trad-inner-dev-loop.png deleted file mode 100644 index 618b674f..00000000 Binary files a/content/en/docs/3.4/images/trad-inner-dev-loop.png and /dev/null differ diff --git a/content/en/docs/3.4/images/windows.png b/content/en/docs/3.4/images/windows.png deleted file mode 100644 index a065dc17..00000000 Binary files a/content/en/docs/3.4/images/windows.png and /dev/null differ diff --git a/content/en/docs/3.4/images/xkcd.png b/content/en/docs/3.4/images/xkcd.png deleted file mode 100644 index ed0d5c33..00000000 Binary files a/content/en/docs/3.4/images/xkcd.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/edge-stack-1.13.4.png b/content/en/docs/3.4/release-notes/edge-stack-1.13.4.png deleted file mode 100644 index 954ac1a9..00000000 Binary files a/content/en/docs/3.4/release-notes/edge-stack-1.13.4.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/edge-stack-1.13.7-json-logging.png b/content/en/docs/3.4/release-notes/edge-stack-1.13.7-json-logging.png deleted file mode 100644 index 4a47cbdf..00000000 Binary files a/content/en/docs/3.4/release-notes/edge-stack-1.13.7-json-logging.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/edge-stack-1.13.7-memory.png b/content/en/docs/3.4/release-notes/edge-stack-1.13.7-memory.png deleted file mode 100644 index 9c415ba3..00000000 Binary files a/content/en/docs/3.4/release-notes/edge-stack-1.13.7-memory.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/edge-stack-1.13.7-tcpmapping-consul.png b/content/en/docs/3.4/release-notes/edge-stack-1.13.7-tcpmapping-consul.png deleted file mode 100644 index c455a47f..00000000 Binary files a/content/en/docs/3.4/release-notes/edge-stack-1.13.7-tcpmapping-consul.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/edge-stack-1.13.8-cloud-bugfix.png b/content/en/docs/3.4/release-notes/edge-stack-1.13.8-cloud-bugfix.png deleted file mode 100644 index 6beaf653..00000000 Binary files a/content/en/docs/3.4/release-notes/edge-stack-1.13.8-cloud-bugfix.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/edge-stack-2.0.0-host_crd.png b/content/en/docs/3.4/release-notes/edge-stack-2.0.0-host_crd.png deleted file mode 100644 index c77ef528..00000000 Binary files a/content/en/docs/3.4/release-notes/edge-stack-2.0.0-host_crd.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/edge-stack-2.0.0-ingressstatus.png b/content/en/docs/3.4/release-notes/edge-stack-2.0.0-ingressstatus.png deleted file mode 100644 index 6856d308..00000000 Binary files a/content/en/docs/3.4/release-notes/edge-stack-2.0.0-ingressstatus.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/edge-stack-2.0.0-insecure_action_hosts.png b/content/en/docs/3.4/release-notes/edge-stack-2.0.0-insecure_action_hosts.png deleted file mode 100644 index 79c20bad..00000000 Binary files a/content/en/docs/3.4/release-notes/edge-stack-2.0.0-insecure_action_hosts.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/edge-stack-2.0.0-listener.png b/content/en/docs/3.4/release-notes/edge-stack-2.0.0-listener.png deleted file mode 100644 index ea45a02b..00000000 Binary files a/content/en/docs/3.4/release-notes/edge-stack-2.0.0-listener.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/edge-stack-2.0.0-prune_routes.png b/content/en/docs/3.4/release-notes/edge-stack-2.0.0-prune_routes.png deleted file mode 100644 index bc43229f..00000000 Binary files a/content/en/docs/3.4/release-notes/edge-stack-2.0.0-prune_routes.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/edge-stack-2.0.0-tlscontext.png b/content/en/docs/3.4/release-notes/edge-stack-2.0.0-tlscontext.png deleted file mode 100644 index 68dbad80..00000000 Binary files a/content/en/docs/3.4/release-notes/edge-stack-2.0.0-tlscontext.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/edge-stack-2.0.0-v3alpha1.png b/content/en/docs/3.4/release-notes/edge-stack-2.0.0-v3alpha1.png deleted file mode 100644 index c0ac3596..00000000 Binary files a/content/en/docs/3.4/release-notes/edge-stack-2.0.0-v3alpha1.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/emissary-1.13.10-cors-origin.png b/content/en/docs/3.4/release-notes/emissary-1.13.10-cors-origin.png deleted file mode 100644 index b7538e5f..00000000 Binary files a/content/en/docs/3.4/release-notes/emissary-1.13.10-cors-origin.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/emissary-ga.png b/content/en/docs/3.4/release-notes/emissary-ga.png deleted file mode 100644 index 062f043a..00000000 Binary files a/content/en/docs/3.4/release-notes/emissary-ga.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/tada.png b/content/en/docs/3.4/release-notes/tada.png deleted file mode 100644 index c8832e8e..00000000 Binary files a/content/en/docs/3.4/release-notes/tada.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/v2.0.4-k8s-1.22.png b/content/en/docs/3.4/release-notes/v2.0.4-k8s-1.22.png deleted file mode 100644 index ed9b0415..00000000 Binary files a/content/en/docs/3.4/release-notes/v2.0.4-k8s-1.22.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/v2.0.4-l7depth.png b/content/en/docs/3.4/release-notes/v2.0.4-l7depth.png deleted file mode 100644 index 9314324c..00000000 Binary files a/content/en/docs/3.4/release-notes/v2.0.4-l7depth.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/v2.0.4-mapping-dns-type.png b/content/en/docs/3.4/release-notes/v2.0.4-mapping-dns-type.png deleted file mode 100644 index 7770c77d..00000000 Binary files a/content/en/docs/3.4/release-notes/v2.0.4-mapping-dns-type.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/v2.0.4-v3alpha1.png b/content/en/docs/3.4/release-notes/v2.0.4-v3alpha1.png deleted file mode 100644 index 9c50b8fb..00000000 Binary files a/content/en/docs/3.4/release-notes/v2.0.4-v3alpha1.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/v2.0.4-version.png b/content/en/docs/3.4/release-notes/v2.0.4-version.png deleted file mode 100644 index 9481b7db..00000000 Binary files a/content/en/docs/3.4/release-notes/v2.0.4-version.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/v2.0.5-auth-circuit-breaker.png b/content/en/docs/3.4/release-notes/v2.0.5-auth-circuit-breaker.png deleted file mode 100644 index cac8cf7b..00000000 Binary files a/content/en/docs/3.4/release-notes/v2.0.5-auth-circuit-breaker.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/v2.0.5-mappingselector.png b/content/en/docs/3.4/release-notes/v2.0.5-mappingselector.png deleted file mode 100644 index 31942ede..00000000 Binary files a/content/en/docs/3.4/release-notes/v2.0.5-mappingselector.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/v2.1.0-canary.png b/content/en/docs/3.4/release-notes/v2.1.0-canary.png deleted file mode 100644 index 39d3bbbf..00000000 Binary files a/content/en/docs/3.4/release-notes/v2.1.0-canary.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/v2.1.0-gzip-enabled.png b/content/en/docs/3.4/release-notes/v2.1.0-gzip-enabled.png deleted file mode 100644 index 061fcbc9..00000000 Binary files a/content/en/docs/3.4/release-notes/v2.1.0-gzip-enabled.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/v2.1.0-smoother-migration.png b/content/en/docs/3.4/release-notes/v2.1.0-smoother-migration.png deleted file mode 100644 index ebd77497..00000000 Binary files a/content/en/docs/3.4/release-notes/v2.1.0-smoother-migration.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/v2.1.2-annotations.png b/content/en/docs/3.4/release-notes/v2.1.2-annotations.png deleted file mode 100644 index b5498c3c..00000000 Binary files a/content/en/docs/3.4/release-notes/v2.1.2-annotations.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/v2.1.2-host-mapping-matching.png b/content/en/docs/3.4/release-notes/v2.1.2-host-mapping-matching.png deleted file mode 100644 index 1cfba5ed..00000000 Binary files a/content/en/docs/3.4/release-notes/v2.1.2-host-mapping-matching.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/v2.1.2-mapping-cors.png b/content/en/docs/3.4/release-notes/v2.1.2-mapping-cors.png deleted file mode 100644 index f76ea01c..00000000 Binary files a/content/en/docs/3.4/release-notes/v2.1.2-mapping-cors.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/v2.1.2-mapping-less-weighted.png b/content/en/docs/3.4/release-notes/v2.1.2-mapping-less-weighted.png deleted file mode 100644 index 7e299062..00000000 Binary files a/content/en/docs/3.4/release-notes/v2.1.2-mapping-less-weighted.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/v2.1.2-mapping-no-rewrite.png b/content/en/docs/3.4/release-notes/v2.1.2-mapping-no-rewrite.png deleted file mode 100644 index 5d3d5a29..00000000 Binary files a/content/en/docs/3.4/release-notes/v2.1.2-mapping-no-rewrite.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/v2.2.0-cloud.png b/content/en/docs/3.4/release-notes/v2.2.0-cloud.png deleted file mode 100644 index 5923fcb4..00000000 Binary files a/content/en/docs/3.4/release-notes/v2.2.0-cloud.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/v2.2.0-percent-escape.png b/content/en/docs/3.4/release-notes/v2.2.0-percent-escape.png deleted file mode 100644 index df4d81b9..00000000 Binary files a/content/en/docs/3.4/release-notes/v2.2.0-percent-escape.png and /dev/null differ diff --git a/content/en/docs/3.4/release-notes/v2.2.0-tls-cert-validation.png b/content/en/docs/3.4/release-notes/v2.2.0-tls-cert-validation.png deleted file mode 100644 index f8635b5a..00000000 Binary files a/content/en/docs/3.4/release-notes/v2.2.0-tls-cert-validation.png and /dev/null differ diff --git a/content/en/docs/3.4/releaseNotes.yml b/content/en/docs/3.4/releaseNotes.yml deleted file mode 100644 index c96d3d9b..00000000 --- a/content/en/docs/3.4/releaseNotes.yml +++ /dev/null @@ -1,1450 +0,0 @@ -# -*- fill-column: 100 -*- - -# This file should be placed in the folder for the version of the -# product that's meant to be documented. A `/release-notes` page will -# be automatically generated and populated at build time. -# -# Note that an entry needs to be added to the `doc-links.yml` file in -# order to surface the release notes in the table of contents. -# -# The YAML in this file should contain: -# -# changelog: An (optional) URL to the CHANGELOG for the product. -# items: An array of releases with the following attributes: -# - version: The (optional) version number of the release, if applicable. -# - date: The date of the release in the format YYYY-MM-DD. -# - notes: An array of noteworthy changes included in the release, each having the following attributes: -# - type: The type of change, one of `bugfix`, `feature`, `security` or `change`. -# - title: A short title of the noteworthy change. -# - body: >- -# Two or three sentences describing the change and why it -# is noteworthy. This is HTML, not plain text or -# markdown. It is handy to use YAML's ">-" feature to -# allow line-wrapping. -# - image: >- -# The URL of an image that visually represents the -# noteworthy change. This path is relative to the -# `release-notes` directory; if this file is -# `FOO/releaseNotes.yml`, then the image paths are -# relative to `FOO/release-notes/`. -# - docs: The path to the documentation page where additional information can be found. -# - href: A path from the root to a resource on the getambassador website, takes precedence over a docs link. - -changelog: https://github.com/emissary-ingress/emissary/blob/$branch$/CHANGELOG.md -items: - - 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:

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

- - Users that are using $productName$ with Certificate Revocation List and allow external users to provide input should upgrade to ensure they are not vulnerable to CVE-2023-0286. - - - version: 3.4.0 - date: '2023-01-03' - notes: - - title: Upgrade to Envoy 1.24.1 - type: feature - body: >- - This upgrades $productName$ to be built on Envoy v1.24.1. Two notable changes were introduced:

- - First, the team at LightStep and the Envoy Maintainers have decided to no longer support the native LightStep tracing driver in favor of using the Open Telemetry driver. The code for the native Enovy LightStep driver has been removed from the Envoy code base. This means $productName$ will no longer support LightStep in the 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.

- - Second, a bug was fixed in Envoy 1.24 that changes how the upstream clusters distributed tracing 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.

- - This allows the healthcheck server to be configured to use IPv6-only k8s environments. (Thanks to Dmitry Golushko!). - docs: https://www.getambassador.io/docs/emissary/pre-release/topics/running/environment/ - - - 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 - - - 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. $productName$ does not expose any of these golang servers to external clients directly. - - - 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: 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 - - - 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 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: 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/content/en/docs/3.4/topics/concepts/architecture.md b/content/en/docs/3.4/topics/concepts/architecture.md deleted file mode 100644 index fe9e0bd3..00000000 --- a/content/en/docs/3.4/topics/concepts/architecture.md +++ /dev/null @@ -1,27 +0,0 @@ -# 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). - -![Architecture](../../images/ambassador-arch.png) - -## 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/content/en/docs/3.4/topics/concepts/gitops-continuous-delivery.md b/content/en/docs/3.4/topics/concepts/gitops-continuous-delivery.md deleted file mode 100644 index 336a1c66..00000000 --- a/content/en/docs/3.4/topics/concepts/gitops-continuous-delivery.md +++ /dev/null @@ -1,66 +0,0 @@ -# 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/content/en/docs/3.4/topics/concepts/index.md b/content/en/docs/3.4/topics/concepts/index.md deleted file mode 100644 index 2d02a027..00000000 --- a/content/en/docs/3.4/topics/concepts/index.md +++ /dev/null @@ -1,10 +0,0 @@ -# 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/content/en/docs/3.4/topics/concepts/kubernetes-network-architecture.md b/content/en/docs/3.4/topics/concepts/kubernetes-network-architecture.md deleted file mode 100644 index 2239a24f..00000000 --- a/content/en/docs/3.4/topics/concepts/kubernetes-network-architecture.md +++ /dev/null @@ -1,52 +0,0 @@ -# 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: - -
- -![Kubernetes Network Architecture](/../../images/documentation/kubernetes-network.inline.svg) - -
- -Each of the components in this topology is discussed in further detail below. - -### Load balancer - -The load balancer is deployed outside of the Kubernetes cluster. Typically, the load balancer also has one or more static IP addresses assigned to it. A DNS entry is then created to map a domain name (e.g., example.com) to the static IP address. - -Cloud infrastructure providers such as Amazon Web Services, Azure, Digital Ocean, and Google make it easy to create these load balancers directly from Kubernetes. This is done by creating a Kubernetes service of `type: LoadBalancer`. When this service is created, the cloud provider will use the metadata contained in the Kubernetes service definition to provision a load balancer. - -If the Kubernetes cluster is deployed in a private data center, an external load balancer is still generally used. Provisioning of this load balancer usually requires the involvement of the data center operations team. - -In both the private data center and cloud infrastructure case, the external load balancer should be configured to point to the edge proxy. - -### Edge Proxy / ingress controller - -The Edge Proxy is typically a Layer 7 proxy that is deployed directly in the cluster. The core function of the edge proxy is to accept incoming traffic from the external load balancer and route the traffic to Kubernetes services. The edge proxy should be configured using Kubernetes manifests. This enables a common management workflow for both the edge proxy and Kubernetes services. - -The most popular approach to configuring edge proxies is with the Kubernetes ingress resource. When an edge proxy can process ingress resources, it is called an ingress controller. Not all edge proxies are ingress controllers (because they can't process ingress resources), but all ingress controllers are edge proxies. - -The ingress resource is a Kubernetes standard. As such, it is a lowest common denominator resource. In practice, users find that the ingress resource is insufficient in scope to address the requirements for edge routing. Semantics such as TLS termination, redirecting to TLS, timeouts, rate limiting, and authentication are all beyond the scope of the ingress resource. - -$productName$ can function as an ingress controller (i.e., it reads ingress resources), although it also includes many other capabilities that are beyond the scope of the ingress specification. Most $productName$ users find that the various additional capabilities of $productName$ are essential, and end up using $productName$'s extensions to the ingress resource, instead of using ingress resources themselves. - -### Kubernetes services and Pods - -Each instance of your application is deployed in a Kubernetes pod. As the workload on your application increases or decreases, Kubernetes can automatically add or remove pods. A Kubernetes _service_ represents a group of pods that comprise the same version of a given application. Traffic can be routed to the pods via a Kubernetes service, or it can be routed directly to the pods. - -When traffic is routed to the pods via a Kubernetes service, Kubernetes uses a built-in mechanism called `kube-proxy` to load balance traffic between the pods. Due to its implementation, `kube-proxy` is a Layer 4 proxy, i.e., it load balances at a connection level. For particular types of traffic such as HTTP/2 and gRPC, this form of load balancing is particularly problematic as it can easily result in a very uneven load balancing configuration. - -Traffic can also be routed directly to pods, bypassing the Kubernetes service. Since pods are much more ephemeral than Kubernetes services, this approach requires an edge proxy that is optimized for this use case. In particular, the edge proxy needs to support real-time discovery of pods, and be able to dynamically update pod locations without downtime. - -$productName$ supports routing both to Kubernetes services and directly to pods. - -## Further reading - -* [Kubernetes Ingress 101](https://blog.getambassador.io/kubernetes-ingress-nodeport-load-balancers-and-ingress-controllers-6e29f1c44f2d) -* [Envoy Proxy Performance on Kubernetes](/resources/envoyproxy-performance-on-k8s/) diff --git a/content/en/docs/3.4/topics/concepts/microservices-api-gateways.md b/content/en/docs/3.4/topics/concepts/microservices-api-gateways.md deleted file mode 100644 index ba95b8fc..00000000 --- a/content/en/docs/3.4/topics/concepts/microservices-api-gateways.md +++ /dev/null @@ -1,60 +0,0 @@ -# Microservices API gateways - -A microservices API gateway is an API gateway designed to accelerate the development workflow of independent services teams. A microservices API gateway provides all the functionality for a team to independently publish, monitor, and update a microservice. - -This focus on accelerating the development workflow is distinct from the purpose of traditional API gateways, which focus on the challenges of managing APIs. Over the past decade, organizations have worked to expose internal systems through well-defined APIs. The challenge of safely exposing hundreds or thousands of APIs to end-users (both internal and external) led to the emergence of API gateways. Over time, API gateways have become centralized, mission critical pieces of infrastructure that control access to these APIs. - -In this article, we'll discuss how the difference in business objective (productivity vs management) results in a very different API gateway. - -## Microservices organization - -In a microservices organization, small teams of developers work independently from each other to rapidly deliver functionality to the customer. In order for each service team to work independently, with a productive workflow, a services team needs to be able to: - -1. Publish their service, so that others can use the service -2. Monitor their service, to see how well it's working -3. Test and update their service, so they can keep on improving the service - -The team needs to do all of this *without* requiring assistance from another operations or platform team--as soon as a services team requires another team, they're no longer working independently, and this can lead to bottlenecks. - -For service publication, a microservices API gateway provides a static address for consumers, and dynamically route requests to the appropriate service address. In addition, providing authentication and TLS termination for security are typical considerations in exposing a service to other consumers. - -Understanding the end-user experience of a service is crucial to improving the service. For example, a software update could inadvertently impact the latency of certain requests. A microservices API gateway is well situated to collect key observability metrics on end-user traffic as it routes traffic to the end service. - -A microservices API gateway also supports dynamically routing user requests to different service versions for canary testing. By routing a small fraction of end-user requests to a new version of a service, service teams can safely test the impact of new updates to a small subset of users. - -## Microservices API Gateways vs. enterprise API Gateways - -At first glance, the use case described above may be fulfilled with an enterprise-focused API gateway. While this may be true, the actual emphasis of enterprise API gateways and microservices API gateways are somewhat different: - -| Use case | Traditional Enterprise API gateway | Microservices API gateway | -|---------------|-------------------|------------------------------| -| Primary Purpose | Expose, compose, and manage internal business APIs | Expose and observe internal business services | -| Publishing Functionality | API management team or service team registers / updates gateway via admin API | Service team registers / updates gateway via declarative code as part of the deployment process | -| Monitoring | Admin and operations focused e.g. meter API calls per consumer, report errors (e.g. internal 5XX). | Developer focused e.g. latency, traffic, errors, saturation | -| Handling and Debugging Issues | L7 error-handling (e.g. custom error page or payload). Run gateway/API with additional logging. Troubleshoot issue in staging environment | Configure more detailed monitoring. Enable traffic shadowing and / or canarying | -| Testing | Operate multiple environments for QA, Staging, and Production. Automated integration testing, and gated API deployment. Use client-driven API versioning for compatibility and stability (e.g. semver) | Facilitate canary routing for dynamic testing (taking care with data mutation side effects). Use developer-driven service versioning for upgrade management | -| Local Development | Deploy gateway locally (via installation script, Vagrant or Docker), and attempt to mitigate infrastructure differences with production. Use language-specific gateway mocking and stubbing frameworks | Deploy gateway locally via service orchestration platform (e.g. Kubernetes) | - -## Self-service publishing - -A team needs to be able to publish a new service to customers without requiring an operations or API management team. This ability to self-service for deployment and publication enables the team to keep the feature release velocity high. While a traditional enterprise API gateway may provide a simple mechanism (e.g., REST API) for publishing a new service, in practice, the usage is often limited to the use of a dedicated team that is responsible for the gateway. The primary reason for limiting publication to a single team is to provide an additional (human) safety mechanism: an errant API call could have potentially disastrous effects on production. - -Microservices API gateways utilize mechanisms that enable service teams to easily *and* safely publish new services, with the inherent understanding that the producing team are responsible for their service, and will fix an issue if one occurs. A microservices gateway provides configurable monitoring for issue detection, and provides hooks for debugging, such as inspecting traffic or traffic shifting/duplication. - -## Monitoring and rate limiting - -A common business model for APIs is metering, where a consumer is charged different fees depending on API usage. Traditional enterprise API gateways excel in this use case: they provide functionality for monitoring per-client usage of an API, and the ability to limit usage when the client exceeds their quota. - -A microservice gateway also requires monitoring and rate limiting, but for different reasons. Monitoring user-visible metrics such as throughput, latency, and availability, are important to ensure that new updates don't impact the end-user. Robust end-user metrics are critical to allowing rapid, incremental updates. Rate limiting is used to improve the overall resilience of a service. When a service is not responding as expected, an API gateway can throttle incoming requests to allow a service to recover and prevent a cascade failure. - -## Testing and updates - -A microservices application has multiple services, each of which is being independently updated. Automated pre-production testing of a moving target is necessary but not sufficient for microservices. Canary testing, where a small percentage of production traffic is routed to a new service version, is an important tool to help test an update. By limiting a new service version to a small percentage of users, the impact of a service failure is limited. - -In a traditional enterprise API gateway, routing is used to isolate or compose/aggregate changing API versions. Automated pre-production testing and manual post-production verification and exploration are required. - -## Summary - -Traditional enterprise API gateways are designed to solve the challenges of API management. While they may appear to solve some of the challenges of adopting microservices, the reality is that a microservices workflow creates a different set of requirements. Integrating a microservices API gateway into your development workflow empowers service teams to self-publish, monitor, and update their service, quickly and safely. This will enable your organization to ship software more rapidly, and with more reliability than ever before. - -For further reading on how an API Gateway can accelerate continuous delivery, read [this blog post](https://blog.getambassador.io/continuous-delivery-how-can-an-api-gateway-help-or-hinder-1ff15224ec4d). diff --git a/content/en/docs/3.4/topics/concepts/progressive-delivery.md b/content/en/docs/3.4/topics/concepts/progressive-delivery.md deleted file mode 100644 index f2ade27f..00000000 --- a/content/en/docs/3.4/topics/concepts/progressive-delivery.md +++ /dev/null @@ -1,47 +0,0 @@ -# Progressive delivery - -Today's cloud-native applications may consist of hundreds of services, each of which are being updated at any time. Thus, many cloud-native organizations augment regression test strategies with testing in production using progressive delivery techniques. - -Progressive Delivery is an approach for releasing software to production users. In the progressive delivery model, software is released to ever growing subsets of production users. This approach reduces the blast radius in the event of a failure. - -## Why test in production? - -Modern cloud applications are continuously deployed, as different teams rapidly update their respective services. Deploying and testing updates in a pre-production staging environment introduces a bottleneck to the speed of iteration. More importantly, staging environments are not representative of what will be running in production when the deployment actually occurs given the velocity of service updates and changes in production. Testing in production addresses both of these challenges: developers evaluate their changes in the real-world environment, enabling rapid iteration. - -## Progressive delivery strategies - -There are a number of different strategies for progressive delivery. These include: - -* Feature flags, where specific features are made available to specific user groups -* Canary releases, where a (small) percentage of traffic is routed to a new version of a service before the service is full production -* Traffic shadowing, where real user traffic is copied, or shadowed, from production to the service under test - -Observability is a critical requirement for testing in production. Regardless of progressive delivery strategy, collecting key metrics around latency, traffic, errors, and saturation (the [“Four Golden Signals of Monitoring”](https://landing.google.com/sre/sre-book/chapters/monitoring-distributed-systems/#xref_monitoring_golden-signals)) provides valuable insight into the stability and performance of a new version of the service. Moreover, application developers can compare the metrics (e.g., latency) between the production version and an updated version. If the metrics are similar, then updates can proceed with much greater confidence. - -$productName$ supports a variety of strategies for progressive delivery. These strategies are discussed in further detail below. - -### Canary releases - -Canary releases shifts a small amount of real user traffic from production to the service under test. - -The user will see the direct response from the canary version of the service from any traffic that is shifted to the canary release, and they will not trigger or see the response from the current production released version of the service. The canary results can also be verified (both the downstream response and associated upstream side effects), but it is key to understand that any side effects will be persisted. - -In addition to allowing verification that the service is not crashing or otherwise behaving badly from an operational perspective when dealing with real user traffic and behavior, canary releasing allows user validation. For example, if a business KPI performs worse for all canaried requests, then this most likely indicates that the canaried service should not be fully released in its current form. - -Canary tests can be automated, and are typically run after testing in a pre-production environment has been completed. The canary release is only visible to a fraction of actual users, and any bugs or negative changes can be reversed quickly by either routing traffic away from the canary or by rolling-back the canary deployment. - -![Canary release process overview](../../images/canary-release-overview.png) - -Canary releases are not a panacea. In particular, many services may not receive sufficient traffic in order for canary releases to provide useful information in an actionable timeframe. - -### Traffic shadowing - -This approach “shadows” or mirrors a small amount of real user traffic from production to the service under test. - -Although the shadowed results can be verified (both the downstream response and associated upstream side effects) they are not returned to the user -- the user only sees the results from the currently released service. Typically any side effects are not persisted or are executed as a no-op and verified (much like setting up a mock, and verifying that a method/function was called with the correct parameters). - -This allows verification that the service is not crashing or otherwise behaving badly from an operational perspective when dealing with real user traffic and behavior (and the larger the percentage of traffic shadowed, the higher the probability of confidence). - -## Further reading - -* [Canary release pattern](https://blog.getambassador.io/cloud-native-patterns-canary-release-1cb8f82d371a) diff --git a/content/en/docs/3.4/topics/concepts/rate-limiting-at-the-edge.md b/content/en/docs/3.4/topics/concepts/rate-limiting-at-the-edge.md deleted file mode 100644 index 016f5ff7..00000000 --- a/content/en/docs/3.4/topics/concepts/rate-limiting-at-the-edge.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -description: "The table below outlines several scenarios where rate limiting and load shedding can provide an effective solution to a range of functional requirements" ---- - -# Rate limiting concepts at the edge - -Rate limiting at the edge is a technique that is used to prevent a sudden or sustained increase in user traffic from breaking an API or underlying service. On the Internet, users can do whatever they want to your APIs, as you have no direct control over these end-users. Whether it’s intentional or not, these users can impact the availability, responsiveness, and scalability of your service. - -## Two approaches: Rate limiting and load shedding - -Rate limiting use cases that fall into this scenario range from implementing functional requirements related to a business scenario -- for example, where requests from paying customers is prioritized over requests from non-paying trial users -- to implementing cross-functional requirements, such as resilience from a malicious actor attempting to issue a denial-of-service (DoS) attack. - -A closely related technique to rate limiting is load shedding, and this can be used to selectively prioritize traffic (by dropping requests) based on the state of the entire system. For example, if a backend data store has become overloaded and slow to respond, it may be appropriate to drop (or “shed”) low priority requests or requests that are not time sensitive. - -## Use cases and scenarios - -The table below outlines several scenarios where rate limiting and load shedding can provide an effective solution to a range of functional and cross-functional requirements. The “Type of Rate Limiter” column provides a summary of the category of rate limiting that would be most appropriate for the scenario, and the “Specifics” column outlines what business or system properties would be involved in computing rate limiting decisions. - -| Scenario | Type of Rate Limiter |                            Specifics                        -| --- | --- | --- | -**Fairness.** One or more users are sending large volumes of requests, and thus impacting other users of the API | **User request rate limiting -** restricts each user to a predetermined number of requests per time unit.

**Concurrent user request limiting -** limits the number of concurrent user requests that can be inflight at any given point in time. |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
  • Geographic rate limiter
  • Time-based rate limiter
-**Prioritisation.** The business model depends on handling high priority requests over others | **User request rate limiting** |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device, free vs non-free user etc)
-**Resilience.** The API backend cannot scale rapidly enough to meet request demand due to a technical issue. | **Backend utilisation load shedder -** rate limit based upon utilisation of aggregate backend instances.

**Node/server utilisation load shedder -** rate limit based upon utilisation of individual or isolated groups of compute nodes/servers. |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
-**Security.** Prevent bad actors from using a DoS attack to overwhelm services, fuzzing, or brute force attacks |**User request rate limiting**

**Node/server utilisation load shedder** |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
  • Service identifier load shedder e.g. login service, audit service
-**Responsiveness.** As per the Reactive Manifesto, responsive systems focus on providing rapid and consistent response times, establishing reliable upper bounds so they deliver a consistent quality of service | **Concurrent user request limiting**

**Backend utilisation load shedder**

**Node/server utilisation load shedder** |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
  • Service identifier load shedder e.g. login service, audit service
- -## Avoiding contention with rate limiting configuration: Decoupling Dev and Ops - -One of the core features of $productName$ is the decentralization of configuration, allowing operations and development teams to independently control $productName$, as well as individual application development teams to minimize collaboration when configuring independently deployable services. This same approach applies to rate limiting configuration. - -The $productName$ rate limiting configuration allows centralized operations teams to define and implement global rate limiting and load shedding policies to protect the system, while still allowing individual application teams to define rate limiting policies that enforce business rules, for example, around paying and non-paying customers (perhaps implementing the so-called “freemium” model). See [Advanced Rate Limiting](../../../../2.0/howtos/advanced-rate-limiting) documentation for examples. - -## Benefits of applying a rate limiter to the edge - -Modern applications and APIs can experience floods of traffic over a short time period (e.g. from achieving a HackerNews front page link), and increasingly bad actors and cyber criminals are targeting public-facing services. - -By implementing rate limiting and load shedding capabilities at the edge, a large amount of scenarios that are bad for business can be mitigated. These capabilities also make the life of the operations and development team that much easier, as the need to constantly firefight ingress traffic is reduced. diff --git a/content/en/docs/3.4/topics/install/ambassador-oss-community.md b/content/en/docs/3.4/topics/install/ambassador-oss-community.md deleted file mode 100644 index b53d1407..00000000 --- a/content/en/docs/3.4/topics/install/ambassador-oss-community.md +++ /dev/null @@ -1,14 +0,0 @@ -# Integration in community projects - -import Table from "../../../../../src/components/CommunityTable"; - -**$AESproductName$ is now available and includes additional functionality beyond the current $OSSproductName$.** -These features include automatic HTTPS, OAuth/OpenID Connect authentication support, integrated rate -limiting, a developer portal, and [more](/edge-stack-faq/). - -## $OSSproductName$ integrations - -If you still want to use just $OSSproductName$, don't worry! $OSSproductName$ -is currently available out-of-the-box in some Kubernetes installers and local environments. - -
\ No newline at end of file diff --git a/content/en/docs/3.4/topics/install/bare-metal.md b/content/en/docs/3.4/topics/install/bare-metal.md deleted file mode 100644 index 84ac1c8d..00000000 --- a/content/en/docs/3.4/topics/install/bare-metal.md +++ /dev/null @@ -1,93 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Install with bare metal - -In cloud environments, provisioning a readily available network load balancer with $productName$ is the best option for handling ingress into your Kubernetes cluster. When running Kubernetes on a bare metal setup, where network load balancers are not available by default, we need to consider different options for exposing $productName$. - -## Exposing $productName$ via NodePort - -The simplest way to expose an application in Kubernetes is via a `NodePort` service. In this configuration, we create the $productName$ service] and identify `type: NodePort` instead of `LoadBalancer`. Kubernetes will then create a service and assign that service a port to be exposed externally and direct traffic to $productName$ via the defined `port`. - -```yaml ---- -apiVersion: v1 -kind: Service -metadata: - name: ambassador -spec: - type: NodePort - ports: - - name: http - port: 8088 - targetPort: 8080 - nodePort: 30036 # Optional: Define the port you would like exposed - protocol: TCP - selector: - service: ambassador -``` - -Using a `NodePort` leaves $productName$ isolated from the host network, allowing the Kubernetes service to handle routing to $productName$ pods. You can drop-in this YAML to replace the `LoadBalancer` service in the [YAML installation guide](../yaml-install) and use `http://:/` as the host for requests. - -## Exposing $productName$ via host network - -When running $productName$ on a bare metal install of Kubernetes, you have the option to configure $productName$ pods to use the network of the host they are running on. This method allows you to bind $productName$ directly to port 80 or 443 so you won't need to identify the port in requests. - -i.e `http://:/` becomes `http:///` - -This can be configured by setting `hostNetwork: true` in the $productName$ deployment. `dnsPolicy: ClusterFirstWithHostNet` will also need to set to tell $productName$ to use *KubeDNS* when attempting to resolve mappings. - -```diff ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: ambassador -spec: - replicas: 1 - selector: - matchLabels: - service: ambassador - template: - metadata: - annotations: - sidecar.istio.io/inject: "false" - labels: - service: ambassador - app.kubernetes.io/managed-by: getambassador.io - spec: -+ hostNetwork: true -+ dnsPolicy: ClusterFirstWithHostNet - serviceAccountName: ambassador - containers: - - name: ambassador - image: docker.io/datawire/ambassador:$version$ - resources: - limits: - cpu: 1 - memory: 400Mi - requests: - cpu: 200m - memory: 100Mi - env: - - name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace - livenessProbe: - httpGet: - path: /ambassador/v0/check_alive - port: 8877 - initialDelaySeconds: 30 - periodSeconds: 3 - readinessProbe: - httpGet: - path: /ambassador/v0/check_ready - port: 8877 - initialDelaySeconds: 30 - periodSeconds: 3 - restartPolicy: Always -``` - -This configuration does not require a defined $productName$ service, so you can remove that service if you have defined one. - -**Note:** Before configuring $productName$ with this method, consider some of the functionality that is lost by bypassing the Kubernetes service including only having one $productName$ able to bind to port 8080 or 8443 per node and losing any load balancing that is typically performed by Kubernetes services. diff --git a/content/en/docs/3.4/topics/install/convert-to-v3alpha1.md b/content/en/docs/3.4/topics/install/convert-to-v3alpha1.md deleted file mode 100644 index 2d8dfb79..00000000 --- a/content/en/docs/3.4/topics/install/convert-to-v3alpha1.md +++ /dev/null @@ -1,275 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Convert Configuration to `getambassador.io/v3alpha1` - -Once your $productName$ $version$ installation is running, it is **strongly recommended** that -you convert your existing configuration resources from `getambassador.io/v2` to -`getambassador.io/v3alpha1`. - - - While it is not necessary to convert all your resources to getambassador.io/v3alpha1 - immediately, you should ultimately update them all for full functionality with $productName$ - - -In general, the best way to convert any resource is to start with `kubectl get`: using -`kubectl get -o yaml` on any `getambassador.io/v2` resource will cause $productName$ to -translate it to a `getambassador.io/v3alpha1` resource. You can then verify that the -`getambassador.io/v3alpha1` resource looks correct and re-apply it, which will convert the -stored copy to `getambassador.io/v3alpha1`. - -As you do the conversion, here are the things to bear in mind: - -## 1. `ambassador_id` must be an array, not a simple string. - -`getambassador.io/v2` allowed `ambassador_id` to be either an array of strings, or a simple -string. In `getambassador.io/v3alpha1`, only the array form is supported: instead of -`ambassador_id: "foo"`, use `ambassador_id: [ "foo" ]`. This applies to all $productName$ -resources, and is supported by all versions of Ambassador 1.X. - -## 2. You must have a `Listener` for each port on which $productName$ should listen. - - - Learn more about Listener - - -`Listener` is **mandatory**. Defining your own `Listener`(s) allows you to carefully -tailor the set of ports you actually need to use, and exactly which `Host` resources -are matched with them (see below). - -## 3. `Listener`, `Host`, and `Mapping` must be explicit about how they associate. - -You need to have `Listener`s, `Host`s, and `Mapping`s correctly associated with each other for $productName$ 2.X configuration. - -### 3.1. `Listener` and `Host` are associated through `Listener.hostBinding` - - - Learn more about Listener
- Learn more about Host - - -In a `Listener`, the `hostBinding` controls whether a given `Host` is associated with that `Listener`, as discussed in the [`Listener`](../../running/listener) documentation. -**The recommended setting is using `hostBinding.selector`** to choose only `Host`s that have a defined -Kubernetes label: - -```yaml -hostBinding: - selector: - matchLabels: - my-listener: listener-8080 -``` - -The above example shows a `Listener` configured to associate only with `Host`s that have a `my-listener: listener-8080` label. - -For migration purposes, it is possible to have a `Listener` associate with all of the `Host`s. This is not recommended for production environments, however, as it can resulting confusing behavior with large numbers of `Host`s, and it -can also result in larger Envoy configurations that slow reconfiguration. - -```yaml -hostBinding: - namespace: - from: ALL -``` - -but **this is not recommended in production**. Allowing every `Host` to associate -with every `Listener` can result in confusing behavior with large numbers of `Host`s, and it -can also result in larger Envoy configurations that slow reconfiguration. - -### 3.2. `Host` and `Mapping` are associated through `Host.mappingSelector` - - -In $productName$ 1.X, `Mapping`s were nearly always associated with every `Host`. Since this -tends to result in larger Envoy configurations that slow down reconfiguration, $productName$ 2.X -inverts this behavior: **`Host` and `Mapping` will not associate without explicit selection**. - -To have a `Mapping` associate with a `Host`, at least one of the following must hold: - -- Recommended: The `Host` must define a `mappingSelector` that matches a `label` on the `Mapping`. -- Alternately, the `Mapping` must define `hostname` that matches the `hostname` of the `Host`. - (Note that the `hostname` of both `Host` and `AmbasssadorMapping` is a DNS glob.) - -If the `Host` defines a `mappingSelector` and the `Mapping` also defines a `hostname`, both must match. - -As a migration aid: - -- A `Mapping` with a `hostname` of `"*"` will associate with any `Host` that -has no `mappingSelector`, and -- A `v3alpha1` `Mapping` will honor `host` if `hostname` is not present. - - - Learn more about Host
- Learn more about Mapping - - - - A Mapping that specifies host_regex: true is associated with  - all Hosts. This is generally far less desirable than using hostname - with a DNS glob. - - - - Support for host and host_regex will be removed before - v3alpha1 is promoted to v3. - - -## 4. Use `Host` to terminate TLS - - - Learn more about Host
- Learn more about TLSContext - - -In $productName$ 1.X, simply creating a `TLSContext` is sufficient to terminate TLS, but in -2.X you _must_ use a `Host`. The minimal setup to terminate TLS is now something like this: - -```yaml ---- -apiVersion: v1 -kind: Secret -metadata: - name: my-secret -type: kubernetes.io/tls -data: - tls.crt: base64-PEM - tls.key: base64-PEM ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: my-host -spec: - hostname: host.example.com - tlsSecret: my-secret -``` - -In the example above, TLS is terminated for `host.example.com`. A `TLSContext` is still right way to share data -about TLS configuration across `Host`s: set both `tlsSecret` and `tlsContext` in the `Host`. - -## 5. `Mapping` should use `hostname` if possible - - - Learn more about Mapping - - -The `getambassador.io/v3alpha1` `Mapping` introduces the new `hostname` element, which is always -a DNS glob. Using `hostname` instead of `host` is **strongly recommended** unless you absolutely -require regular expression matching: - -- if `host` is being used for an exact match, simply rename `host` to `hostname`. -- if `host` is being used for a regex that effects a prefix or suffix match, rename it - to `hostname` and rewrite the regex into a DNS glob, e.g. `host: .*\.example\.com` would become - `hostname: *.example.com`. - -Additionally, when `hostname` is used, the `Mapping` will be associated with a `Host` only -if `hostname` matches the hostname of the `Host`. If the `Host`'s `selector` is also set, -both the `selector` and the hostname must line up. - - - An 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. - - -## 6. `Mapping` added headers must not be simple strings - - - Learn more about Mapping - - -The `getambassador.io/v2` `Mapping` supported strings and dictionaries for `add_request_headers` and -`add_response_headers`, for example: - -```yaml -add_request_headers: - X-Add-String: bar - X-Add-Dict: - value: bar -``` - -In `getambassador.io/v2`, both `X-Add-String` and `X-Add-Dict` will be added with the value `bar`. - -The string form - shown with `X-Add-String` - is not supported in `getambassador.io/v3alpha1`. Use the -dictionary form instead (which works in both `getambassador.io/v2` and `getambassador.io/v3alpha1`). - -## 7. `Mapping` `headers` and `query_parameters` must not be `true` - - - Learn more about Mapping - - -`headers` and `query_parameters` in a `Mapping` control header matches and query-parameter matches. In -`getambassador.io/v2`, they support both strings and dictionaries, and each has a `_regex` variant. -For example: - - ```yaml - headers: - x-exact-match: foo - x-existence-match: true - headers_regex: - x-regex-match: "fo.*o" - ``` - -In this example, the `Mapping` requires the `x-exact-match` header to have the value `foo`, the -`x-regex-match` whose value starts with `fo` and ends with `o`. However, `x-existence-match` requires -simply that the `x-existence-match` header exists. - -In `getambassador.io/v3alpha1`, the `true` value for an existence match is not supported. Instead, -use `headers_regex` for the same header with value of `.*`. This is fully supported in 1.k) - -`query_parameters` and `query_parameters_regex` work exactly like `headers` and `headers_reex`. - -## 8. `Mapping` `labels` must be converted to new syntax - - - Learn more about Mapping - - -In `getambassador.io/v2`, the `labels` element in a `Mapping` supported several different types of -data. In `getambassador.io/v3alpha1`, all labels must have the same type, so labels must be converted -to the new syntax: - -| `getambassador.io/v2` | `getambassador.io/v3alpha1` | -| -------------------------------- | ----------------------------------------------------------- | -| `source_cluster` | `{ source_cluster: { key: source_cluster } }` | -| `destination_cluster` | `{ destination_cluster: { key: destination_cluster }` } | -| `remote_address` | `{ remote_address: { key: remote_address } }` | -| `{ my_key: { header: my_hdr } }` | `{ generic_key: { value: my_val } }` | -| `{ my_val }` | `{ generic_key: { value: my_val } }` | -| `{ my_key: { header: my_hdr } }` | `{ request_headers: { key: my_key, header_name: my_hdr } }` | - -You can check the [Rate Limiting Labels documentation](../../using/rate-limits#attaching-labels-to-requests) -for more examples. - -## 9. `tls` cannot be `true` in `AuthService`, `Mapping`, `RateLimitService`, and `TCPMapping` - - - Learn more about AuthService
- Learn more about Mapping
- Learn more about RateLimitService
- Learn more about TCPMapping - - -The `tls` element in `AuthService`, `Mapping`, `RateLimitService`, and `TCPMapping` controls TLS -origination. In `getambassador.io/v2`, it may be a string naming a `TLSContext` to use to determine -which client certificate is sent, or the boolean value `true` to request TLS origination with no -cluent certificate being sent. - -In `getambassador.io/v3alpha1`, only the string form is supported. To originate TLS with no client -certificate (the semantic of `tls: true`), omit the `tls` element and prefix the `service` with -`https://`. Note that `TCPMapping` in `getambassador.io/v2` does not support the `https://prefix`. - -## 10. Some `Module` settings have moved or changed - - - Learn more about Listener - - -A few settings have moved from the `Module` in 2.0. Make sure you review the following settings -and move them to their new locations if you are using them in a `Module`: - -- Configuration for the `PROXY` protocol is part of the `Listener` resource in $productName$ 2.0, -so the `use_proxy_protocol` element of the `ambassador` `Module` is no longer supported. - -- `xff_num_trusted_hops` has been removed from the `Module`, and its functionality has been moved -to the `l7Depth` setting in the `Listener` resource. - -- It is no longer possible to configure TLS using the `tls` element of the `Module`. Its -functionality is fully covered by the `TLSContext` resource. diff --git a/content/en/docs/3.4/topics/install/docker.md b/content/en/docs/3.4/topics/install/docker.md deleted file mode 100644 index e430a55c..00000000 --- a/content/en/docs/3.4/topics/install/docker.md +++ /dev/null @@ -1,73 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Run the demo with Docker - -In this Docker quickstart guide, we'll get $productName$ running locally -with a demo configuration. In the next section, we'll then walk through how to -deploy $productName$ in Kubernetes with a custom configuration. - -## 1. Running the demo configuration - -By default, $productName$ uses a demo configuration to show some of its basic features. Get it running with Docker, and expose $productName$ on port 8080: - -``` -docker run -it -p 8080:8080 --name=$productDeploymentName$ --rm docker.io/emissaryingress/emissary:$version$ --demo -``` - -## 2. $productName$'s diagnostics - -$productName$ provides live diagnostics viewable with a web browser. While this would normally not be exposed to the public network, the Docker demo publishes the diagnostics service at the following URL: - -`http://localhost:8080/ambassador/v0/diag/` - -You'll have to authenticate to view this page: use the username `admin`, -password `admin` (obviously this would be a poor choice in the real world!). -We'll talk more about authentication shortly. - -To access the Diagnostics page with authentication, use `curl http://localhost:8080/ambassador/v0/diag/ -u admin:admin` - -Some of the most important information - your $productName$ version, how recently $productName$'s configuration was updated, and how recently Envoy last reported status to $productName$ - is right at the top. The diagnostics overview can show you what it sees in your configuration map, and which Envoy objects were created based on your configuration. - -## 3. The Quote service - -Since $productName$ is a comprehensive, self-service edge stack, its primary purpose is to provide access and control to microservices for the teams that manage them. The demo is preconfigured with a mapping that connects the `/qotm/` resource to the "Quote" service -- a demo service that supplies quotations. You can try it out by opening - -`http://localhost:8080/qotm/` - -in your browser, or from the command line as - -``` -curl -L 'http://localhost:8080/qotm/?json=true' -``` - -This request will route to the `qotm` service at `demo.getambassador.io`, and return a random quote. - -You can see details of the mapping by clicking the blue `http://localhost:8080/qotm/` link at the very bottom of the `Ambassador Route Table` in the diagnostics overview. - -## 4. Authentication - -On the diagnostic overview, you can also see that $productName$ is configured to do authentication -- in the middle of the overview page, you'll see the `Ambassador Services In Use` section, and you can click the `tcp://127.0.0.1:5050` link for details on the `AuthService` configuration. This demo auth service is running inside the Docker container with $productName$ and the Quote service, and $productName$ uses it to mediate access to everything behind $productName$. - -You saw above that access to the diagnostic overview required you to authenticate as an administrator. Getting a random quote does not require authentication, but to get a specific quote, you'll have to authenticate as a demo user. To see this in action, open - -`http://localhost:8080/qotm/quote/5` - -in your browser. From the command line, you can see that: - -``` -curl -Lv 'http://localhost:8080/qotm/quote/5?json=true' -``` - -will return a 401, but - -``` -curl -Lv -u username:password 'http://localhost:8080/qotm/quote/5?json=true' -``` - -will succeed. (Note that that's literally "username" and "password" -- the demo auth service is deliberately not very secure!) - -Note that it's up to the auth service to decide what needs authentication -- teaming $productName$ with an authentication service can be as flexible or strict as you need it to be. - -## Next steps - -We've just walked through some of the core features of $productName$ in a local configuration. To see $productName$ in action on Kubernetes, check out the [Installation Guide](../). diff --git a/content/en/docs/3.4/topics/install/helm.md b/content/en/docs/3.4/topics/install/helm.md deleted file mode 100644 index 4c8a9836..00000000 --- a/content/en/docs/3.4/topics/install/helm.md +++ /dev/null @@ -1,102 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Install with Helm - - - - To migrate from $productName$ 1.X to $productName$ 2.X, see the - [$productName$ migration matrix](../migration-matrix/). This guide - **will not work** for that, due to changes to the configuration - resources used for $productName$ 2.X. - - - -[Helm](https://helm.sh) is a package manager for Kubernetes that automates the release and management of software on Kubernetes. $productName$ can be installed via a Helm chart with a few simple steps, depending on if you are deploying for the first time, upgrading $productName$ from an existing installation, or migrating from $productName$. - -## Before you begin - -The $productName$ Helm chart is hosted by Datawire and published at `https://app.getambassador.io`. - -Start by adding this repo to your helm client with the following command: - -``` -helm repo add datawire https://app.getambassador.io -helm repo update -``` - -## Install with Helm - -When you run the Helm chart, it installs $productName$. - -1. Install the $productName$ CRDs. - - Before installing $productName$ $version$ itself, you must configure your - Kubernetes cluster to support the `getambassador.io/v3alpha1` and `getambassador.io/v2` - configuration resources. This is required. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. Install the $productName$ Chart with the following command: - - ``` - helm install -n $productNamespace$ --create-namespace \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - -3. Next Steps - - $productName$ shold now be successfully installed and running, but in order to get started deploying Services and test routing to them you need to configure a few more resources. - - - [The `Listener` Resource](../../running/listener/) is required to configure which ports the $productName$ pods listen on so that they can begin responding to requests. - - [The `Mapping` Resouce](../../using/intro-mappings/) is used to configure routing requests to services in your cluster. - - [The `Host` Resource](../../running/host-crd/) configures TLS termination for enablin HTTPS communication. - - Explore how $productName$ [configures communication with clients](../../../howtos/configure-communications) - - - We strongly recommend following along with our Quickstart Guide to get started by creating a Listener, deploying a simple service to test with, and setting up a Mapping to route requests from $productName$ to the demo service. - - - - $productName$ $version$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - -For more advanced configuration and details about helm values, -[please see the helm chart.](https://artifacthub.io/packages/helm/datawire/emissary-ingress/) - -## Upgrading an existing installation - -See the [migration matrix](../migration-matrix) for instructions about upgrading -$productName$. diff --git a/content/en/docs/3.4/topics/install/index.less b/content/en/docs/3.4/topics/install/index.less deleted file mode 100644 index bc649e7c..00000000 --- a/content/en/docs/3.4/topics/install/index.less +++ /dev/null @@ -1,57 +0,0 @@ -@media (max-width: 769px) { - #index-installContainer { - flex-direction: column; - } - .index-dropdown { - width: auto; - } - .index-dropBtn { - width: 100%; - } -} - -.index-dropBtn { - background-color: #8e77ff; - color: white; - padding: 10px; - font-size: 16px; - border: none; - margin-top: -20px; -} - -.index-dropdown { - position: relative; - display: inline-block; -} - -.index-dropdownContent { - display: none; - position: absolute; - background-color: #f1f1f1; - width: 100%; - box-shadow: 0px 8px 16px 0px rgba(0, 0, 0, 0.2); - z-index: 1; -} - -.index-dropdownContent a { - color: black; - padding: 12px 16px; - text-decoration: none; - display: block; -} - -.index-dropdownContent a:hover { - background-color: #ddd; -} - -.index-dropdown:hover .index-dropdownContent { - display: block; -} - -.index-dropdown:hover .index-dropBtn { - background-color: #5f3eff; -} - -#index-installContainer { - display: flex; -} diff --git a/content/en/docs/3.4/topics/install/index.md b/content/en/docs/3.4/topics/install/index.md deleted file mode 100644 index 40fa95fd..00000000 --- a/content/en/docs/3.4/topics/install/index.md +++ /dev/null @@ -1,47 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; -import './index.less' - -# Installing $productName$ - -## 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/content/en/docs/3.4/topics/install/migrate-to-2-alternate.md b/content/en/docs/3.4/topics/install/migrate-to-2-alternate.md deleted file mode 100644 index 0b4b6743..00000000 --- a/content/en/docs/3.4/topics/install/migrate-to-2-alternate.md +++ /dev/null @@ -1,40 +0,0 @@ ---- - 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$ 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/content/en/docs/3.4/topics/install/migrate-to-3-alternate.md b/content/en/docs/3.4/topics/install/migrate-to-3-alternate.md deleted file mode 100644 index d0b791a1..00000000 --- a/content/en/docs/3.4/topics/install/migrate-to-3-alternate.md +++ /dev/null @@ -1,36 +0,0 @@ -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/content/en/docs/3.4/topics/install/migration-matrix.md b/content/en/docs/3.4/topics/install/migration-matrix.md deleted file mode 100644 index e205b660..00000000 --- a/content/en/docs/3.4/topics/install/migration-matrix.md +++ /dev/null @@ -1,46 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrading $productName$ - - - Read the instructions below before making any changes to your cluster! - - -There are currently multiple paths for upgrading $productName$, depending on what version you're currently -running, what you want to be running, and whether you installed $productName$ using [Helm](../helm) or -YAML. - -(To check out if you installed $productName$ using Helm, run `helm list --all` and see if -$productName$ is listed. If so, you installed using Helm.) - - - Read the instructions below before making any changes to your cluster! - - -## If you are currently running $AESproductName$ - -See the [instructions on updating $AESproductName$](/docs/edge-stack/$aesDocsVersion$/topics/install/migration-matrix/). - -## If you installed $OSSproductName$ using Helm - -| If you're running. | You can upgrade to | -|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------| -| $OSSproductName$ $version$ | [$AESproductName$ $aesVersion$](/docs/edge-stack/$aesDocsVersion$/topics/install/upgrade/helm/emissary-3.4/edge-stack-3.X/) | -| $OSSproductName$ 3.3.X | [$OSSproductName$ $version$](../upgrade/helm/emissary-3.3/emissary-3.X) | -| $OSSproductName$ $versionTwoX$ | [$OSSproductName$ $version$](../upgrade/helm/emissary-2.5/emissary-3.X) | -| $OSSproductName$ 2.4.X | [$OSSproductName$ $version$](../upgrade/helm/emissary-2.4/emissary-2.X) | -| $OSSproductName$ 2.0.5 | [$OSSproductName$ $versionTwoX$](../upgrade/helm/emissary-2.0/emissary-2.X) | -| $OSSproductName$ $versionOneX$ | [$OSSproductName$ $versionTwoX$](../upgrade/helm/emissary-1.14/emissary-2.X) | -| $OSSproductName$ prior to $versionOneX$ | [$OSSproductName$ $versionOneX$](../../../../1.14/topics/install/upgrading) | - -## If you installed $OSSproductName$ manually by applying YAML - -| If you're running. | You can upgrade to | -|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------| -| $OSSproductName$ $version$ | [$AESproductName$ $aesVersion$](/docs/edge-stack/$aesDocsVersion$/topics/install/upgrade/yaml/emissary-3.4/edge-stack-3.X/) | -| $OSSproductName$ 3.3.X | [$OSSproductName$ $version$](../upgrade/yaml/emissary-3.3/emissary-3.X) | -| $OSSproductName$ $versionTwoX$ | [$OSSproductName$ $version$](../upgrade/yaml/emissary-2.5/emissary-3.X) | -| $OSSproductName$ 2.4.X | [$OSSproductName$ $version$](../upgrade/yaml/emissary-2.4/emissary-2.X) | -| $OSSproductName$ 2.0.5 | [$OSSproductName$ $versionTwoX$](../upgrade/yaml/emissary-2.0/emissary-2.X) | -| $OSSproductName$ $versionOneX$ | [$OSSproductName$ $versionTwoX$](../upgrade/yaml/emissary-1.14/emissary-2.X) | -| $OSSproductName$ prior to $versionOneX$ | [$OSSproductName$ $versionOneX$](../../../../1.14/topics/install/upgrading) | diff --git a/content/en/docs/3.4/topics/install/upgrade/helm/emissary-1.14/emissary-2.X.md b/content/en/docs/3.4/topics/install/upgrade/helm/emissary-1.14/emissary-2.X.md deleted file mode 100644 index bd61fafc..00000000 --- a/content/en/docs/3.4/topics/install/upgrade/helm/emissary-1.14/emissary-2.X.md +++ /dev/null @@ -1,312 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 1.14.X (Helm) - - - This guide covers migrating from $productName$ 1.14.X to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -We're pleased to introduce $productName$ $versionTwoX$! The 2.X family introduces a number of -changes to allow $productName$ to more gracefully handle larger installations (including -multitenant or multiorganizational installations), reduce memory footprint, and improve -performance. In keeping with [SemVer](https://semver.org), $productName$ 2.X introduces -some changes that aren't backward-compatible with 1.X. These changes are detailed in -[Major Changes in $productName$ 2.X](../../../../../../about/changes-2.x/). - -## Migration Overview - - - Read the migration instructions below before making any changes to your - cluster! - - -The recommended strategy for migration is to run $productName$ 1.14 and $productName$ -$versionTwoX$ side-by-side in the same cluster. This gives $productName$ $versionTwoX$ -and $productName$ 1.14 access to all the same configuration resources, with some -important caveats: - -1. **$productName$ 1.14 will not see any `getambassador.io/v3alpha1` resources.** - - This is intentional; it provides a way to apply configuration only to - $productName$ $versionTwoX$, while not interfering with the operation of your - $productName$ 1.14 installation. - -2. **If needed, you can use labels to further isolate configurations.** - - If you need to prevent your $productName$ $versionTwoX$ installation from - seeing a particular bit of $productName$ 1.14 configuration, you can apply - a Kubernetes label to the configuration resources that should be seen by - your $productName$ $versionTwoX$ installation, then set its - `AMBASSADOR_LABEL_SELECTOR` environment variable to restrict its 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$ $versionTwoX$, then set - `AMBASSADOR_LABEL_SELECTOR=version-two=true` in its Deployment. - -3. **Be careful about label selectors on Kubernetes Services!** - - If you have services in $productName$ 1.14 that use selectors that will match - Pods from $productName$ $versionTwoX$, traffic will be erroneously split between - $productName$ 1.14 and $productName$ $versionTwoX$. The labels used by $productName$ - $versionTwoX$ include: - - ```yaml - app.kubernetes.io/name: emissary-ingress - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/part-of: emissary-ingress - app.kubernetes.io/managed-by: getambassador.io - product: aes - profile: main - ``` - -4. **Be careful to only have one $productName$ Agent running at a time.** - - The $productName$ Agent is responsible for communications between - $productName$ and Ambassador Cloud. If multiple versions of the Agent are - running simultaneously, Ambassador Cloud could see conflicting information - about your cluster. - - The best way to avoid multiple agents when installing with Helm is to use - `--set agent.enabled=false` to tell Helm not to install a new Agent with - $productName$ $versionTwoX$. Once testing is done, you can switch Agents safely. - -You can also migrate by [installing $productName$ $versionTwoX$ in a separate cluster](../../../../migrate-to-2-alternate). -This permits absolute certainty that your $productName$ 1.14 configuration will not be -affected by changes meant for $productName$ $versionTwoX$, and it eliminates concerns about -ACME, but it is more effort. - -## Side-by-Side Migration Steps - -Migration is a seven-step process: - -1. **Make sure that older configuration resources are not present.** - - $productName$ 2.X does not support `getambassador.io/v0` or `getambassador.io/v1` - resources, and Kubernetes will not permit removing support for CRD versions that are - still in use for stored resources. To verify that no resources older than - `getambassador.io/v2` are active, run - - ``` - kubectl get crds -o 'go-template={{range .items}}{{.metadata.name}}={{.status.storedVersions}}{{"\n"}}{{end}}' | fgrep getambassador.io - ``` - - If `v1` is present in the output, **do not begin migration.** The old resources must be - converted to `getambassador.io/v2` and the `storedVersion` information in the cluster - must be updated. If necessary, contact Ambassador Labs on [Slack](http://a8r.io/slack) - for more information. - -2. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you must configure your - Kubernetes cluster to support its new `getambassador.io/v3alpha1` configuration - resources. Note that `getambassador.io/v2` resources are still supported, but **you - must install support for `getambassador.io/v3alpha1`** to run $productName$ $versionTwoX$, - even if you intend to continue using only `getambassador.io/v2` resources for some - time. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -3. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, you need to install $productName$ $versionTwoX$ itself - **in the same namespace as your existing $productName$ 1.14 installation**. It's important - to use the same namespace so that the two installations can see the same secrets, etc. - - Start by making sure that your `emissary` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Typically, $productName$ 1.14 was installed in the `ambassador` namespace. If you installed - $productName$ 1.14 in a different namespace, change the namespace in the commands below. - - - If you do not need to set `AMBASSADOR_LABEL_SELECTOR`: - - ```bash - helm install -n ambassador \ - --set agent.enabled=false \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - - - If you do need to set `AMBASSADOR_LABEL_SELECTOR`, use `--set`, for example: - - ```bash - helm install -n ambassador \ - --set agent.enabled=false \ - --set env.AMBASSADOR_LABEL_SELECTOR="version-two=true" \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 2.X. - Do not use the ambassador Helm chart. - - - - $productName$ $versionTwoX$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - -4. **Install `Listener`s and `Host`s as needed.** - - An important difference between $productName$ 1.14 and $productName$ $versionTwoX$ is the - new **mandatory** `Listener` CRD. Also, when running both installations side by side, - you will need to make sure that a `Host` is present for the new $productName$ $versionTwoX$ - Service. For example: - - ```bash - kubectl apply -f - < - Kubernetes will not allow you to have a 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.
-
- If you find that your $productName$ $versionTwoX$ installation and your $productName$ 1.14 - installation absolutely must have resources that are only seen by one version or the - other way, see overview section 2, "If needed, you can use labels to further isolate configurations". - - - **If you find that you need to roll back**, just reinstall your 1.14 CRDs and delete your - installation of $productName$ $versionTwoX$. - -6. **When ready, switch over to $productName$ $versionTwoX$.** - - You can run $productName$ 1.14 and $productName$ $versionTwoX$ side-by-side as long as you care - to. However, taking full advantage of $productName$ 2.X's capabilities **requires** - [updating your configuration to use `getambassador.io/v3alpha1` configuration resources](../../../../convert-to-v3alpha1), - since some useful features in $productName$ $versionTwoX$ are only available using - `getambassador.io/v3alpha1` resources. - - When you're ready to have $productName$ $versionTwoX$ handle traffic on its own, switch - your original $productName$ 1.14 Service to point to $productName$ $versionTwoX$. Use - `kubectl edit service ambassador` and change the `selectors` to: - - ``` - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/name: emissary-ingress - profile: main - ``` - - Repeat using `kubectl edit service ambassador-admin` for the `ambassador-admin` - Service. - -7. **Finally, install the $productName$ $versionTwoX$ Ambassador Agent.** - - First, scale the 1.14 agent to 0: - - ``` - kubectl scale -n ambassador deployment/ambassador-agent --replicas=0 - ``` - - Once that's done, install the new Agent. **Note that if you needed to set - `AMBASSADOR_LABEL_SELECTOR`, you must add that to this `helm upgrade` command.** - - ```bash - helm upgrade -n ambassador \ - --set agent.enabled=true \ - $productHelmName$ datawire/$productHelmName$ \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - -Congratulations! At this point, $productName$ $versionTwoX$ is fully running and it's safe to remove the `ambassador` and `ambassador-agent` Deployments: - -``` -kubectl delete deployment/ambassador deployment/ambassador-agent -``` - -Once $productName$ 1.14 is no longer running, you may [convert](../../../../convert-to-v3alpha1) -any remaining `getambassador.io/v2` resources to `getambassador.io/v3alpha1`. -You may also want to redirect DNS to the `edge-stack` Service and remove the -`ambassador` Service. diff --git a/content/en/docs/3.4/topics/install/upgrade/helm/emissary-2.0/emissary-2.X.md b/content/en/docs/3.4/topics/install/upgrade/helm/emissary-2.0/emissary-2.X.md deleted file mode 100644 index c0a392f1..00000000 --- a/content/en/docs/3.4/topics/install/upgrade/helm/emissary-2.0/emissary-2.X.md +++ /dev/null @@ -1,75 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.0.5 (Helm) - - - This guide covers migrating from $productName$ 2.0.5 to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster; Helm will not do this for you. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, use Helm to install $productName$ $versionTwoX$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 2.X. - Do not use the ambassador Helm chart. - diff --git a/content/en/docs/3.4/topics/install/upgrade/helm/emissary-2.4/emissary-2.X.md b/content/en/docs/3.4/topics/install/upgrade/helm/emissary-2.4/emissary-2.X.md deleted file mode 100644 index 3e44b511..00000000 --- a/content/en/docs/3.4/topics/install/upgrade/helm/emissary-2.4/emissary-2.X.md +++ /dev/null @@ -1,75 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.4.Z (Helm) - - - This guide covers migrating from $productName$ 2.4.Z to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster; Helm will not do this for you. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, use Helm to install $productName$ $versionTwoX$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 2.X. - Do not use the ambassador Helm chart. - diff --git a/content/en/docs/3.4/topics/install/upgrade/helm/emissary-2.5/emissary-3.X.md b/content/en/docs/3.4/topics/install/upgrade/helm/emissary-2.5/emissary-3.X.md deleted file mode 100644 index d8439c5a..00000000 --- a/content/en/docs/3.4/topics/install/upgrade/helm/emissary-2.5/emissary-3.X.md +++ /dev/null @@ -1,153 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.5.Z (Helm) - - - This guide covers migrating from $productName$ 2.5.Z to $productName$ $version$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - - - Make sure that you have updated any 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$. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -$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. - -### Resources to check before migrating to $version$. - -$productName$ 3.X has been upgraded from Envoy 1.17.X to Envoy 1.22 which removed support for the Envoy V2 Transport Protocol. This means all `AuthService`, `RatelimitService`, and `LogServices` must be updated to use the V3 Protocol. Additionally support for some of the runtime bootstrap flags has been removed. - -You can refer to the [Major changes in $productName$ 3.x](../../../../../../about/changes-3.y/) guide for an overview of the changes. - -1. $productName$ 3.2 fixed a bug with `Host.spec.selector\mappingSelector` and `Listener.spec.selector` not being properly enforced. - In previous versions, if only a single label from the selector was present on the resource then they would be associated. Additionally, when associating `Hosts` with `Mappings`, if the `Mapping` configured a `hostname` that matched the `hostname` of the `Host` then they would be associated regardless of the configuration of the `selector\mappingSelector` on the `Host`. - - Before upgrading, review your Ambassador resources, and if you make use of the selectors, ensure that every other resource you want it to be associated with contains all the required labels. - - The environment variable `DISABLE_STRICT_LABEL_SELECTORS` can be set to `"true"` on the $productName$ deployment to revert to the - old incorrect behavior to help prevent any configuration issues after upgrading in the event that not all manifests making use of the selectors have been corrected yet. - - For more information on `DISABLE_STRICT_LABEL_SELECTORS` see the [Environment Variables page](../../../../../running/environment). - -2. Check Transport Protocol usage on all resources before migrating. - - The `AuthService`, `RatelimitService`, and `LogServices` 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. - - `protocol_version` should be updated to `v3` for all of the above resources while still running $productName$ $versionTwoX$. As of version `2.3.z`+, support for `protocol_version` `v2` and `v3` is supported in order to allow migration from `protocol_version` `v2` to `v3` before upgrading to $productName$ $version$ where support for `v2` is removed. - - Upgrading any application code for your own implementations of these services is very straightforward. - - The following imports simply need to be updated to switch from Envoy's Transport Protocol `v2` to `v3`, and then the configuration for these resources can be updated to add the `protocl_version: "v3"` when the updated service is deployed. - - `v2` Imports: - ```golang - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" - ``` - - `v3` Imports: - ```golang - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" - ``` - -3. Check removed runtime changes - - ```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, - - # Developers 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, - ``` - -4. Support for LightStep tracing driver removed - - - As of $productName$ 3.4.Z, the LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read before upgrading. - - -$productName$ 3.4 is based on Envoy 1.24.1 which removed support for the `LightStep` tracing driver. The team at LightStep and the maintainers of Envoy-Proxy recommend that users instead leverage the OpenTelemetry Collector to send tracing information to LightStep. We have written a guide which can be found here Distributed Tracing with OpenTelemetry and Lightstep that outlines how to set this up. **It is important that you follow this upgrade path prior to upgrading or you will drop tracing data.** - -## Migration Steps - -Migration is a two-step process: - -1. **Install new CRDs.** - - After reviewing the changes in 3.x and confirming that you are ready to upgrade, the process is the same as upgrading minor versions - in previous version of $productName$ and does not require the complex migration steps that the migration from 1.x tto 2.x required. - - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $version$.** - - After installing the new CRDs, use Helm to install $productName$ $version$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 3.Y. - diff --git a/content/en/docs/3.4/topics/install/upgrade/helm/emissary-3.3/emissary-3.X.md b/content/en/docs/3.4/topics/install/upgrade/helm/emissary-3.3/emissary-3.X.md deleted file mode 100644 index caae4111..00000000 --- a/content/en/docs/3.4/topics/install/upgrade/helm/emissary-3.3/emissary-3.X.md +++ /dev/null @@ -1,87 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 3.3.Z (Helm) - - - This guide covers migrating from $productName$ 3.3.Z to $productName$ $version$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -### Resources to check before migrating to $version$. - - - As of $productName$ 3.4.Z, the LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read below before upgrading. - - -$productName$ 3.4 has been upgraded from Envoy 1.23 to Envoy 1.24.1 which removed support for the `LightStep` tracing driver. The team at LightStep and the maintainers of Envoy-Proxy recommend that users instead leverage the OpenTelemetry Collector to send tracing information to LightStep. We have written a guide which can be found here Distributed Tracing with OpenTelemetry and Lightstep that outlines how to set this up. **It is important that you follow this upgrade path prior to upgrading or you will drop tracing data.** - -## Migration Steps - -Migration is a two-step process: - -1. **Install new CRDs.** - - After reviewing the changes in 3.x and confirming that you are ready to upgrade, the process is the same as upgrading minor versions - in previous version of $productName$ and does not require the complex migration steps that the migration from 1.x tto 2.x required. - - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $version$.** - - After installing the new CRDs, use Helm to install $productName$ $version$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 3.Y. - diff --git a/content/en/docs/3.4/topics/install/upgrade/yaml/emissary-1.14/emissary-2.X.md b/content/en/docs/3.4/topics/install/upgrade/yaml/emissary-1.14/emissary-2.X.md deleted file mode 100644 index eb1dcf6c..00000000 --- a/content/en/docs/3.4/topics/install/upgrade/yaml/emissary-1.14/emissary-2.X.md +++ /dev/null @@ -1,282 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 1.14.X (YAML) - - - This guide covers migrating from $productName$ 1.14.X to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -We're pleased to introduce $productName$ $versionTwoX$! The 2.X family introduces a number of -changes to allow $productName$ to more gracefully handle larger installations (including -multitenant or multiorganizational installations), reduce memory footprint, and improve -performance. In keeping with [SemVer](https://semver.org), $productName$ 2.X introduces -some changes that aren't backward-compatible with 1.X. These changes are detailed in -[Major Changes in $productName$ 2.X](../../../../../../about/changes-2.x/). - -## Migration Overview - - - Read the migration instructions below before making any changes to your - cluster! - - -The recommended strategy for migration is to run $productName$ 1.14 and $productName$ -$versionTwoX$ side-by-side in the same cluster. This gives $productName$ $versionTwoX$ -and $productName$ 1.14 access to all the same configuration resources, with some -important caveats: - -1. **$productName$ 1.14 will not see any `getambassador.io/v3alpha1` resources.** - - This is intentional; it provides a way to apply configuration only to - $productName$ $versionTwoX$, while not interfering with the operation of your - $productName$ 1.14 installation. - -2. **If needed, you can use labels to further isolate configurations.** - - If you need to prevent your $productName$ $versionTwoX$ installation from - seeing a particular bit of $productName$ 1.14 configuration, you can apply - a Kubernetes label to the configuration resources that should be seen by - your $productName$ $versionTwoX$ installation, then set its - `AMBASSADOR_LABEL_SELECTOR` environment variable to restrict its 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$ $versionTwoX$, then set - `AMBASSADOR_LABEL_SELECTOR=version-two=true` in its Deployment. - -3. **Be careful about label selectors on Kubernetes Services!** - - If you have services in $productName$ 1.14 that use selectors that will match - Pods from $productName$ $versionTwoX$, traffic will be erroneously split between - $productName$ 1.14 and $productName$ $versionTwoX$. The labels used by $productName$ - $versionTwoX$ include: - - ```yaml - app.kubernetes.io/name: emissary-ingress - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/part-of: emissary-ingress - app.kubernetes.io/managed-by: getambassador.io - product: aes - profile: main - ``` - -4. **Be careful to only have one $productName$ Agent running at a time.** - - The $productName$ Agent is responsible for communications between - $productName$ and Ambassador Cloud. If multiple versions of the Agent are - running simultaneously, Ambassador Cloud could see conflicting information - about your cluster. - - The migration YAML used below to install $productName$ $versionTwoX$ will not - install a duplicate agent. If you are building your own YAML, make sure not - to include a duplicate agent. - -You can also migrate by [installing $productName$ $versionTwoX$ in a separate cluster](../../../../migrate-to-2-alternate). -This permits absolute certainty that your $productName$ 1.14 configuration will not be -affected by changes meant for $productName$ $versionTwoX$, and it eliminates concerns about -ACME, but it is more effort. - -## Side-by-Side Migration Steps - -Migration is a seven-step process: - -1. **Make sure that older configuration resources are not present.** - - $productName$ 2.X does not support `getambassador.io/v0` or `getambassador.io/v1` - resources, and Kubernetes will not permit removing support for CRD versions that are - still in use for stored resources. To verify that no resources older than - `getambassador.io/v2` are active, run - - ``` - kubectl get crds -o 'go-template={{range .items}}{{.metadata.name}}={{.status.storedVersions}}{{"\n"}}{{end}}' | fgrep getambassador.io - ``` - - If `v1` is present in the output, **do not begin migration.** The old resources must be - converted to `getambassador.io/v2` and the `storedVersion` information in the cluster - must be updated. If necessary, contact Ambassador Labs on [Slack](http://a8r.io/slack) - for more information. - -2. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you must configure your - Kubernetes cluster to support its new `getambassador.io/v3alpha1` configuration - resources. Note that `getambassador.io/v2` resources are still supported, but **you - must install support for `getambassador.io/v3alpha1`** to run $productName$ $versionTwoX$, - even if you intend to continue using only `getambassador.io/v2` resources for some - time. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -3. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, you need to install $productName$ $versionTwoX$ itself - **in the same namespace as your existing $productName$ 1.14 installation**. It's important - to use the same namespace so that the two installations can see the same secrets, etc. - - We publish two manifests for different namespaces. Use only the one that - matches the namespace into which you installed $productName$ 1.14: - - - [`emissary-emissaryns.yaml`] for the `emissary` namespace; or - - [`emissary-defaultns.yaml`] for the `default` namespace. - - If you installed $productName$ 1.14 into some other namespace, you'll need to - download one of the files and edit it to match your namespace. - - [`emissary-emissaryns.yaml`]: https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-emissaryns.yaml - [`emissary-defaultns.yaml`]: https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-defaultns.yaml - - **If you need to set `AMBASSADOR_LABEL_SELECTOR`**, you'll need to download - your chosen file and and edit it to do so. - - Assuming that you're using the `default` namespace: - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-defaultns.yaml && \ - kubectl rollout status -n default deployment/edge-stack -w - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - -4. **Install `Listener`s and `Host`s as needed.** - - An important difference between $productName$ 1.14 and $productName$ $versionTwoX$ is the - new **mandatory** `Listener` CRD. Also, when running both installations side by side, - you will need to make sure that a `Host` is present for the new $productName$ $versionTwoX$ - Service. For example: - - ```bash - kubectl apply -f - < - Kubernetes will not allow you to have a 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.
-
- If you find that your $productName$ $versionTwoX$ installation and your $productName$ 1.14 - installation absolutely must have resources that are only seen by one version or the - other way, see overview section 2, "If needed, you can use labels to further isolate configurations". - - - **If you find that you need to roll back**, just reinstall your 1.14 CRDs and delete your - installation of $productName$ $versionTwoX$. - -6. **When ready, switch over to $productName$ $versionTwoX$.** - - You can run $productName$ 1.14 and $productName$ $versionTwoX$ side-by-side as long as you care - to. However, taking full advantage of $productName$ 2.X's capabilities **requires** - [updating your configuration to use `getambassador.io/v3alpha1` configuration resources](../../../../convert-to-v3alpha1), - since some useful features in $productName$ $versionTwoX$ are only available using - `getambassador.io/v3alpha1` resources. - - When you're ready to have $productName$ $versionTwoX$ handle traffic on its own, switch - your original $productName$ 1.14 Service to point to $productName$ $versionTwoX$. Use - `kubectl edit service ambassador` and change the `selectors` to: - - ``` - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/name: emissary-ingress - profile: main - ``` - - Repeat using `kubectl edit service ambassador-admin` for the `ambassador-admin` - Service. - - -Congratulations! At this point, $productName$ $versionTwoX$ is fully running and it's safe to remove the `ambassador` and `ambassador-agent` Deployments: - -``` -kubectl delete deployment/ambassador deployment/ambassador-agent -``` - -Once $productName$ 1.14 is no longer running, you may [convert](../../../../convert-to-v3alpha1) -any remaining `getambassador.io/v2` resources to `getambassador.io/v3alpha1`. -You may also want to redirect DNS to the `edge-stack` Service and remove the -`ambassador` Service. diff --git a/content/en/docs/3.4/topics/install/upgrade/yaml/emissary-2.0/emissary-2.X.md b/content/en/docs/3.4/topics/install/upgrade/yaml/emissary-2.0/emissary-2.X.md deleted file mode 100644 index b16d046f..00000000 --- a/content/en/docs/3.4/topics/install/upgrade/yaml/emissary-2.0/emissary-2.X.md +++ /dev/null @@ -1,65 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.0.5 (YAML) - - - This guide covers migrating from $productName$ 2.0.5 to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, upgrade $productName$ $versionTwoX$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/3.4/topics/install/upgrade/yaml/emissary-2.4/emissary-2.X.md b/content/en/docs/3.4/topics/install/upgrade/yaml/emissary-2.4/emissary-2.X.md deleted file mode 100644 index ec8b6a70..00000000 --- a/content/en/docs/3.4/topics/install/upgrade/yaml/emissary-2.4/emissary-2.X.md +++ /dev/null @@ -1,67 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.4.Z (YAML) - - - This guide covers migrating from $productName$ 2.4.Z to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -## Migration Steps - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, upgrade $productName$ $versionTwoX$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/3.4/topics/install/upgrade/yaml/emissary-2.5/emissary-3.X.md b/content/en/docs/3.4/topics/install/upgrade/yaml/emissary-2.5/emissary-3.X.md deleted file mode 100644 index ea3b7bc9..00000000 --- a/content/en/docs/3.4/topics/install/upgrade/yaml/emissary-2.5/emissary-3.X.md +++ /dev/null @@ -1,144 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.5.Z (YAML) - - - This guide covers migrating from $productName$ 2.5.Z to $productName$ $version$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - - - Make sure that you have updated any 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$. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading -between versions is straightforward. - -$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. - -### Resources to check before migrating to $version$. - -$productName$ 3.X has been upgraded from Envoy 1.17.X to Envoy 1.22 which removed support for the Envoy V2 Transport Protocol. This means all `AuthService`, `RatelimitService`, and `LogServices` must be updated to use the V3 Protocol. Additionally support for some of the runtime bootstrap flags has been removed. - -You can refer to the [Major changes in $productName$ 3.x](../../../../../../about/changes-3.y/) guide for an overview of the changes. - -1. $productName$ 3.2 fixed a bug with `Host.spec.selector\mappingSelector` and `Listener.spec.selector` not being properly enforced. - In previous versions, if only a single label from the selector was present on the resource then they would be associated. Additionally, when associating `Hosts` with `Mappings`, if the `Mapping` configured a `hostname` that matched the `hostname` of the `Host` then they would be associated regardless of the configuration of the `selector\mappingSelector` on the `Host`. - - Before upgrading, review your Ambassador resources, and if you make use of the selectors, ensure that every other resource you want it to be associated with contains all the required labels. - - The environment variable `DISABLE_STRICT_LABEL_SELECTORS` can be set to `"true"` on the $productName$ deployment to revert to the - old incorrect behavior to help prevent any configuration issues after upgrading in the event that not all manifests making use of the selectors have been corrected yet. - - For more information on `DISABLE_STRICT_LABEL_SELECTORS` see the [Environment Variables page](../../../../../running/environment#disable_strict_label_selectors). - -2. Check Transport Protocol usage on all resources before migrating. - - The `AuthService`, `RatelimitService`, and `LogServices` 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. - - `protocol_version` should be updated to `v3` for all of the above resources while still running $productName$ $versionTwoX$. As of version `2.3.z`+, support for `protocol_version` `v2` and `v3` is supported in order to allow migration from `protocol_version` `v2` to `v3` before upgrading to $productName$ $version$ where support for `v2` is removed. - - Upgrading any application code for your own implementations of these services is very straightforward. - - The following imports simply need to be updated to switch from Envoy's Transport Protocol `v2` to `v3`, and then the configuration for these resources can be updated to add the `protocl_version: "v3"` when the updated service is deployed. - - `v2` Imports: - ```golang - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" - ``` - - `v3` Imports: - ```golang - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" - ``` - -3. Check removed runtime changes - - ```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, - - # Developers 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, - ``` - -4. Support for LightStep tracing driver removed - - - As of $productName$ 3.4.Z, the LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read before upgrading. - - -$productName$ 3.4 is based on Envoy 1.24.1 which removed support for the `LightStep` tracing driver. The team at LightStep and the maintainers of Envoy-Proxy recommend that users instead leverage the OpenTelemetry Collector to send tracing information to LightStep. We have written a guide which can be found here Distributed Tracing with OpenTelemetry and Lightstep that outlines how to set this up. **It is important that you follow this upgrade path prior to upgrading or you will drop tracing data.** - -## Migration Steps - -Migration is a two-step process: - -1. **Install new CRDs.** - - After reviewing the changes in 3.x and confirming that you are ready to upgrade, the process is the same as upgrading minor versions - in previous version of $productName$ and does not require the complex migration steps that the migration from 1.x tto 2.x required. - - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $version$.** - - After installing the new CRDs, upgrade $productName$ $version$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/3.4/topics/install/upgrade/yaml/emissary-3.3/emissary-3.X.md b/content/en/docs/3.4/topics/install/upgrade/yaml/emissary-3.3/emissary-3.X.md deleted file mode 100644 index 2488ab18..00000000 --- a/content/en/docs/3.4/topics/install/upgrade/yaml/emissary-3.3/emissary-3.X.md +++ /dev/null @@ -1,75 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 3.3.Z (YAML) - - - This guide covers migrating from $productName$ 3.3.Z to $productName$ $version$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading -between versions is straightforward. - -### Resources to check before migrating to $version$. - - - As of $productName$ 3.4.Z, the LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read below before upgrading. - - -$productName$ 3.4 has been upgraded from Envoy 1.23 to Envoy 1.24.1 which removed support for the `LightStep` tracing driver. The team at LightStep and the maintainers of Envoy-Proxy recommend that users instead leverage the OpenTelemetry Collector to send tracing information to LightStep. We have written a guide which can be found here Distributed Tracing with OpenTelemetry and Lightstep that outlines how to set this up. **It is important that you follow this upgrade path prior to upgrading or you will drop tracing data.** - -## Migration Steps - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $version$.** - - After installing the new CRDs, upgrade $productName$ $version$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/3.4/topics/install/yaml-install.md b/content/en/docs/3.4/topics/install/yaml-install.md deleted file mode 100644 index b28e6265..00000000 --- a/content/en/docs/3.4/topics/install/yaml-install.md +++ /dev/null @@ -1,87 +0,0 @@ ---- - description: In this guide, we'll walk through the process of deploying $productName$ in Kubernetes for ingress routing. ---- - -import Alert from '@material-ui/lab/Alert'; - -# Install manually - - - - To migrate from $productName$ 1.X to $productName$ 2.X, see the - [$productName$ migration matrix](../migration-matrix/). This guide - **will not work** for that, due to changes to the configuration - resources used for $productName$ 2.X. - - - -In this guide, we'll walk you through installing $productName$ in your Kubernetes cluster. - -The manual install process does not allow for as much control over configuration -as the [Helm install method](../helm), so if you need more control over your $productName$ -installation, it is recommended that you use helm. - -## Before you begin - -$productName$ is designed to run in Kubernetes for production. The most essential requirements are: - -* Kubernetes 1.11 or later -* The `kubectl` command-line tool - -## Install with YAML - -$productName$ is typically deployed to Kubernetes from the command line. If you don't have Kubernetes, you should use our [Docker](../docker) image to deploy $productName$ locally. - -1. In your terminal, run the following command: - - ``` - kubectl create namespace $productNamespace$ || true - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml && \ - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-emissaryns.yaml && \ - kubectl -n $productNamespace$ wait --for condition=available --timeout=90s deploy $productDeploymentName$ - ``` - - - $productName$ $version$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. Determine the IP address or hostname of your cluster by running the following command: - - ``` - kubectl get -n $productNamespace$ service $productDeploymentName$ -o "go-template={{range .status.loadBalancer.ingress}}{{or .ip .hostname}}{{end}}" - ``` - - Your load balancer may take several minutes to provision your IP address. Repeat the provided command until you get an IP address. - -3. Next Steps - - $productName$ shold now be successfully installed and running, but in order to get started deploying Services and test routing to them you need to configure a few more resources. - - - [The `Listener` Resource](../../running/listener/) is required to configure which ports the $productName$ pods listen on so that they can begin responding to requests. - - [The `Mapping` Resouce](../../using/intro-mappings/) is used to configure routing requests to services in your cluster. - - [The `Host` Resource](../../running/host-crd/) configures TLS termination for enablin HTTPS communication. - - Explore how $productName$ [configures communication with clients](../../../howtos/configure-communications) - - - We strongly recommend following along with our Quickstart Guide to get started by creating a Listener, deploying a simple service to test with, and setting up a Mapping to route requests from $productName$ to the demo service. - - -## Upgrading an existing installation - -See the [migration matrix](../migration-matrix) for instructions about upgrading -$productName$. diff --git a/content/en/docs/3.4/topics/running/ambassador-deployment.md b/content/en/docs/3.4/topics/running/ambassador-deployment.md deleted file mode 100644 index d870f32c..00000000 --- a/content/en/docs/3.4/topics/running/ambassador-deployment.md +++ /dev/null @@ -1,21 +0,0 @@ -# Deployment architecture - -$productName$ can be deployed in a variety of configurations. The specific configuration depends on your data center. - -## Public cloud - -If you're using a public cloud provider such as Amazon, Azure, or Google, $productName$ can be deployed directly to a Kubernetes cluster running in the data center. Traffic is routed to $productName$ via a cloud-managed load balancer such as an Amazon Elastic Load Balancer or Google Cloud Load Balancer. Typically, this load balancer is transparently managed by Kubernetes in the form of the `LoadBalancer` service type. $productName$ then routes traffic to your services running in Kubernetes. - -## On-Premise data center - -In an on-premise data center, $productName$ is deployed on the Kubernetes cluster. Instead of exposing it via the `LoadBalancer` service type, $productName$ is exposed as a `NodePort`. Traffic is sent to a specific port on any of the nodes in the cluster, which route the traffic to $productName$, which then routes the traffic to your services running in Kubernetes. You'll also need to deploy a separate load balancer to route traffic from your core routers to $productName$. [MetalLB](https://metallb.universe.tf/) is an open-source external load balancer for Kubernetes designed for this problem. Other options are traditional TCP load balancers such as F5 or Citrix Netscaler. - -## Hybrid data center - -Many data centers include services that are running outside of Kubernetes on virtual machines. For $productName$ to route to services both inside and outside of Kubernetes, it needs the real-time network location of all services. This problem is known as "[service discovery](https://www.datawire.io/guide/traffic/service-discovery-microservices/)" and $productName$ supports using [Consul](https://www.consul.io). Services in your data center register themselves with Consul, and $productName$ uses Consul-supplied data to dynamically route requests to available services. - -## Hybrid on-premise data center - -The diagram below details a common network architecture for a hybrid on-premise data center. Traffic flows from core routers to MetalLB, which routes to $productName$ running in Kubernetes. $productName$ routes traffic to individual services running on both Kubernetes and VMs. Consul tracks the real-time network location of the services, which $productName$ uses to route to the given services. - -![Architecture](../../images/consul-ambassador.png) diff --git a/content/en/docs/3.4/topics/running/ambassador-with-aws.md b/content/en/docs/3.4/topics/running/ambassador-with-aws.md deleted file mode 100644 index b321543a..00000000 --- a/content/en/docs/3.4/topics/running/ambassador-with-aws.md +++ /dev/null @@ -1,364 +0,0 @@ -# $productName$ with AWS - -$productName$ is a platform agnostic Kubernetes API gateway. It will run in any distribution of Kubernetes whether it is managed by a cloud provider or on homegrown bare-metal servers. - -This document serves as a reference for different configuration options available when running Kubernetes in AWS. See [Installing $productName$](../../install) for the various installation methods available. - -## Recommended configuration - -There are lot of configuration options available to you when running $productName$ in AWS. While you should read this entire document to understand what is best for you, the following is the recommended configuration when running $productName$ in AWS: - -It is recommended to terminate TLS at $productName$ so you can take advantage of all the TLS configuration options available in $productName$ including setting the allowed TLS versions, setting `alpn_protocol` options, enforcing HTTP -> HTTPS redirection, and [automatic certificate management](../host-crd) in the $productName$. - -When terminating TLS at $productName$, you should deploy a L4 [Network Load Balancer (NLB)](#network-load-balancer-nlb) with the proxy protocol enabled to get the best performance out of your load balancer while still preserving the client IP address. - -The following `Service` should be configured to deploy an NLB with cross zone load balancing enabled (see [NLB notes](#network-load-balancer-nlb) for caveat on the cross-zone-load-balancing annotation). You will need to configure the proxy protocol in the NLB manually in the AWS Console. - -```yaml -apiVersion: v1 -kind: Service -metadata: - name: ambassador - namespace: ambassador - annotations: - service.beta.kubernetes.io/aws-load-balancer-type: "nlb" - service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: "true" -spec: - type: LoadBalancer - ports: - - name: HTTP - port: 80 - targetPort: 8080 - - name: HTTPS - port: 443 - targetPort: 8443 - selector: - service: ambassador -``` - - After deploying the `Service` above and manually enabling the proxy protocol you will need to deploy the following [Ambassador `Module`](../ambassador) to tell $productName$ to use the proxy protocol and then restart $productName$ for the configuration to take effect. - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - use_proxy_proto: true - ``` - - $productName$ will now expect traffic from the load balancer to be wrapped with the proxy protocol so it can read the client IP address. - -## AWS load balancer notes - -AWS provides three types of load balancers: - -### "Classic" Elastic Load Balancer (ELB) - -The ELB is the first generation AWS Elastic Load Balancer. It is the default type of load balancer ensured by a `type: LoadBalancer` `Service` and routes directly to individual EC2 instances. It can be configured to run at layer 4 or layer 7 of the OSI model. See [What is a Classic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/introduction.html) for more details. - -* Ensured by default for a `type: LoadBalancer` `Service` -* Layer 4: TCP, TCP/SSL - * Protocol support - * HTTP(S) - * Websockets - * HTTP/2 - * Connection based load balancing - * Cannot modify the request -* Layer 7: HTTP, HTTPS - * Protocol support - * HTTP(S) - * Request based load balancing - * Can modify the request (append to `X-Forwarded-*` headers) -* Can perform TLS termination - -**Notes:** -- While it has been superseded by the `Network Load Balancer` and `Application Load Balancer` the ELB offers the simplest way of provisioning an L4 or L7 load balancer in Kubernetes. -- All of the [load balancer annotations](#load-balancer-annotations) are respected by the ELB. -- If using the ELB for TLS termination, it is recommended to run in L7 mode so it can modify `X-Forwarded-Proto` correctly. - -### Network Load Balancer (NLB) - -The NLB is a second generation AWS Elastic Load Balancer. It can be ensure by a `type: LoadBalancer` `Service` using an annotation. It can only run at layer 4 of the OSI model and load balances based on connection allowing it to handle millions of requests per second. See [What is a Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/introduction.html) for more details. - -* Can be ensured by a `type: LoadBalancer` `Service` -* Layer 4: TCP, TCP/SSL - * Protocol support - * HTTP(S) - * Websockets - * HTTP/2 - * Connection based load balacing - * Cannot modify the request -* Can perform TLS termination - -**Notes:** -- The NLB is the most efficient load balancer capable of handling millions of requests per second. It is recommended for streaming connections since it will maintain the connection stream between the client and $productName$. -- Most of the [load balancer annotations](#load-balancer-annotations) are respected by the NLB. You will need to manually configure the proxy protocol and take an extra step to enable cross zone load balancing. -- Since it operates at L4 and cannot modify the request, you will need to tell $productName$ if it is terminating TLS or not (see [TLS termination](#tls-termination) notes below). - -### Application Load Balancer (ALB) - -The ALB is a second generation AWS Elastic Load Balancer. It cannot be ensured by a `type: LoadBalancer` `Service` and must be deployed and configured manually. It can only run at layer 7 of the OSI model and load balances based on request information allowing it to perform fine-grained routing to applications. See [What is a Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/introduction.html) for more details. - -* Cannot be configured by a `type: LoadBalancer` `Service` -* Layer 7: HTTP, HTTPS - * Protocol support - * HTTP(S) - * Request based load balancing - * Can modify the request (append to `X-Forwarded-*` headers) -* Can perform TLS termination - -**Notes:** - -- The ALB can perform routing based on the path, headers, host, etc.. Since $productName$ performs this kind of routing in your cluster, unless you are using the same load balancer to route to services outside of Kubernetes, the overhead of provisioning an ALB is often not worth the benefits. -- If you would like to use an ALB, you will need to expose $productName$ with a `type: NodePort` service and manually configure the ALB to forward to the correct ports. -- None of the [load balancer annotations](#load-balancer-annotations) are respected by the ALB. You will need to manually configure all options. -- The ALB will properly set the `X-Forward-Proto` header if terminating TLS. See (see [TLS termination](#tls-termination) notes below). - -## Load balancer annotations - -Kubernetes on AWS exposes a mechanism to request certain load balancer configurations by annotating the `type: LoadBalancer` `Service`. The most complete set and explanations of these annotations can be found in this [Kubernetes document](https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer). This document will go over the subset that is most relevant when deploying $productName$. - -- `service.beta.kubernetes.io/aws-load-balancer-ssl-cert`: - - Configures the load balancer to use a valid certificate ARN to terminate TLS at the Load Balancer. - - Traffic from the client into the load balancer is encrypted but, since TLS is being terminated at the load balancer, traffic from the load balancer to $productName$ will be cleartext. You will need to configure $productName$ differently depending on whether the load balancer is running in L4 or L7 (see [TLS termination](#tls-termination) notes below). - -- `service.beta.kubernetes.io/aws-load-balancer-ssl-ports`: - - Configures which port the load balancer will be listening for SSL traffic on. Defaults to `"*"`. - - If you want to enable cleartext redirection, make sure to set this to `"443"` so traffic on port 80 will come in over cleartext. - -- `service.beta.kubernetes.io/aws-load-balancer-backend-protocol`: - - Configures the ELB to operate in L4 or L7 mode. Can be set to `"tcp"`/`"ssl"` for an L4 listener or `"http"`/`"https"` for an L7 listener. Defaults to `"tcp"` or `"ssl"` if `aws-load-balancer-ssl-cert` is set. - -- `service.beta.kubernetes.io/aws-load-balancer-type: "nlb"`: - - When this annotation is set it will launch a [Network Load Balancer (NLB)](#network-load-balancer-nlb) instead of a classic ELB. - -- `service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled`: - - Configures the load balancer to load balance across zones. For high availability, it is typical to deploy nodes across availability zones so this should be set to `"true"`. - - **Note:** You cannot configure this annotation and `service.beta.kubernetes.io/aws-load-balancer-type: "nlb"` at the same time. You must first deploy the `Service` with an NLB and then update it with the cross zone load balancing configuration. - -- `service.beta.kubernetes.io/aws-load-balancer-proxy-protocol`: - - Configures the ELB to enable the proxy protocol. `"*"`, which enables the proxy protocol on all ELB backends, is the only acceptable value. - - The proxy protocol can be used to preserve the client IP address. - - If setting this value, you need to make sure $productName$ is configured to use the proxy protocol (see [preserving the client IP address](#preserving-the-client-ip-address) below). - - **Note:** This annotation will not be recognized if `aws-load-balancer-type: "nlb"` is configured. Proxy protocol must be manually enabled for NLBs. - -## TLS termination - -TLS termination is an important part of any modern web app. $productName$ exposes a lot of TLS termination configuration options that make it a powerful tool for managing encryption between your clients and microservices. Refer to the [TLS Termination](../tls) documentation for more information on how to configure TLS termination at $productName$. - -With AWS, the AWS Certificate Manager (ACM) makes it easy to configure TLS termination at an AWS load balancer using the annotations explained above. - -This means that, when running $productName$ in AWS, you have the choice between terminating TLS at the load balancer using a certificate from the ACM or at $productName$ using a certificate stored as a `Secret` in your cluster. - -The following documentation will cover the different options available to you and how to configure $productName$ and the load balancer to get the most of each. - -### TLS termination at $productName$ - -Terminating TLS at $productName$ will guarantee you to be able to use all of the TLS termination options that $productName$ exposes including enforcing the minimum TLS version, setting the `alpn_protocols`, and redirecting cleartext to HTTPS. - -If terminating TLS at $productName$, you can provision any AWS load balancer that you want with the following (default) port assignments: - -```yaml -spec: - ports: - - name: http - port: 80 - targetPort: 8080 - - name: https - port: 443 - targetPort: 8443 -``` - -While terminating TLS at $productName$ makes it easier to expose more advanced TLS configuration options, it does have the drawback of not being able to use the ACM to manage certificates. You will have to manage your TLS certificates yourself or use the [automatic certificate management](../host-crd) available in $productName$ to have $productName$ do it for you. - -### TLS termination at the load balancer - -If you choose to terminate TLS at your Amazon load balancer you will be able to use the ACM to manage TLS certificates. This option does add some complexity to your $productName$ configuration, depending on which load balancer you are using. - -Terminating TLS at the load balancer means that $productName$ will be receiving all traffic as un-encrypted cleartext traffic. Since $productName$ expects to be serving both encrypted and cleartext traffic by default, you will need to make the following configuration changes to $productName$ to support this: - -#### L4 load balancer (default ELB or NLB) - -* **Load Balancer Service Configuration:** - The following `Service` will deploy a L4 ELB with TLS termination configured at the load balancer: - ```yaml - apiVersion: v1 - kind: Service - metadata: - name: ambassador - namespace: ambassador - annotations: - service.beta.kubernetes.io/aws-load-balancer-ssl-cert: {{ACM_CERT_ARN}} - service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "443" - spec: - type: LoadBalancer - ports: - - name: HTTP - port: 80 - targetPort: 8080 - - name: HTTPS - port: 443 - targetPort: 8080 - selector: - service: ambassador - ``` - - Note that the `spec.ports` has been changed so both the HTTP and HTTPS ports forward to the cleartext port 8080 on $productName$. - -* **`Host`:** - - The `Host` configures how $productName$ handles encrypted and cleartext traffic. The following `Host` configuration will tell $productName$ to `Route` cleartext traffic that comes in from the load balancer: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Host - metadata: - name: ambassador - spec: - hostname: "*" - selector: - matchLabels: - hostname: wildcard - acmeProvider: - authority: none - requestPolicy: - insecure: - action: Route - ``` - -**Important:** - -Because L4 load balancers do not set `X-Forwarded` headers, $productName$ will not be able to distinguish between traffic that came in to the load balancer as encrypted or cleartext. Because of this, **HTTP -> HTTPS redirection is not possible when terminating TLS at a L4 load balancer**. - -#### L7 load balancer (ELB or ALB) - -* **Load Balancer Service Configuration (L7 ELB):** - - The following `Service` will deploy a L7 ELB with TLS termination configured at the load balancer: - ```yaml - apiVersion: v1 - kind: Service - metadata: - name: ambassador - namespace: ambassador - annotations: - service.beta.kubernetes.io/aws-load-balancer-ssl-cert: {{ACM_CERT_ARN}} - service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "443" - service.beta.kubernetes.io/aws-load-balancer-backend-protocol: "http" - spec: - type: LoadBalancer - ports: - - name: HTTP - port: 80 - targetPort: 8080 - - name: HTTPS - port: 443 - targetPort: 8080 - selector: - service: ambassador - ``` - - Note that the `spec.ports` has been changed so both the HTTP and HTTPS ports forward to the cleartext port 8080 on $productName$. - -* **`Host`:** - - The `Host` configures how $productName$ handles encrypted and cleartext traffic. The following `Host` configuration will tell $productName$ to `Redirect` cleartext traffic that comes in from the load balancer: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Host - metadata: - name: ambassador - spec: - hostname: "*" - selector: - matchLabels: - hostname: wildcard - acmeProvider: - authority: none - requestPolicy: - insecure: - action: Redirect - ``` - -* **Module:** - - Since a L7 load balancer will be able to append to `X-Forwarded` headers, we need to configure $productName$ to trust the value of these headers. The following `Module` will configure $productName$ to trust a single L7 proxy in front of $productName$: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - xff_num_trusted_hops: 1 - use_remote_address: false - ``` - -**Note:** - -$productName$ uses the value of `X-Forwarded-Proto` to know if the request originated as encrypted or cleartext. Unlike L4 load balancers, L7 load balancers will set this header so HTTP -> HTTPS redirection is possible when terminating TLS at a L7 load balancer. - -## Preserving the client IP address - -Many applications will want to know the IP address of the connecting client. In Kubernetes, this IP address is often obscured by the IP address of the `Node` that is forwarding the request to $productName$ so extra configuration must be done if you need to preserve the client IP address. - -In AWS, there are two options for preserving the client IP address. - -1. Use a L7 Load Balancer that sets `X-Forwarded-For` - - A L7 load balancer will populate the `X-Forwarded-For` header with the IP address of the downstream connecting client. If your clients are connecting directly to the load balancer, this will be the IP address of your client. - - When using L7 load balancers, you must configure $productName$ to trust the value of `X-Forwarded-For` and not append its own IP address to it by setting `xff_num_trusted_hops` and `use_remote_address: false` in the [Ambassador `Module`](../ambassador): - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - xff_num_trusted_hops: 1 - use_remote_address: false - ``` - - After configuring the above `Module`, you will need to restart $productName$ for the changes to take effect. - -2. Use the proxy protocol - - The [proxy protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) is a wrapper around an HTTP request that, like `X-Forwarded-For`, lists the IP address of the downstream connecting client but is able to be set by L4 load balancers as well. - - In AWS, you can configure ELBs to use the proxy protocol by setting the `service.beta.kubernetes.io/aws-load-balancer-proxy-protocol: "*"` annotation on the service. You must manually configure this on ALBs and NLBs. - - After configuring the load balancer to use the proxy protocol, you need to tell $productName$ to expect it on the request. - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - use_proxy_proto: true - ``` - - After configuring the above `Module`, you will need to restart $productName$ for the changes to take effect. diff --git a/content/en/docs/3.4/topics/running/ambassador-with-gke.md b/content/en/docs/3.4/topics/running/ambassador-with-gke.md deleted file mode 100644 index 2b90581d..00000000 --- a/content/en/docs/3.4/topics/running/ambassador-with-gke.md +++ /dev/null @@ -1,187 +0,0 @@ -# $productName$ with GKE - -Google offers a [L7 load balancer](https://cloud.google.com/kubernetes-engine/docs/concepts/ingress) to -leverage network services such as managed SSL certificates, SSL offloading or the Google content delivery network. -A L7 load balancer in front of $productName$ can be configured by hand or by using the Ingress-GCE resource. Using the -Ingress resource also allows you to create Google-managed SSL certificates through Kubernetes. - -With this setup, HTTPS will be terminated at the Google load balancer. The load balancer will be created and configured by -the Ingress-GCE resource. The load balancer consists of a set of -[forwarding rules](https://cloud.google.com/load-balancing/docs/forwarding-rule-concepts#https_lb) and a set of -[backend services](https://cloud.google.com/load-balancing/docs/backend-service). -In this setup, the ingress resource creates two forwarding rules, one for HTTP and one for HTTPS. The HTTPS -forwarding rule has the SSL certificates attached. Also, one backend service will be created to point to -a list of instance groups at a static port. This will be the NodePort of the $productName$ service. - -With this setup, the load balancer terminates HTTPS and then directs the traffic to the $productName$ service -via the `NodePort`. $productName$ is then doing all the routing to the other internal/external services. - -# Overview of steps - -1. Install and configure the ingress with the HTTP(S) load balancer -2. Install $productName$ -3. Configure and connect $productName$ to ingress -4. Create an SSL certificate and enable HTTPS -5. Create BackendConfig for health checks -6. Configure $productName$ to do HTTP -> HTTPS redirection - -`ambassador` will be running as a `NodePort` service. Health checks will be configured to go to a BackendConfig resource. - -## 0. $productName$ - -This guide will install $OSSproductName$. You can also install $AESproductName$. Please note: -- The ingress and the `ambassador` service need to run in the same namespace -- The `ambassador` service needs to be of type `NodePort` and not `LoadBalancer`. Also remove the line with `externalTrafficPolicy: Local` -- Ambassador-Admin needs to be of type `NodePort` instead of `ClusterIP` since it needs to be available for health checks - -## 1 . Install and configure ingress with the HTTP(S) load balancer - -Create a GKE cluster through the web console. Use the release channel. When the cluster -is up and running follow [this tutorial from Google](https://cloud.google.com/kubernetes-engine/docs/tutorials/http-balancer) to configure -an ingress and a L7 load balancer. After you have completed these steps you will have a running L7 load balancer -and one service. - -## 2. Install $productName$ - -Follow the first section of the [$OSSproductName$ installation guide](../../install/) to install $OSSproductName$. -Stop before defining the `ambassador` service. - -$productName$ needs to be deployed as `NodePort` instead of `LoadBalancer` to work with the L7 load balancer and the ingress. - -Save the YAML below in ambassador.yaml and apply with `kubectl apply -f ambassador.yaml` - -```yaml -apiVersion: v1 -kind: Service -metadata: - name: ambassador -spec: - type: NodePort - ports: - - port: 8080 - targetPort: 8080 - selector: - service: ambassador -``` - -You will now have an `ambassador` service running next to your ingress. - -## 3. Configure and connect `ambassador` to the ingress - -You need to change the ingress for it to send traffic to `ambassador`. Assuming you have followed the tutorial, you should -have a file named basic-ingress.yaml. Change it to point to `ambassador` instead of web: - -```yaml -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - name: basic-ingress -spec: - backend: - serviceName: ambassador - servicePort: 8080 -``` - -Now let's connect the other service from the tutorial to `ambassador` by specifying a Mapping: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: web - namespace: default -spec: - hostname: "*" - prefix: / - service: web:8080 -``` - -All traffic will now go to `ambassador` and from `ambassador` to the `web` service. You should be able to hit your load balancer and get the output. It may take some time until the load balancer infrastructure has rolled out all changes and you might see gateway errors during that time. -As a side note: right now all traffic will go to the `web` service, including the load balancer health check. - -## 4. Create an SSL certificate and enable HTTPS - -Read up on [managed certificates on GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/managed-certs). You need -a DNS name and point it to the external IP of the load balancer. - -certificate.yaml: -```yaml -apiVersion: networking.gke.io/v1beta1 -kind: ManagedCertificate -metadata: - name: www-example-com -spec: - domains: - - www.example.com -``` - -Modify the ingress from before: -```yaml -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - name: basic-ingress - annotations: - networking.gke.io/managed-certificates: www-example-com -spec: - backend: - serviceName: ambassador - servicePort: 8080 -``` - -Please wait (5-15 minutes) until the certificate is created and all edge servers have the certificates ready. -`kubectl describe ManagedCertificate` will show you the status or go to the web console to view the load balancer. - -You should now be able to access the web service via `https://www.example.com`. - -## 5. Configure BackendConfig for health checks - -Create and apply a BackendConfig resource with a [custom health check](https://cloud.google.com/kubernetes-engine/docs/how-to/ingress-features#direct_health) specified: - -```yaml -apiVersion: cloud.google.com/v1 -kind: BackendConfig -metadata: - name: ambassador-hc-config - namespace: ambassador -spec: - # https://cloud.google.com/kubernetes-engine/docs/how-to/ingress-features - timeoutSec: 30 - connectionDraining: - drainingTimeoutSec: 30 - logging: - enable: true - sampleRate: 1.0 - healthCheck: - checkIntervalSec: 10 - timeoutSec: 10 - port: 8877 - type: HTTP - requestPath: /ambassador/v0/check_alive -``` - -Then edit your previous `ambassador.yaml` file to add an annotation referencing the BackendConfig and apply the file: - -``` -apiVersion: v1 -kind: Service -metadata: - name: ambassador - annotations: - cloud.google.com/backend-config: '{"default": "ambassador-hc-config"}' -spec: - type: NodePort - ports: - - port: 8080 - targetPort: 8080 - selector: - service: ambassador -``` - -## 6. Configure $productName$ to do HTTP -> HTTPS redirection - -Configure $productName$ to [redirect traffic from HTTP to HTTPS](../tls/cleartext-redirection/#http-https-redirection). You will need to restart $productName$ to effect the changes with `kubectl rollout restart deployment ambassador`. - -The result should be that `http://www.example.com` will redirect to `https://www.example.com`. - -You can now add more services by specifying the hostname in the Mapping. diff --git a/content/en/docs/3.4/topics/running/ambassador.md b/content/en/docs/3.4/topics/running/ambassador.md deleted file mode 100644 index 3af41d93..00000000 --- a/content/en/docs/3.4/topics/running/ambassador.md +++ /dev/null @@ -1,558 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# The `Ambassador` `Module` Resource - -
-

Contents

- -* [Envoy](#envoy) -* [General](#general) -* [gRPC](#grpc) -* [Header behavior](#header-behavior) -* [Observability](#observability) -* [Protocols](#protocols) -* [Security](#security) -* [Service health / timeouts](#service-health--timeouts) -* [Traffic management](#traffic-management) - - -
- -If present, the `ambassador` `Module` defines system-wide configuration for $productName$. You won't need it unless you need to change one of the system-wide configuration settings below. - -To use the `ambassador` `Module` to configure $productName$, it MUST be named `ambassador`, otherwise it will be ignored. To create multiple `ambassador` `Module`s in the same Kubernetes namespace, you will need to apply them as annotations with separate `ambassador_id`s: you will not be able to use multiple CRDs. - -There are many items that can be configured on the `ambassador` `Module`. They are listed below with examples and grouped by category. - -## Envoy - -##### Content-Length headers - -* `allow_chunked_length: true` tells Envoy to allow requests or responses with both `Content-Length` and `Transfer-Encoding` headers set. The default is `false`. - -By default, messages with both `Content-Length` and `Content-Transfer-Encoding` are rejected. If `allow_chunked_length` is `true`, $productName$ will remove the `Content-Length` header and process the message. See the [Envoy documentation for more details](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto.html?highlight=allow_chunked_length#config-core-v3-http1protocoloptions). - -##### Envoy access logs - -* `envoy_log_path` defines the path of Envoy's access log. By default this is standard output. -* `envoy_log_type` defines the type of access log Envoy will use. Currently, only `json` or `text` are supported. -* `envoy_log_format` defines the Envoy access log line format. - -These logs can be formatted using [Envoy operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) to display specific information about an incoming request. The example below will show only the protocol and duration of a request: - -```yaml -envoy_log_path: /dev/fd/1 -envoy_log_type: json -envoy_log_format: - { - "protocol": "%PROTOCOL%", - "duration": "%DURATION%" - } -``` - -See the Envoy documentation for the [standard log format](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#default-format-string) and a [complete list of log format operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/access_log). - -##### Envoy validation timeout - -* `envoy_validation_timeout` defines the timeout, in seconds, for validating a new Envoy configuration. The default is 10. - -A value of 0 disables Envoy configuration validation. Most installations will not need to change this setting. - -For example: - -```yaml -envoy_validation_timeout: 30 -``` - -would allow 30 seconds to validate the generated Envoy configuration. - -##### Error response overrides - -* `error_response_overrides` permits changing the status code and body text for 4XX and 5XX response codes. The default is not to override any error responses. - -By default, $productName$ will pass through error responses without modification, and errors generated locally will use Envoy's default response body, if any. - -See [using error response overrides](../custom-error-responses) for usage details. For example, this configuration: - -```yaml -error_response_overrides: - - on_status_code: 404 - body: - text_format: "File not found" -``` - -would explicitly modify the body of 404s to say "File not found". - -##### Forwarding client cert details - -Two attributes allow providing information about the client's TLS certificate to upstream certificates: - -* `forward_client_cert_details: true` will tell Envoy to add the `X-Forwarded-Client-Cert` to upstream - requests. The default is `false`. -* `set_current_client_cert_details` will tell Envoy what information to include in the - `X-Forwarded-Client-Cert` header. The default is not to include the `X-Forwarded-Client-Cert` header at all. - -$productName$ will not forward information about a certificate that it cannot validate. - -See the Envoy documentation on [X-Forwarded-Client-Cert](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers.html?highlight=xfcc#x-forwarded-client-cert) and [SetCurrentClientCertDetails](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto.html#extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-setcurrentclientcertdetails) for more information. - -```yaml -forward_client_cert_details: true -set_current_client_cert_details: SANITIZE -``` - -##### Server name - -* `server_name` allows overriding the server name that Envoy sends with responses to clients. The default is `envoy`. - -##### Suppress Envoy headers - -* `suppress_envoy_headers: true` will prevent $productName$ from emitting certain additional - headers to HTTP requests and responses. The default is `false`. - -For the exact set of headers covered by this config, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter#config-http-filters-router-headers-set) - ---- -## General - -##### Ambassador ID - -* `ambassador_id` allows using multiple instances of $productName$ in the same cluster. The default is unset. - -We recommend _not_ setting `ambassador_id` if you are running only one instance of $productName$ in your cluster. For more information, see the [Running and Deployment documentation](../running/#ambassador_id). - -If used, the `ambassador_id` value must be an array, for example: - -```yaml -ambassador_id: [ "test_environment" ] -``` - -##### Defaults - -* `defaults` provides a dictionary of default values that will be applied to various $productName$ resources. The default is to have no defaults configured. - -See [Using `ambassador` `Module` Defaults](../../using/defaults) for more information. - ---- - -## gRPC - -##### Bridges - -* `enable_grpc_http11_bridge: true` will enable the gRPC-HTTP/1.1 bridge. The default is `false`. -* `enable_grpc_web: true` will enable the gRPC-Web bridge. The default is `false`. - -gRPC is a binary HTTP/2-based protocol. While this allows high performance, it can be problematic for clients that are unable to speak HTTP/2 (such as JavaScript in many browsers, or legacy clients in difficult-to-update environments). - -The gRPC-HTTP/1.1 bridge can translate HTTP/1.1 calls with `Content-Type: application/grpc` into gRPC calls: $productName$ will perform buffering and translation as necessary. For more details on the translation process, see the [Envoy gRPC HTTP/1.1 bridge documentation](https://www.envoyproxy.io/docs/envoy/v1.11.2/configuration/http_filters/grpc_http1_bridge_filter.html). - -Likewise, gRPC-Web is a JSON and HTTP-based protocol that allows browser-based clients to take advantage of gRPC protocols. The gRPC-Web specification requires a server-side proxy to translate between gRPC-Web requests and gRPC backend services, and $productName$ can fill this role when the gRPC-Web bridge is enabled. For more details on the translation process, see the [Envoy gRPC HTTP/1.1 bridge documentation](https://www.envoyproxy.io/docs/envoy/v1.11.2/configuration/http_filters/grpc_http1_bridge_filter.html); for more details on gRPC-Web itself, see the [gRPC-Web client GitHub repo](https://github.com/grpc/grpc-web). - -##### Statistics - -* `grpc_stats` allows enabling telemetry for gRPC calls using Envoy's [gRPC Statistics Filter](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/grpc_stats_filter). The default is disabled. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - grpc_stats: - upstream_stats: true - services: - - name: . - method_names: [] -``` - -Supported parameters: -* `all_methods` -* `services` -* `upstream_stats` - -Available metrics: -* `envoy_cluster_grpc__` -* `envoy_cluster_grpc__request_message_count` -* `envoy_cluster_grpc__response_message_count` -* `envoy_cluster_grpc__success` -* `envoy_cluster_grpc__total` -* `envoy_cluster_grpc_upstream_` - **only when `upstream_stats: true`** - -Please note that `` will only be present if `all_methods` is set or the service and the method are present under `services`. If `all_methods` is false or the method is not on the list, the available metrics will be in the format `envoy_cluster_grpc_`. - -* `all_methods`: If set to true, emit stats for all service/method names. -If set to false, emit stats for all service/message types to the same stats without including the service/method in the name. -**This option is only safe if all clients are trusted. If this option is enabled with untrusted clients, the clients could cause unbounded growth in the number -of stats in Envoy, using unbounded memory and potentially slowing down stats pipelines.** - -* `services`: If set, specifies an allow list of service/methods that will have individual stats emitted for them. Any call that does not match the allow list will be counted in a stat with no method specifier (generic metric). - - - If both all_methods and services are present, all_methods will be ignored. - - -* `upstream_stats`: If true, the filter will gather a histogram for the request time of the upstream. - ---- - -## Header behavior - -##### Header case - -* `proper_case: true` forces headers to have their "proper" case as shown in RFC7230. The default is `false`. -* `header_case_overrides` allows forcing certain headers to have specific casing. The default is to override no headers. - -proper_case and header_case_overrides are mutually exclusive. - -RFC7230 specifies that HTTP header names are case-insensitive, but always shows and refers to headers as starting with a capital letter, continuing in lowercase, then repeating the single capital letter after each non-alpha character. This has become an established convention when working with HTTP: - -- `Host`, not `host` or `HOST` -- `Content-Type`, not `content-type`, `Content-type`, or `cOnTeNt-TyPe` - -Internally, Envoy typically uses [all lowercase](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/header_casing) for header names. This is fully compliant with RFC7230, but some services and clients may require headers to follow the stricter casing rules implied by RFC7230 section headers: in that situation, setting `proper_case: true` will tell Envoy to force all headers to use the casing above. - -Alternately, it is also possible - although less common - for services or clients to require some other specific casing for specific headers. `header_case_overrides` specifies an array of header names: if a case-insensitive match for a header is found in the list, the matching header will be replaced with the one in the list. For example, the following configuration will force headers that match `X-MY-Header` and `X-EXPERIMENTAL` to use that exact casing, regardless of the original case used in flight: - -```yaml -header_case_overrides: -- X-MY-Header -- X-EXPERIMENTAL -``` - -If the upstream service responds with `x-my-header: 1`, $productName$ will return `X-MY-Header: 1` to the client. Similarly, if the client includes `x-ExperiMENTAL: yes` in its request, the request to the upstream service will include `X-EXPERIMENTAL: yes`. Other headers will not be altered; $productName$ will use its default lowercase header. - -Please see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto.html#config-core-v3-http1protocoloptions-headerkeyformat) for more information. Note that in general, we recommend updating clients and services rather than relying on `header_case_overrides`. - -##### Linkerd interoperability - -* `add_linkerd_headers: true` will force $productName$ to include the `l5d-dst-override` header for Linkerd. The default is `false`. - -When using older Linkerd installations, requests going to an upstream service may need to include the `l5d-dst-override` header to ensure that Linkerd will route them correctly. Setting `add_linkerd_headers` does this automatically. See the [Mapping](../../using/mappings#linkerd-interoperability-add_linkerd_headers) documentation for more details. - -##### Max request headers size - -* `max_request_headers_kb` sets the maximum allowed request header size in kilobytes. If not set, the default is 60 KB. - -See [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto.html) for more information. - -##### Preserve external request ID - -* `preserve_external_request_id: true` will preserve any `X-Request-Id` header presented by the client. The default is `false`, in which case Envoy will always generate a new `X-Request-Id` value. - -##### Strip matching host port - -* `strip_matching_host_port: true` will tell $productName$ to strip any port number from the host/authority header before processing and routing the request if that port number matches the port number of Envoy's listener. The default is `false`, which will preserve any port number. - -In the default installation of $productName$ the public port is 443, which then maps internally to 8443, so this only works in custom installations where the public Service port and Envoy listener port match. - -A common reason to try using this property is if you are using gRPC with TLS and your client library appends the port to the Host header (i.e. `myurl.com:443`). We have an alternative solution in our [gRPC guide](../../../howtos/grpc#working-with-host-headers-that-include-the-port) that uses a [Lua script](#lua-scripts) to remove all ports from every Host header for that use case. - ---- - -## Miscellaneous - - -##### Envoy's admin port - -* `admin_port` specifies the port where $productName$'s Envoy will listen for low-level admin requests. The default is 8001; it should almost never need changing. - -##### Lua scripts - -* `lua_scripts` allows defining a custom Lua script to run on every request. The default is to run no script. - -This is useful for simple use cases that mutate requests or responses, for example to add a custom header: - -```yaml -lua_scripts: | - function envoy_on_response(response_handle) - response_handle:headers():add("Lua-Scripts-Enabled", "Processed") - end -``` - -For more details on the Lua API, see the [Envoy Lua filter documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/lua_filter.html). - -Some caveats around the embedded scripts: - -* They run in-process, so any bugs in your Lua script can break every request. -* They're run on every request/response to every URL. -* They're inlined in the $productName$ YAML; as such, we do not recommend using Lua scripts for long, complex logic. - -If you need more flexible and configurable options, $AESproductName$ supports a [pluggable Filter system](/docs/edge-stack/latest/topics/using/filters/). - -##### Merge slashes - -* `merge_slashes: true` will cause $productName$ to merge adjacent slashes in incoming paths when doing route matching and request filtering. The default is `false`. - -For example, with `merge_slashes: true`, a request for `//foo///bar` would be matched to a `Mapping` with prefix `/foo/bar`. - -##### Modify Default Buffer Size - -By default, the Envoy that ships with $productName$ uses a defailt of 1MiB soft limit for an upstream service's read and write buffer limits. This setting allows you to configure that buffer limit. See the [Envoy docs](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto.html?highlight=per_connection_buffer_limit_bytes) for more information. - -```yaml -buffer_limit_bytes: 5242880 # Sets the default buffer limit to 5 MiB -``` - -##### Use $productName$ namespace for service resolution - -* `use_ambassador_namespace_for_service_resolution: true` tells $productName$ to assume that unqualified services are in the same namespace as $productName$. The default is `false`. - -By default, when $productName$ sees a service name without a namespace, it assumes that the namespace is the same as the resource referring to the service. For example, for this `Mapping`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-1 - namespace: foo -spec: - hostname: "*" - prefix: / - service: upstream -``` - -$productName$ would look for a Service named `upstream` in namespace `foo`. - -However, if `use_ambassador_namespace_for_service_resolution` is `true`, this `Mapping` would look for a Service named `foo` in the namespace in which $productName$ is installed instead. - ---- - -## Observability - -##### Diagnostics - -* `diagnostics` controls access to the diagnostics interface. - -By default, $productName$ creates a `Mapping` that allows access to the diagnostic interface at `/ambassador/v0/diag` from anywhere in the cluster. To disable the `Mapping` entirely, set `diagnostics.enabled` to `false`: - - -```yaml -diagnostics: - enabled: false -``` - -With diagnostics disabled, `/ambassador/v0/diag` will respond with 404; however, the service itself is still running, and `/ambassador/v0/diag/` is reachable from inside the $productName$ Pod at `https://localhost:8877`. You can use Kubernetes port forwarding to set up remote access to the diagnostics page temporarily: - -``` -kubectl port-forward -n ambassador deploy/ambassador 8877 -``` - -Alternately, to leave the `Mapping` intact but restrict access to only the local Pod, set `diagnostics.allow_non_local` to `false`: - -```yaml -diagnostics: - allow_non_local: true -``` - -See [Protecting Access to the Diagnostics Interface](../../../howtos/protecting-diag-access) for more information. - ---- -## Protocols - -##### Enable IPv4 and IPv6 - -* `enable_ipv4` determines whether IPv4 DNS lookups are enabled. The default is `true`. -* `enable_ipv6` determines whether IPv6 DNS lookups are enabled. The default is `false`. - -If both IPv4 and IPv6 are enabled, $productName$ will prefer IPv6. This can have strange effects if $productName$ receives `AAAA` records from a DNS lookup, but the underlying network of the pod doesn't actually support IPv6 traffic. For this reason, the default is IPv4 only. - -An [`Mapping`](../../using/mappings) can override both `enable_ipv4` and `enable_ipv6`, but if either is not stated explicitly in a `Mapping`, the values here are used. Most $productName$ installations will probably be able to avoid overriding these settings in Mappings. - -##### HTTP/1.0 support - -* `enable_http10: true` will enable handling incoming HTTP/1.0 and HTTP/0.9 requests. The default is `false`. - ---- -## Security - -##### Cross origin resource sharing (CORS) - -* `cors` sets the default CORS configuration for all mappings in the cluster. The default is that CORS is not configured. - -For example: - -```yaml -cors: - origins: http://foo.example,http://bar.example - methods: POST, GET, OPTIONS - ... -``` - -See the [CORS syntax](../../using/cors) for more information. - -##### IP allow and deny - -* `ip_allow` and `ip_deny` define HTTP source IP address ranges to allow or deny. The default is to allow all traffic. - -Only one of ip_allow and ip_deny may be specified. - -If `ip_allow` is specified, any traffic not matching a range to allow will be denied. If `ip_deny` is specified, any traffic not matching a range to deny will be allowed. A list of ranges to allow and a separate list to deny may not both be specified. - -Both take a list of IP address ranges with a keyword specifying how to interpret the address, for example: - -```yaml -ip_allow: -- peer: 127.0.0.1 -- remote: 99.99.0.0/16 -``` - -The keyword `peer` specifies that the match should happen using the IP address of the other end of the network connection carrying the request: `X-Forwarded-For` and the `PROXY` protocol are both ignored. Here, our example specifies that connections originating from the $productName$ pod itself should always be allowed. - -The keyword `remote` specifies that the match should happen using the IP address of the HTTP client, taking into account `X-Forwarded-For` and the `PROXY` protocol if they are allowed (if they are not allowed, or not present, the peer address will be used instead). This permits matches to behave correctly when, for example, $productName$ is behind a layer 7 load balancer. Here, our example specifies that HTTP clients from the IP address range `99.99.0.0` - `99.99.255.255` will be allowed. - -You may specify as many ranges for each kind of keyword as desired. - -##### Rejecting Client Requests With Escaped Slashes - -* `reject_requests_with_escaped_slashes: true` will tell $productName$ to reject requests containing escaped slashes. The default is `false`. - -When set to `true`, $productName$ will reject any client requests that contain escaped slashes (`%2F`, `%2f`, `%5C`, or `%5c`) in their URI path by returning HTTP 400. By default, $productName$ will forward these requests unmodified. - -In general, a request with an escaped slash will _not_ match a `Mapping` prefix with an unescaped slash. However, external authentication services and other upstream services may handle escaped slashes differently, which can lead to security issues if paths with escaped slashes are allowed. By setting `reject_requests_with_escaped_slashes: true`, this class of security concern can be largely avoided. - -##### Trust downstream client IP - -* `use_remote_address: false` tells $productName$ that it cannot trust the remote address of incoming connections, and must instead rely exclusively on the `X-Forwarded-For` header. The default is `true`. - -When `true` (the default), $productName$ will append its own IP address to the `X-Forwarded-For` header so that upstream services of $productName$ can get the full set of IP addresses that have propagated a request. You may also need to set `externalTrafficPolicy: Local` on your `LoadBalancer` to propagate the original source IP address. - -See the [Envoy documentation on the `X-Forwarded-For header` ](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers) and the [Kubernetes documentation on preserving the client source IP](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/#preserving-the-client-source-ip) for more details. - -##### `X-Forwarded-For` trusted hops - -* `xff_num_trusted_hops` sets the default value for [the `l7Depth` setting of a `Listener`](../listener/#securitymodel). The default is 0. - -See the [`Listener` documentation](../listener/#securitymodel) for more details. - ---- - -## Service health / timeouts - -##### Incoming connection idle timeout - -* `listener_idle_timeout_ms` sets the idle timeout for incoming connections. The default is no timeout, meaning that incoming connections may remain idle forever. - -If set, this specifies the length of time (in milliseconds) that an incoming connection is allowed to be idle before being dropped. This can useful if you have proxies and/or firewalls in front of $productName$ and need to control how $productName$ initiates closing an idle TCP connection. - -Please see the [Envoy documentation on HTTP protocol options](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#config-core-v3-httpprotocoloptions) for more information. - -##### Keepalive - -* `keepalive` sets the global TCP keepalive settings. - -$productName$ will use these settings for all `AmbasasdorMapping`s unless overridden in a `Mapping`'s configuration. Without `keepalive`, $productName$ follows the operating system defaults. - -For example, the following configuration: - -```yaml -keepalive: - time: 2 - interval: 2 - probes: 100 -``` - -would enable keepalives every two seconds (`interval`), starting after two seconds of idleness (`time`), with the connection being dropped if 100 keepalives are sent with no response (`probes`). For more information, see the [Envoy keepalive documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/address.proto.html#config-core-v3-tcpkeepalive). - -##### Upstream idle timeout - -* `cluster_idle_timeout_ms` sets the default idle timeout for upstream connections (by default, one hour). - -If set, this specifies the timeout (in milliseconds) after which an idle connection upstream is closed. The idle timeout can be completely disabled by setting `cluster_idle_timeout_ms: 0`, which risks idle upstream connections never getting closed. - -If not set, the default idle timeout is one hour. - -You can override this setting with [`idle_timeout_ms` on a `Mapping`](../../using/timeouts/). - -##### Upstream max lifetime - -* `cluster_max_connection_lifetime_ms` sets the default maximum lifetime of an upstream connection. - -If set, this specifies the maximum amount of time (in milliseconds) after which an upstream connection is drained and closed, regardless of whether it is idle or not. Connection recreation incurs additional overhead when processing requests. The overhead tends to be nominal for plaintext (HTTP) connections within the same cluster, but may be more significant for secure HTTPS connections or upstreams with high latency. For this reason, it is generally recommended to set this value to at least 10000 ms to minimize the amortized cost of connection recreation while providing a reasonable bound for connection lifetime. - -If not set (or set to zero), then upstream connections may remain open for arbitrarily long. - -You can override this setting with [`cluster_max_connection_lifetime_ms` on a `Mapping`](../../using/timeouts/). - -##### Request timeout - -* `cluster_request_timeout_ms` sets the default end-to-end timeout for a single request. - -If set, this specifies the default end-to-end timeout for every request. - -If not set, the default is three seconds. - -You can override this setting with [`timeout_ms` on a `Mapping`](../../using/timeouts/). - -##### Readiness and liveness probes - -* `readiness_probe` sets whether `/ambassador/v0/check_ready` is automatically mapped -* `liveness_probe` sets whether `/ambassador/v0/check_alive` is automatically mapped - -By default, $productName$ creates `Mapping`s that support readiness and liveness checks at `/ambassador/v0/check_ready` and `/ambassador/v0/check_alive`. To disable the readiness `Mapping` entirely, set `readiness_probe.enabled` to `false`: - - -```yaml -readiness_probe: - enabled: false -``` - -Likewise, to disable the liveness `Mapping` entirely, set `liveness_probe.enabled` to `false`: - - -```yaml -liveness_probe: - enabled: false -``` - -A disabled probe endpoint will respond with 404; however, the service is still running, and will be accessible on localhost port 8877 from inside the $productName$ Pod. - -You can change these to route requests to some other service. For example, to have the readiness probe map to the `quote` application's health check: - -```yaml -readiness_probe: - enabled: true - service: quote - rewrite: /backend/health -``` - -The liveness and readiness probes both support `prefix` and `rewrite`, with the same meanings as for [Mappings](../../using/mappings). - -##### Retry policy - -This lets you add resilience to your services in case of request failures by performing automatic retries. - -```yaml -retry_policy: - retry_on: "5xx" -``` - ---- - -## Traffic management - -##### Circuit breaking - -* `circuit_breakers` sets the global circuit breaking configuration defaults - -You can override the circuit breaker settings for individual `Mapping`s. By default, $productName$ does not configure any circuit breakers. For more information, see the [circuit breaking reference](../../using/circuit-breakers). - -##### Default label domain and labels - -* `default_labels` sets default domains and labels to apply to every request. - -For more on how to use the default labels, , see the [Rate Limit reference](../../using/rate-limits/#attaching-labels-to-requests). - -##### Default load balancer - -* `load_balancer` sets the default load balancing type and policy - -For example, to set the default load balancer to `least_request`: - -```yaml -load_balancer: - policy: least_request -``` - -If not set, the default is to use round-robin load balancing. For more information, see the [load balancer reference](../load-balancer). diff --git a/content/en/docs/3.4/topics/running/custom-error-responses.md b/content/en/docs/3.4/topics/running/custom-error-responses.md deleted file mode 100644 index b0ad9877..00000000 --- a/content/en/docs/3.4/topics/running/custom-error-responses.md +++ /dev/null @@ -1,217 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Custom error responses - -Custom error responses set overrides for HTTP response statuses generated either -by $productName$ or upstream services. - -They can be configured either on the $productName$ -[`Module`](../ambassador) -or on an [`Mapping`](../../using/intro-mappings/), the schema is identical. See -below for more information on [rule precedence](#rule-precedence). - -- `on_status_code`: HTTP status code to match for this rewrite - rule. Only 4xx and 5xx classes are supported. -- `body`: Describes the response body contents and format. - + `content_type`: A string that sets the content type of the - response. - + `text_format`: A string whose value will be used as the new - response body. `Content-Type` will default to `text/plain` if - unspecified. - + `json_format`: A config object whose keys and values will be - serialized as JSON and used as the new response body. - + `text_format_source`: Describes a file to be used as the - response. If used, `filename` must be set and the file must exist - on the $productName$ pod. - * `filename`: A file path on the $productName$ pod that will be used - as the new response body. - -Only one of `text_format`, `json_format`, or `text_format_source` may be provided. - -Custom response bodies are subject to Envoy's AccessLog substitution syntax -and variables, see [Envoy's documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#config-access-log-format-strings) for more information. - -Note that the AccessLog substitutions use `%` as a delimiter (for example, -`%RESPONSE_CODE%`). To include a literal `%` in a custom response body, use `%%`. -For example, - -``` -%%RESPONSE_CODE%% %RESPONSE_CODE% -``` - -would render as - -``` -%RESPONSE_CODE% 401 -``` - -for a request that resulted in a response code of 401. - - - If the % 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. - - -## Simple response bodies - -Simple responses can be be added quickly for convenience. They are inserted into -the manifest as either text or JSON: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador - namespace: ambassador -spec: - config: - error_response_overrides: - - on_status_code: 404 - body: - text_format: "File not found" - - on_status_code: 500 - body: - json_format: - error: "Application error" - status: "%RESPONSE_CODE%" - cluster: "%UPSTREAM_CLUSTER%" -``` -## File response bodies - -For more complex response bodies a file can be returned as the response. -This could be used for a customer friendly HTML document for example. Use -`text_format_source` with a `filename` set as a path on the $productName$ pod. -`content_type` should be used set the specific file type, such as `text/html`. - -First configure the $productName$ module: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador - namespace: ambassador -spec: - config: - error_response_overrides: - - on_status_code: 404 - body: - content_type: "text/html" - text_format_source: - filename: '/ambassador/ambassador-errorpages/404.html' -``` - -Then create the config map containing the HTML file: - -```yaml ---- -apiVersion: v1 -kind: ConfigMap -metadata: - name: ambassador-errorpages - namespace: ambassador -data: - 404.html: | - -

File not found

-

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/content/en/docs/3.4/topics/running/debugging.md b/content/en/docs/3.4/topics/running/debugging.md deleted file mode 100644 index bd376483..00000000 --- a/content/en/docs/3.4/topics/running/debugging.md +++ /dev/null @@ -1,192 +0,0 @@ -# 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. - - - Enabling debug-level logging can produce a lot of log output — enough to - potentially impact the performance of $productName$. We don't recommend running with debug - logging enabled as a matter of course; it's usually better to enable it only when needed, - then reset logging to normal once you're finished debugging. - - -### $productName$ debug logging - -Much of $productName$'s logging is concerned with the business of noticing changes to -Kubernetes resources that specify the $productName$ configuration, and generating new -Envoy configuration in response to those changes. Enabling debug logging for this part -of the system is under the control of two environment variables: - -- Set `AES_LOG_LEVEL=debug` to debug the early boot sequence and $productName$'s interactions - with the Kubernetes cluster (finding changed resources, etc.). -- Set `AMBASSADOR_DEBUG=diagd` to debug the process of generating an Envoy configuration from - the input resources. - -### $productName$ Envoy logging - -Envoy logging is concerned with the actions Envoy is taking for incoming requests. -Typically, Envoy will only output access logs, and certain errors, but enabling Envoy -debug logging will show very verbose information about the actions Envoy is actually -taking. It can be useful for understanding why connections are being closed, or whether -an error status is coming from Envoy or from the upstream service. - -It is possible to enable Envoy logging at boot, but for the most part, it's safer to -enable it at runtime, right before sending a request that is known to have problems. -To enable Envoy debug logging, use `kubectl exec` to get a shell on the $productName$ -pod, then: - - ``` - curl -XPOST http://localhost:8001/logging?level=trace && \ - sleep 10 && \ - curl -XPOST http://localhost:8001/logging?level=warning - ``` - -This will turn on Envoy debug logging for ten seconds, then turn it off again. - -### Viewing logs - -To view the logs from $productName$: - -1. Use the following command to target an individual $productName$ Pod: `kubectl get pods -n $productNamespace$` - - The terminal will print something similar to the following: - - ``` - $ kubectl get pods -n $productNamespace$ - NAME READY STATUS RESTARTS AGE - $productDeploymentName$-85c4cf67b-4pfj2 1/1 Running 0 3m - ``` - -2. Then, run the following: `kubectl logs -n $productNamespace$ <$productDeploymentName$-pod-name>` - -The terminal will print something similar to the following: - - ``` - $ kubectl logs -n $productNamespace$ $productDeploymentName$-85c4cf67b-4pfj2 - 2018-10-10 12:26:50 kubewatch 0.40.0 INFO: generating config with gencount 1 (0 changes) - /usr/lib/python3.6/site-packages/pkg_resources/__init__.py:1235: UserWarning: /ambassador is writable by group/others and vulnerable to attack when used with get_resource_filename. Consider a more secure location (set with .set_extraction_path or the PYTHON_EGG_CACHE environment variable). - warnings.warn(msg, UserWarning) - 2018-10-10 12:26:51 kubewatch 0.40.0 INFO: Scout reports {"latest_version": "0.40.0", "application": "ambassador", "notices": [], "cached": false, "timestamp": 1539606411.061929} - - 2018-10-10 12:26:54 diagd 0.40.0 [P15TMainThread] INFO: thread count 3, listening on 0.0.0.0:8877 - [2018-10-10 12:26:54 +0000] [15] [INFO] Starting gunicorn 19.8.1 - [2018-10-10 12:26:54 +0000] [15] [INFO] Listening at: http://0.0.0.0:8877 (15) - [2018-10-10 12:26:54 +0000] [15] [INFO] Using worker: threads - [2018-10-10 12:26:54 +0000] [42] [INFO] Booting worker with pid: 42 - 2018-10-10 12:26:54 diagd 0.40.0 [P42TMainThread] INFO: Starting periodic updates - [2018-10-10 12:27:01.977][21][info][main] source/server/drain_manager_impl.cc:63] shutting down parent after drain - ``` - -Note that many deployments will have multiple logs, and the logs are independent for each Pod. - -## Examine Pod and container contents - -You can examine the contents of the $productName$ Pod for issues, such as if volume mounts are correct and TLS certificates are present in the required directory, to determine if the Pod has the latest $productName$ configuration, or if the generated Envoy configuration is correct or as expected. In these instructions, we will look for problems related to the Envoy configuration. - -1. To look into an $productName$ Pod, get a shell on the Pod using `kubectl exec`. For example, - - ``` - kubectl exec -it -n $productNamespace$ <$productDeploymentName$-pod-name> -- bash - ``` - -2. Determine the latest configuration. If you haven't overridden the configuration directory, the latest configuration will be in `/ambassador/snapshots`. If you have overridden it, $productName$ saves configurations in `$AMBASSADOR_CONFIG_BASE_DIR/snapshots`. - - In the snapshots directory: - - * `snapshot.yaml` contains the full input configuration that $productName$ has found; - * `aconf.json` contains the $productName$ configuration extracted from the snapshot; - * `ir.json` contains the IR constructed from the $productName$ configuration; and - * `econf.json` contains the Envoy configuration generated from the IR. - - In the snapshots directory, the current configuration will be stored in files with no digit suffix, and older configurations have increasing numbers. For example, `ir.json` is current, `ir-1.json` is the next oldest, then `ir-2.json`, etc. - -3. If something is wrong with `snapshot` or `aconf`, there is an issue with your configuration. If something is wrong with `ir` or `econf`, you should [open an issue on Github](https://github.com/emissary-ingress/emissary/issues/new/choose). - -4. The actual input provided to Envoy is split into `$AMBASSADOR_CONFIG_BASE_DIR/bootstrap-ads.json` and `$AMBASSADOR_CONFIG_BASE_DIR/envoy/envoy.json`. - - - The `bootstrap-ads.json` file contains details about Envoy statistics, logging, authentication, etc. - - The `envoy.json` file contains information about request routing. - - You may generally find it simplest to just look at the `econf.json` files in the `snapshot` - directory, which includes both kinds of configuration. diff --git a/content/en/docs/3.4/topics/running/diagnostics.md b/content/en/docs/3.4/topics/running/diagnostics.md deleted file mode 100644 index 20506304..00000000 --- a/content/en/docs/3.4/topics/running/diagnostics.md +++ /dev/null @@ -1,54 +0,0 @@ -# Diagnostics - -With $productName$ Diagnostics and Ambassador Cloud, you get a summary of the current status and Mappings of your cluster and it's services, which gets displayed -in [Diagnostics Overview](https://www.getambassador.io/docs/cloud/latest/diagnostics-ui/view-diagnostics/). - -## Troubleshooting - -### Can't access $productName$ Diagnostics Overview? - -Create an Ambassador `Module` if one does not already exist, and add the following config to enable diagnostics data. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - diagnostics: - enabled: true -``` -Next, ensure that the 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/content/en/docs/3.4/topics/running/environment.md b/content/en/docs/3.4/topics/running/environment.md deleted file mode 100644 index cb2d37fb..00000000 --- a/content/en/docs/3.4/topics/running/environment.md +++ /dev/null @@ -1,353 +0,0 @@ -# $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_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_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/content/en/docs/3.4/topics/running/gzip.md b/content/en/docs/3.4/topics/running/gzip.md deleted file mode 100644 index e3005c83..00000000 --- a/content/en/docs/3.4/topics/running/gzip.md +++ /dev/null @@ -1,55 +0,0 @@ -# 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/content/en/docs/3.4/topics/running/host-crd.md b/content/en/docs/3.4/topics/running/host-crd.md deleted file mode 100644 index cd187ebe..00000000 --- a/content/en/docs/3.4/topics/running/host-crd.md +++ /dev/null @@ -1,279 +0,0 @@ -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` - - - Remember that Listener resources are required for a functioning - $productName$ installation!
- Learn more about Listener. - - - - Remember than $productName$ does not make sure that a wildcard Host exists! If the - wildcard behavior is needed, a Host with a hostname of "*" - must be defined by the user. - - -A minimal `Host` resource, assuming no TLS configuration, would be: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: minimal-host -spec: - hostname: host.example.com -``` - -This `Host` tells $productName$ to expect to be reached at `host.example.com`, -with no TLS termination, and only associating with `Mapping`s that also set a -`hostname` that matches `host.example.com`. - -Remember that a 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/content/en/docs/3.4/topics/running/http3.md b/content/en/docs/3.4/topics/running/http3.md deleted file mode 100644 index 9aeb6cac..00000000 --- a/content/en/docs/3.4/topics/running/http3.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -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`. - - -The protocolStack elements need to be entered in the specific order of TLS, HTTP, UDP. - - -The `Listener` configured for HTTP/3 can be bound to the same address and port (`0.0.0.0:8443`) as the `Listener` that supports HTTP/2 and HTTP/1.1. This is not required, but it allows $productName$ to inject the default `alt-svc: h3=":443"; ma=86400, h3-29=":443"; ma=86400` header into the responses returned over the TCP connection with no additional configuration needed. **Most clients such as browsers require the `alt-svc` header to upgrade to HTTP/3**. - - -The current default of 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. - - -```yaml -# This is a standard Listener that leverages TCP to serve HTTP/2 and HTTP/1.1 traffic. -# It is bound to the same address and port (0.0.0.0:8443) as the UDP listener. -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: $productDeploymentName$-https-listener - namespace: $productNamespace$ -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: - namespace: - from: ALL ---- -# This is a Listener that leverages UDP and HTTP to serve HTTP/3 traffic. -# NOTE: Raw UDP traffic is not supported. UDP and HTTP must be used together. -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: $productDeploymentName$-https-listener-udp - namespace: $productNamespace$ -spec: - port: 8443 - # Order is important here. HTTP is required. - protocolStack: - - TLS - - HTTP - - UDP - securityModel: XFP - hostBinding: - namespace: - from: ALL -``` - -### Configuring the Host resource - -Because the QUIC network requires TLS, the certificate needs to be valid so the client can upgrade a connection to HTTP/3. See the [Host documentation](./host-crd.md) for more information on how to configure TLS for a `Host`. - -### Certificate verification - -Clients can only upgrade to an HTTP/3 connection with a valid certificate. If the client won’t upgrade to HTTP/3, verify that you have a valid TLS certificate and that your client can speak **TLS v1.3**. Your `Host` resource should be configured similar to the following: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: my-domain-host -spec: - hostname: your-hostname - # acme isn't required but just shown as an example of how to manage a valid TLS cert - acmeProvider: - email: your-email@example.com - authority: https://acme-v02.api.letsencrypt.org/directory - tls: - # QUIC requires TLS v1.3 version. Verify your client supports it. - min_tls_version: v1.3 - # Either protocol can be upgraded, but http/2 is recommended. - alpn_protocols: h2,http/1.1 -``` - -### External load balancers - -The two most common service types to expose traffic outside of a Kubernetes cluster are: - -- `LoadBalancer`: A load balancer controller generates and manages the cloud provider-specific external load balancer. -- `NodePort`: The platform administrator has to manually set up things like the external load balancer, firewall rules, and health checks. - -#### LoadBalancer setup - -The ideal setup would be to configure a single service of type `LoadBalancer`, but this comes with some current restrictions: -- You need version 1.24 or later of Kubernetes with the [`MixedProtocolLBService` feature enabled](https://kubernetes.io/docs/concepts/services-networking/service/#load-balancers-with-mixed-protocol-types). -- Your cloud service provider needs to support the creation of an external load balancer with mixed protocol types (TCP/UDP), port reuse, and port forwarding. Support for Kubernetes feature flags may vary between cloud service providers. Refer to your provider’s documentation to see if they support this scenario. - -An example `LoadBalancer` configuration that fits the criteria listed above: - -```yaml - -# note: extra fields such as labels and selectors removed for clarity -apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$ - namespace: $productNamespace$ -spec: - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - - name: http3 - port: 443 - targetPort: 8443 - protocol: UDP - type: LoadBalancer -``` - -## Cloud service provider setup - -Once you've completed the steps above, you need to configure HTTP/3 support through your cloud service provider. The configuration processes for each provider can be found here: - -- HTTP/3 setup for [Amazon Elastic Kubernetes Service (EKS)](../../../howtos/http3-eks) -- HTTP/3 setup for [Azure Kubernetes Service (AKS)](../../../howtos/http3-aks) -- HTTP/3 setup for [Google Kubernetes Engine (GKE)](../../../howtos/http3-gke) diff --git a/content/en/docs/3.4/topics/running/index.md b/content/en/docs/3.4/topics/running/index.md deleted file mode 100644 index 6eb7af94..00000000 --- a/content/en/docs/3.4/topics/running/index.md +++ /dev/null @@ -1,16 +0,0 @@ -# Running $productName$ in production - -This section of the documentation is designed for operators and site reliability engineers who are managing the deployment of $productName$. Learn more below: - -* *Global Configuration:* The [Ambassador module](ambassador) is used to set system-wide configuration. -* *Exposing $productName$ to the Internet:* The [`Listener` CRD](listener) defines which ports are exposed, including their protocols and security models. The [`Host` CRD](host-crd) defines how $productName$ manages TLS, domains, and such. -* *Load Balancing:* $productName$ supports a number of different [load balancing strategies](load-balancer) as well as different ways to configure [service discovery](resolvers) -* [Gzip Compression](gzip) -* *Deploying $productName$:* On [Amazon Web Services](ambassador-with-aws) | [Google Cloud](ambassador-with-gke) | [general security and operational notes](running), including running multiple $productNamePlural$ on a cluster -* *TLS/SSL:* [Simultaneously Routing HTTP and HTTPS](tls/cleartext-redirection#cleartext-routing) | [HTTP -> HTTPS Redirection](tls/cleartext-redirection#http-https-redirection) | [Mutual TLS](tls/mtls) | [TLS origination](tls/origination) -* *Statistics and Monitoring:* [Integrating with Prometheus, DataDog, and other monitoring systems](statistics) -* *Extending $productName$* $productName$ can be extended with custom plug-ins that connect via HTTP/gRPC interfaces. [Custom Authentication](services/auth-service) | [The External Auth protocol](services/ext-authz) | [Custom Logging](services/log-service) | [Rate Limiting](services/rate-limit-service) | [Distributed Tracing](services/tracing-service) -* *Troubleshooting:* [Diagnostics](diagnostics) | [Debugging](debugging) -* *Scaling $productName$:* [Scaling $productName$](scaling) -* *Ingress:* $productName$ can function as an [Ingress Controller](ingress-controller) -* *Error Response Overrides:* $productName$ can override 4xx and 5xx responses with [custom response bodies](custom-error-responses) diff --git a/content/en/docs/3.4/topics/running/ingress-controller.md b/content/en/docs/3.4/topics/running/ingress-controller.md deleted file mode 100644 index 9b7afb82..00000000 --- a/content/en/docs/3.4/topics/running/ingress-controller.md +++ /dev/null @@ -1,325 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Ingress controller - -
-

Contents

- -- [When and how to use the Ingress resource](#when-and-how-to-use-the-ingress-resource) -- [What is required to use the Ingress resource?](#what-is-required-to-use-the-ingress-resource) -- [When to use an Ingress instead of annotations or CRDs](#when-to-use-an-ingress-instead-of-annotations-or-crds) -- [Ingress support](#ingress-support) -- [Examples of Ingress configs vs Mapping configs](#examples-of-ingress-configs-vs-mapping-configs) -- [Ingress routes and mappings](#ingress-routes-and-mappings) -- [The Minimal Ingress](#the-minimal-ingress) -- [Name based virtual hosting with an Ambassador ID](#name-based-virtual-hosting-with-an-ambassador-id) -- [TLS Termination](#tls-termination) - -
- -An Ingress resource is a popular way to expose Kubernetes services to the Internet. In order to use Ingress resources, you need to install an [ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/). $productName$ can function as a fully-fledged Ingress controller, making it easy to work with other Ingress-oriented tools within the Kubernetes ecosystem. - -## When and how to use the Ingress resource - -If you're new to $productName$ and to Kubernetes, we'd recommend you start with our [quickstart](../../../tutorials/getting-started/) instead of this Ingress guide. If you're a power user and need to integrate with other software that leverages the Ingress resource, read on. The Ingress specification is very basic and does not support many of the features of $productName$, so you'll be using both the Ingress resource and $productName$'s Mapping resource to manage your Kubernetes services. - -### What is required to use the Ingress resource? - -- Know what version of Kubernetes you are using. - - - In Kubernetes 1.13 and below, the Ingress was only included in the `extensions` API. - - - Starting in Kubernetes 1.14, the Ingress was added to the new `networking.k8s.io` API. - - - Kubernetes 1.18 introduced the IngressClass resource to the existing `networking.k8s.io/v1beta1` API. - - If you are using 1.14 and above, it is recommended to use 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. - - -- You will need RBAC permissions to create Ingress resources in either - the `extensions` `apiGroup` (present in all supported versions of - Kubernetes) or the `networking.k8s.io` `apiGroup` (introduced in - Kubernetes 1.14). - -- $productName$ will need RBAC permissions to get, list, watch, and update Ingress resources. - - You can see this in the [`aes-crds.yaml`](https://app.getambassador.io/yaml/ambassador-docs/latest/aes.yaml) - file, but this is the critical rule to add to $productName$'s `Role` or `ClusterRole`: - - ```yaml - - apiGroups: ['extensions', 'networking.k8s.io'] - resources: ['ingresses', 'ingressclasses'] - verbs: ['get', 'list', 'watch'] - - apiGroups: ['extensions', 'networking.k8s.io'] - resources: ['ingresses/status'] - verbs: ['update'] - ``` - - - This is included by default in all $productName$ installations. - - -- You must create your Ingress resource with the correct `ingress.class`. - - $productName$ will automatically read Ingress resources with the annotation - `kubernetes.io/ingress.class: ambassador`. - -- You may need to set your Ingress resource's `ambassador-id`. - - If you are [using `amabssador-id` on your Module](../running/#ambassador_id), you'll need to add the `getambassador.io/ambassador-id` - annotation to your Ingress. See the [examples below](#name-based-virtual-hosting-with-an-ambassador-id). - -- You must create a Service resource with the correct `app.kubernetes.io/component` label. - - $productName$ will automatically load balance Ingress resources using the endpoint exposed - from the Service with the annotation `app.kubernetes.io/component: ambassador-service`. - - ```yaml - --- - kind: Service - apiVersion: v1 - metadata: - name: ingress-ambassador - labels: - app.kubernetes.io/component: ambassador-service - spec: - externalTrafficPolicy: Local - type: LoadBalancer - selector: - service: ambassador - ports: - - name: http - port: 80 - targetPort: http - - name: https - port: 443 - targetPort: https - ``` - -### When to use an Ingress instead of annotations or CRDs - -We recommend that $productName$ be configured using CRDs. The Ingress resource is available to users who need it for integration with other ecosystem tools, or who feel that it more closely matches their workflows. However, it is important to recognize that the Ingress resource is rather more limited than the $productName$ Mapping is (for example, the Ingress spec has no support for rewriting or for TLS origination). **When in doubt, use CRDs.** - -## Ingress support - -$productName$ supports basic core functionality of the Ingress resource, as defined by the [Ingress resource](https://kubernetes.io/docs/concepts/services-networking/ingress/) itself: - -- Basic routing is supported, including the `route` specification and the default backend functionality. It's particularly easy to use a minimal Ingress to the $productName$ diagnostic UI. -- [TLS termination](../tls/) is supported. You can use multiple Ingress resources for SNI. -- Using the Ingress resource in concert with $productName$ CRDs or annotations is supported. This includes $productName$ annotations on the Ingress resource itself. - -$productName$ does **not** extend the basic Ingress specification with the following exceptions: - -- The `getambassador.io/ambassador-id` annotation allows you to set [the Ambassador ID](../running/#ambassador_id) for the Ingress itself. - -- The `getambassador.io/config` annotation can be provided on the Ingress resource, just as on a Service. - -Note that if you need to set `getambassador.io/ambassador-id` on the Ingress, you will also need to set `ambassador-id` on resources within the annotation. - -## Examples of Ingress configs vs Mapping configs - -### Ingress routes and Mappings - -$productName$ actually creates Mapping objects from the Ingress route rules. These Mapping objects interact with Mappings defined in CRDs **exactly** as they would if the Ingress route rules had been specified with CRDs originally. - -For example, this Ingress resource routes traffic to `/foo/` to `service1`: - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: test-ingress -spec: - rules: - - http: - paths: - - path: /foo/ - backend: - serviceName: service1 - servicePort: 80 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: test-ingress-0-0 -spec: - hostname: '*' - prefix: /foo/ - service: service1:80 -``` - -This YAML will set up $productName$ to do canary routing where 50% of the traffic will go to `service1` and 50% will go to `service2`. - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: test-ingress -spec: - rules: - - http: - paths: - - path: /foo/ - backend: - serviceName: service1 - servicePort: 80 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: my-mapping -spec: - hostname: '*' - prefix: /foo/ - service: service2 -``` - -### The minimal Ingress - -An Ingress resource must provide at least some routes or a [default backend](https://kubernetes.io/docs/concepts/services-networking/ingress/#default-backend). The default backend provides for a simple way to direct all traffic to some upstream service: - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: test-ingress -spec: - backend: - serviceName: exampleservice - servicePort: 8080 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: test-ingress -spec: - hostname: '*' - prefix: / - service: exampleservice:8080 -``` - -### Name based virtual hosting with an Ambassador ID - -This Ingress resource will result in all requests to `foo.bar.com` going to `service1`, and requests to `bar.foo.com` going to `service2`: - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - getambassador.io/ambassador-id: externalid - name: name-virtual-host-ingress -spec: - rules: - - host: foo.bar.com - http: - paths: - - backend: - serviceName: service1 - servicePort: 80 - - host: bar.foo.com - http: - paths: - - backend: - serviceName: service2 - servicePort: 80 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: host-foo-mapping -spec: - ambassador_id: ['externalid'] - prefix: / - host: foo.bar.com - service: service1 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: host-bar-mapping -spec: - ambassador_id: ['externalid'] - prefix: / - host: bar.foo.com - service: service2 -``` - -Read more on the [Kubernetes documentation on name based virtual routing](https://kubernetes.io/docs/concepts/services-networking/ingress/#name-based-virtual-hosting). - -### TLS termination - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: tls-example-ingress -spec: - tls: - - hosts: - - sslexample.foo.com - secretName: testsecret-tls - rules: - - host: sslexample.foo.com - http: - paths: - - path: / - backend: - serviceName: service1 - servicePort: 80 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: sslexample-termination-context -spec: - hosts: - - sslexample.foo.com - secret: testsecret-tls ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: sslexample-mapping -spec: - host: sslexample.foo.com - prefix: / - service: service1 -``` - -Note that this shows TLS termination, not origination: the Ingress spec does not support origination. Read more on the [Kubernetes docs on TLS termination](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls). diff --git a/content/en/docs/3.4/topics/running/listener.md b/content/en/docs/3.4/topics/running/listener.md deleted file mode 100644 index 152e1b74..00000000 --- a/content/en/docs/3.4/topics/running/listener.md +++ /dev/null @@ -1,218 +0,0 @@ -# The `Listener` CRD - -The `Listener` CRD defines where, and how, $productName$ should listen for requests from the network, and which `Host` definitions should be used to process those requests. For further examples of how to use `Listener`, see [Configuring $productName$ Communications](../../../howtos/configure-communications). - -**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. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 # int32, port number on which to listen - protocol: HTTPS # HTTP, HTTPS, HTTPPROXY, HTTPSPROXY, TCP - securityModel: XFP # XFP (for X-Forwarded-Proto), SECURE, INSECURE - statsPrefix: example-listener # default depends on protocol; see below - l7Depth: 0 # int32 - hostBinding: - namespace: - from: SELF # SELF, ALL - selector: ... # Kubernetes label selector -``` - -| Element | Type | Definition | -| :------ | :--- | :--------- | -| `port` | `int32` | The network port on which $productName$ should listen. *Required.* | -| `protocol` | `enum`; see below | A high-level protocol type, like "HTTPS". *Exactly one of `protocol` and `protocolStack` must be supplied.* | -| `protocolStack` | array of `enum`; see below | A sequence of low-level protocols to layer together. *Exactly one of `protocol` and `protocolStack` must be supplied.* | -| `securityModel` | `enum`; see below | How does $productName$ decide whether requests here are secure? *Required.* | -| `statsPrefix` | `string`; see below | Under what name do statistics for this `Listener` appear? *Optional; default depends on protocol.* | -| `l7Depth` | `int32` | How many layer 7 load balancers are between the edge of the network and $productName$? *Optional; default is 0.*| -| `hostBinding` | `struct`, see below | Mechanism for determining which `Host`s will be associated with this `Listener`. *Required* | - -### `protocol` and `protocolStack` - -`protocol` is the **recommended** way to tell $productName$ that a `Listener` expects connections using a well-known protocol. When using `protocol`, `protocolStack` may not also be supplied. - -Valid `protocol` values are: - -| `protocol` | Description | -| :--------- | :---------- | -| `HTTP` | Cleartext-only HTTP. HTTPS is not allowed. | -| `HTTPS` | Either HTTPS or HTTP -- Envoy's TLS support can tell whether or not TLS is in use, and it will set `X-Forwarded-Proto` correctly for later decision-making. | -| `HTTPPROXY` | Cleartext-only HTTP, using the HAProxy `PROXY` protocol. | -| `HTTPSPROXY` | Either HTTPS or HTTP, using the HAProxy `PROXY` protocol. | -| `TCP` | TCP sessions without HTTP at all. You will need to use `TCPMapping`s to route requests for this `Listener`. | -| `TLS` | TLS sessions without HTTP at all. You will need to use `TCPMapping`s to route requests for this `Listener`. | - -### `securityModel` - -`securityModel` defines how the `Listener` will decide whether a request is secure or insecure: - -| `securityModel` | Description | -| :--------- | :---------- | -| `XFP` | Requests are secure if, and only if, `X-Forwarded-Proto` indicates HTTPS. This is common; see below. | -| `SECURE` | Requests are always secure. You might set this if your load balancer always terminates TLS for you, and you can trust the clients. | -| `INSECURE` | Requests are always insecure. You might set this for an HTTP-only `Listener`, or a `Listener` for clients that are expected to be hostile. | - -The `X-Forwarded-Proto` header mentioned above is meant to reflect the protocol the _original client_ -used to contact $productName$. When no layer 7 proxies are in use, Envoy will make certain that the -`X-Forwarded-Proto` header matches the wire protocol of the connection the client made to Envoy, -which allows $productName$ to trust `X-Forwarded-Proto` for routing decisions such as deciding to -redirect requests made using HTTP over to HTTPS for greater security. When using $productName$ as an -edge proxy or a typical API gateway, this is a desirable configuration; setting `securityModel` to -`XFP` makes this easy. - -When layer proxies _are_ in use, the `XFP` setting is often still desirable; however, you will also -need to set `l7Depth` to allow it to function. See below. - -`SECURE` and `INSECURE` are helpful for cases where something downstream of $productName$ should be -allowing only one kind of request to reach $productName$. For example, a `Listener` behind a load -balancer that terminates TLS and checks client certificates might use -`SecurityModel: SECURE`, then use `Host`s to reject insecure requests if one somehow -arrives. - -### `l7Depth` - -When layer 7 (L7) proxies are in use, the connection to $productName$ comes from the L7 proxy itself -rather than from the client. Examining the protocol and IP address of that connection is useless, and -instead you need to configure the L7 proxy to pass extra information about the client to $productName$ -using the `X-Forwarded-Proto` and `X-Forwarded-For` headers. - -However, if $productName$ always trusted `X-Forwarded-Proto` and `X-Forwarded-For`, any client could -use them to lie about itself to $productName$. As a security mechanism, therefore, you must _also_ -set `l7Depth` in the `Listener` to the number of trusted L7 proxies in front of $productName$. If -`l7Depth` is not set in the `Listener`, the `xff_num_trusted_hops` value from the `ambassador` `Module` -will be used. If neither is set, the default `l7Depth` is 0. - -When `l7Depth` is 0, any incoming `X-Forwarded-Proto` is stripped: Envoy always provides an -`X-Forwarded-Proto` matching the wire protocol of the incoming connection, so that `X-Forwarded-Proto` -can be trusted. When `l7Depth` is non-zero, `X-Forwarded-Proto` is accepted from the L7 proxy, and -trusted. The actual wire protocol in use from the L7 proxy to $productName$ is ignored. - -`l7Depth` also affects $productName$'s view of the client's source IP address, which is used as the -`remote_address` field when rate limiting, and for the `X-Envoy-External-Address` header: - -- When `l7Depth` is 0, $productName$ uses the IP address of the incoming connection. -- When `l7Depth` is some value N that is non-zero, the behavior is determined by the value of - `use_remote_address` in the `ambassador` `Module`: - - - When `use_remote_address` is true (the default) then the trusted client address will be the Nth - address from the right end of the `X-Forwarded-For` header. (If the XFF contains fewer than N - addresses, Envoy falls back to using the immediate downstream connection’s source address as a - trusted client address.) - - - When `use_remote_address` is false, the trusted client address is the (N+1)th address from the - right end of XFF. (If the XFF contains fewer than N+1 addresses, Envoy falls back to using the - immediate downstream connection’s source address as a trusted client address.) - - For more detailed examples of this interaction, refer to [Envoy's documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers.html#x-forwarded-for). - - -### `hostBinding` - -`hostBinding` specifies how this `Listener` should determine which `Host`s are associated with it: - -- `namespace.from` allows filtering `Host`s by the namespace of the `Host`: - - `namespace.from: SELF` accepts only `Host`s in the same namespace as the `Listener`. - - `namespace.from: ALL` accepts `Host`s in any namespace. -- `selector` accepts only `Host`s that has labels matching the selector. - -`hostBinding` is mandatory, and at least one of `namespace.from` and `selector` must be set. If both are set, both must match for a `Host` to be accepted. - -### `statsPrefix` - -$productName$ produces detailed [statistics](../statistics) which can be monitored in a variety of ways. Statistics have hierarchical names, and the `Listener` will cause a set of statistics to be logged under the name specified by `statsPrefix`. - -The default `statsPrefix` depends on the protocol for this `Listener`: - -- If the `Listener` speaks HTTPS, the default is `ingress-https`. -- Otherwise, if the `Listener` speaks HTTP, the default is `ingress-http`. -- Otherwise, if the `Listener` speaks TLS, the default is `ingress-tls-$port`. -- Otherwise, the default is `ingress-$port`. - -Note that it doesn't matter whether you use `protocol` or `protocolStack`: what matters is what protocol is actually configured. Also note that the default doesn't take the HAProxy `PROXY` protocol into account. - -Some examples: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 - protocol: HTTPS - ... -``` - -will use a `statsPrefix` of `ingress-https`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 - protocol: TCP - ... -``` - -will use `statsPrefix` of `ingress-8080`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 - protocol: HTTPSPROXY - statsPrefix: proxy-8080 - ... -``` - -would also use `ingress-https`, but it explicitly overrides `statsPrefix` to `proxy-8080`. - -For complete information on which statistics will appear for the `Listener`, see [the Envoy listener statistics documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/listeners/stats.html). Some important statistics include - -| Statistic name | Type | Description | -| :-----------------------------------------------| :-------- | :-------------------------------- | -| `listener.$statsPrefix.downstream_cx_total` | Counter | Total connections | -| `listener.$statsPrefix.downstream_cx_active` | Gauge | Total active connections | -| `listener.$statsPrefix.downstream_cx_length_ms` | Histogram | Connection length in milliseconds | - -### `protocolStack` - -**`protocolStack` is not recommended if you can instead use `protocol`.** - -Where `protocol` allows configuring the `Listener` to use well-known protocol stacks, `protocolStack` allows configuring exactly which protocols will be layered together. If `protocol` allows what you need, it is safer to use `Protocol` than to risk having the stack broken with an incorrect `protocolStack`. - -The possible stack elements are: - -| `ProtocolStack` Element | Description | -| :---------------------- | :---------- | -| `HTTP` | Cleartext-only HTTP; must be layered with `TLS` for HTTPS | -| `PROXY` | The HAProxy `PROXY` protocol | -| `TLS` | TLS | -| `TCP` | Raw TCP | - -`protocolStack` supplies a list of these elements to describe the protocol stack. **Order matters.** Some examples: - -| `protocolStack` | Description | -| :-------------- | :---------- | -| [ `HTTP`, `TCP` ] | Cleartext-only HTTP, exactly equivalent to `protocol: HTTP`. | -| [ `TLS`, `HTTP`, `TCP` ] | HTTPS or HTTP, exactly equivalent to `protocol: HTTPS`. | -| [ `PROXY`, `TLS`, `TCP` ] | The `PROXY` protocol, wrapping `TLS` _afterward_, wrapping raw TCP. This isn't equivalent to any `protocol` setting, and may be nonsensical. | - -## Examples - -For further examples of how to use `Listener`, see [Configuring $productName$ to Communicate](../../../howtos/configure-communications). diff --git a/content/en/docs/3.4/topics/running/load-balancer.md b/content/en/docs/3.4/topics/running/load-balancer.md deleted file mode 100644 index 987a910b..00000000 --- a/content/en/docs/3.4/topics/running/load-balancer.md +++ /dev/null @@ -1,209 +0,0 @@ -# Load balancing - -Load balancing configuration can be set for all $productName$ mappings in the [`ambassador` `Module`](../ambassador), or set per [`Mapping`](../../using/mappings). If nothing is set, simple round robin balancing is used via Kubernetes services. - -To use advanced load balancing, you must first configure a [resolver](../resolvers) that supports advanced load balancing (e.g., the Kubernetes Endpoint Resolver or Consul Resolver). Once a resolver is configured, you can use the `load_balancer` attribute. The following fields are supported: - -```yaml -load_balancer: - policy: -``` - -Supported load balancer policies: - -- `round_robin` -- `least_request` -- `ring_hash` -- `maglev` - -For more information on the different policies and the implications, see [load balancing strategies in Kubernetes](https://blog.getambassador.io/load-balancing-strategies-in-kubernetes-l4-round-robin-l7-round-robin-ring-hash-and-more-6a5b81595d6c). - -## Round robin -When `policy` is set to `round_robin`, $productName$ discovers healthy endpoints for the given mapping, and load balances the incoming L7 requests with round robin scheduling. To specify this: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - resolver: my-resolver - load_balancer: - policy: round_robin -``` - -or, per mapping: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - resolver: my-resolver - hostname: '*' - load_balancer: - policy: round_robin -``` - -Note that load balancing may not appear to be "even" due to Envoy's threading model. For more details, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/faq/load_balancing/concurrency_lb). - -## Least request - -When `policy` is set to `least_request`, $productName$ discovers healthy endpoints for the given mapping, and load balances the incoming L7 requests to the endpoint with the fewest active requests. To specify this: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - resolver: my-resolver - load_balancer: - policy: least_request -``` - -or, per mapping: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend/ -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: least_request -``` - -## Sticky sessions / session affinity - -Configuring sticky sessions makes $productName$ route requests to a specific pod providing your service in a given session. One pod serves all requests from a given session, eliminating the need for session data to be transferred between pods. $productName$ lets you configure session affinity based on the following parameters in an incoming request: - -- Cookie -- Header -- Source IP - -**NOTE:** $productName$ supports sticky sessions using two load balancing policies, `ring_hash` and `maglev`. - -### Cookie - -```yaml -load_balancer: - policy: ring_hash - cookie: - name: - ttl: - path: -``` - -If the cookie you wish to set affinity on is already present in incoming requests, then you only need the `cookie.name` field. However, if you want $productName$ to generate and set a cookie in response to the first request, then you need to specify a value for the `cookie.ttl` field which generates a cookie with the given expiration time. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - hostname: '*' - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - cookie: - name: sticky-cookie - ttl: 60s -``` - -### Header - -```yaml -load_balancer: - policy: ring_hash - header:
-``` - -$productName$ allows header based session affinity if the given header is present on incoming requests. - -Example: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - header: STICKY_HEADER -``` - -#### Source IP - -```yaml -load_balancer: - policy: ring_hash - source_ip: -``` - -$productName$ allows session affinity based on the source IP of incoming requests. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - source_ip: true -``` - -Load balancing can be configured both globally, and overridden on a per mapping basis. The following example configures the default load balancing policy to be round robin, while using header-based session affinity for requests to the `/backend/` endpoint of the quote application: - -Load balancing can be configured both globally, and overridden on a per mapping basis. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - resolver: my-resolver - load_balancer: - policy: round_robin -``` - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - header: STICKY_HEADER -``` diff --git a/content/en/docs/3.4/topics/running/resolvers.md b/content/en/docs/3.4/topics/running/resolvers.md deleted file mode 100644 index 1ace9a86..00000000 --- a/content/en/docs/3.4/topics/running/resolvers.md +++ /dev/null @@ -1,128 +0,0 @@ -# Service discovery and resolvers - -Service discovery is how cloud applications and their microservices are located on the network. In a cloud environment, services are ephemeral, existing only as long as they are needed and in use, so a real-time service discovery mechanism is required. $productName$ uses information from service discovery to determine where to route incoming requests. - -## $productName$ support for service discovery - -$productName$ supports different mechanisms for service discovery. These mechanisms are: - -* Kubernetes service-level discovery (default). -* Kubernetes endpoint-level discovery. -* Consul endpoint-level discovery. - -### Kubernetes service-level discovery - -By default, $productName$ uses Kubernetes DNS and service-level discovery. In a `Mapping` resource, specifying `service: foo` will prompt $productName$ to look up the DNS address of the `foo` Kubernetes service. Traffic will be routed to the `foo` service. Kubernetes will then load balance that traffic between multiple pods. For more details on Kubernetes networking and how this works, see our blog post on [Session affinity, load balancing controls, gRPC-Web, and $productName$](https://blog.getambassador.io/session-affinity-load-balancing-controls-grpc-web-and-ambassador-0-52-2b916b396d0c). - -### Kubernetes endpoint-level discovery - -$productName$ can also watch Kubernetes endpoints. This bypasses the Kubernetes service routing layer and enables the use of advanced load balancing controls such as session affinity and maglev. For more details, see the [load balancing reference](../load-balancer). - -### Consul endpoint-level discovery - -$productName$ natively integrates with [Consul](https://www.consul.io) for endpoint-level service discovery. In this mode, $productName$ obtains endpoint information from Consul. One of the primary use cases for this architecture is in hybrid cloud environments that run a mixture of Kubernetes services as well as VMs, as Consul can serve as the single global registry for all services. - -## The Resolver resource - -The `Resolver` resource is used to configure the discovery service strategy for $productName$. - -### The Kubernetes service resolver - -The Kubernetes Service Resolver configures $productName$ to use Kubernetes services. If no resolver is specified, this behavior is the default. When this resolver is used, the `service.namespace` value from a `Mapping` is handed to the Kubernetes cluster's DNS resolver to determine where requests are sent. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: KubernetesServiceResolver -metadata: - name: kubernetes-service -``` - -### The Kubernetes endpoint resolver - -The Kubernetes Endpoint Resolver configures $productName$ to resolve Kubernetes endpoints. This enables the use of more a [advanced load balancing configuration](../load-balancer). When this resolver is used, the endpoints for the `service` defined in a `Mapping` are resolved and used to determine where requests are sent. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: KubernetesEndpointResolver -metadata: - name: endpoint -``` - -### The Consul resolver - -The Consul Resolver configures $productName$ to use Consul for service discovery. When this resolver is used, the `service` defined in a `Mapping` is passed to Consul, along with the datacenter specified, to determine where requests are sent. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: ConsulResolver -metadata: - name: consul-dc1 -spec: - address: consul-server.default.svc.cluster.local:8500 - datacenter: dc1 -``` -- `address`: The fully-qualified domain name or IP address of your Consul server. This field also supports environment variable substitution. -- `datacenter`: The Consul data center where your services are registered - -You may want to use an environment variable if you're running a Consul agent on each node in your cluster. In this setup, you could do the following: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: ConsulResolver -metadata: - name: consul-dc1 -spec: - address: "${HOST_IP}" - datacenter: dc1 -``` - -and then add the `HOST_IP` environment variable to your Kubernetes deployment: - -```yaml -containers: - - name: example - image: docker.io/datawire/ambassador:$version$ - env: - - name: HOST_IP - valueFrom: - fieldRef: - fieldPath: status.hostIP -``` - -## Using resolvers - -Once a resolver is defined, you can use them in a given `Mapping`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: "*" - prefix: /backend/ - service: quote - resolver: endpoint - load_balancer: - policy: round_robin ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: bar -spec: - hostname: "*" - prefix: /bar/ - service: https://bar:9000 - tls: client-context - resolver: consul-dc1 - load_balancer: - policy: round_robin -``` - -The YAML configuration above will configure $productName$ to use Kubernetes Service Discovery to route to the Consul Service Discovery to route to the `bar` service on requests with `prefix: /bar/`. diff --git a/content/en/docs/3.4/topics/running/running.md b/content/en/docs/3.4/topics/running/running.md deleted file mode 100644 index a28b0cb5..00000000 --- a/content/en/docs/3.4/topics/running/running.md +++ /dev/null @@ -1,338 +0,0 @@ -# Running and deployment - -This section is intended for operators running $productName$, and covers various aspects of deploying and configuring the $productName$ in production. - -## $productName$ and Kubernetes - -$productName$ relies on Kubernetes for reliability, availability, and scalability. This means that features such as Kubernetes readiness and liveness probes, rolling updates, and the Horizontal Pod Autoscaling should be utilized to manage $productName$. - -## Default configuration - -The default configuration of $productName$ includes default [resource limits](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-requests-and-limits-of-pod-and-container), as well as [readiness and liveness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/). These values should be adjusted for your specific environment. - -## Running as non-root - -Starting with $productName$ 0.35, we support running $productName$ as non-root. This is the recommended configuration, and will be the default configuration in future releases. We recommend you configure $productName$ to run as non-root as follows: - -* Have Kubernetes run $productName$ as non-root. This may happen by default (e.g., OpenShift) or you can set a `securityContext` in your Deployment as shown below in this abbreviated example: - -```yaml ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: ambassador -spec: - replicas: 1 - selector: - matchLabels: - service: ambassador - template: - metadata: - labels: - service: ambassador - spec: - containers: - image: docker.io/datawire/aes:$version$ - name: ambassador - restartPolicy: Always - securityContext: - runAsUser: 8888 - serviceAccountName: ambassador -``` - -* Set the `service_port` element in the `ambassador Module` to 8080 (cleartext) or 8443 (TLS). This is the port that $productName$ will use to listen to incoming traffic. Note that any port number above 1024 will work; $productName$ will use 8080/8443 as its defaults in the future. - -* Make sure that incoming traffic to $productName$ is configured to route to the `service_port`. If you're using the default $productName$ configuration, this means configuring the `targetPort` to point to the `service_port` above. - -* If you are using `redirect_cleartext_from`, change the value of this field to point to your cleartext port (e.g., 8080) and set `service_port` to be your TLS port (e.g., 8443). - -## Changing the configuration directory - -While running, $productName$ needs to use a directory within its container for generated configuration data. Normally this is `/ambassador`, but in some situations - especially if running as non-root - it may be necessary to change to a different directory. To do so, set the environment variable `AMBASSADOR_CONFIG_BASE_DIR` to the full pathname of the directory to use, as shown below in this abbreviated example: - -```yaml -env: -- name: AMBASSADOR_CONFIG_BASE_DIR - value: /tmp/ambassador-config -``` - -With `AMBASSADOR_CONFIG_BASE_DIR` set as above, $productName$ will create and use the directory `/tmp/ambassador-config` for its generated data. (Note that, while the directory will be created if it does not exist, attempts to turn an existing file into a directory will fail.) - -## Running as DaemonSet - -$productName$ can be deployed as a DaemonSet to have one pod per node in a Kubernetes cluster. This setup is especially helpful when you have a Kubernetes cluster running on a private cloud. - -* In an ideal example scenario, you are running containers on Kubernetes alongside with your non-containerized applications running exposed via VIP using BIG-IP or similar products. In such cases, east-west traffic is routed based on iRules to certain a set of application pools consisting of application or web servers. In this setup, alongside traditional application servers, two or more $productName$ pods can also be part of the application pools. In case of failure there is at least one $productName$ pod available to BIG-IP that can take care of routing traffic to the Kubernetes cluster. - -* In manifest files `kind: Deployment` needs to be updated to `kind: DaemonSet` and `replicas` should be removed in `spec` section. - -## Namespaces - -$productName$ supports multiple namespaces within Kubernetes. To make this work correctly, you need to set the `AMBASSADOR_NAMESPACE` environment variable in $productName$'s container. By far the easiest way to do this is using Kubernetes' downward API (this is included in the YAML files from `getambassador.io`): - -```yaml -env: -- name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace -``` - -Given that `AMBASSADOR_NAMESPACE` is set, $productName$ [`Mappings`](../../using/mappings) can operate within the same namespace, or across namespaces. **Note well** that `Mappings` will have to explicitly include the namespace with the service to cross namespaces; see the [`Mapping`](../../using/mappings) documentation for more information. - -If you want $productName$ to only work within a single namespace, set `AMBASSADOR_SINGLE_NAMESPACE` as an environment variable. - -```yaml -env: -- name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace -- name: AMBASSADOR_SINGLE_NAMESPACE - value: "true" -``` - -With $productName$, if you set `AMBASSADOR_NAMESPACE` or `AMBASSADOR_SINGLE_NAMESPACE`, set it in the deployment container. - -If you want to set a certificate for your `TLScontext` from another namespace, you can use the following: - -```yaml -env: -- name: AMBASSADOR_SINGLE_NAMESPACE - value: "YES" -- name: AMBASSADOR_CERTS_SINGLE_NAMESPACE - value: "YES" -- name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - apiVersion: v1 - fieldPath: metadata.namespace -``` - -## `AMBASSADOR_ID` - -$productName$ supports running multiple $productNamePlural$ in the same cluster, without restricting a given $productName$ to a single namespace. This is done with the `AMBASSADOR_ID` setting. In the `ambassador Module`, set the `ambassador_id`, e.g., - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - ambassador_id: [ "ambassador-1" ] - config: - ... -``` - -Then, assign each $productName$ pod a unique `AMBASSADOR_ID` with the environment variable as part of your deployment: - -```yaml -env: -- name: AMBASSADOR_ID - value: ambassador-1 -``` - -With $productName$, if you set `AMBASSADOR_ID`, you will need to set it in the deployment container. - -$productName$ will then only use YAML objects that include an appropriate `ambassador_id` attribute. For example, if $productName$ is given the ID `ambassador-1` as above, only the first two YAML objects below will be used: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-used -spec: - ambassador_id: [ "ambassador-1" ] - prefix: /demo1/ - service: demo1 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-used-2 -spec: - ambassador_id: [ "ambassador-1", "ambassador-2" ] - prefix: /demo2/ - service: demo2 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-skipped -spec: - prefix: /demo3/ - service: demo3 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-skipped-2 -spec: - ambassador_id: [ "ambassador-2" ] - prefix: /demo4/ - service: demo4 -``` - -`ambassador_id` is always a list, and may (as shown in `mapping-used-2` above) include multiple IDs to allow a given object in the configuration for multiple $productName$ instances. In this case, `mapping-used-2` will be included in the configuration for `ambassador-1` and also for `ambassador-2`. - -**Note well that _any_ $productName$ configuration resource can have an `ambassador_id` included** so, for example, it is _fully supported_ to use `ambassador_id` to qualify the `ambassador Module`, `TLSContext`, and `AuthService` objects. You will need to set `ambassador_id` in all resources you want to use for $productName$. - -If no `AMBASSADOR_ID` is assigned to an $productName$, it will use the ID `default`. If no `ambassador_id` is present in a YAML object, it will also use the ID `default`. - -## `AMBASSADOR_ENVOY_BASE_ID` - -$productName$ supports running side-by-side with other envoy-based projects in a single pod. An example of this is running with an `istio` sidecar. This is done with the `AMBASSADOR_ENVOY_BASE_ID` environment variable as part of your deployment: - -```yaml -env: -- name: AMBASSADOR_ENVOY_BASE_ID - value: 1 -``` - -If no `AMBASSADOR_ENVOY_BASE_ID` is provided then it will use the ID `0`. For more information on the Envoy base-id option please see the [Envoy command line documentation](https://www.envoyproxy.io/docs/envoy/latest/operations/cli.html?highlight=base%20id#cmdoption-base-id). - -## `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. - -## `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. - -## `AMBASSADOR_LEGACY_MODE` - -Setting `AMBASSADOR_LEGACY_MODE` to `true` will result in $productName$ disabling certain features -and reverting to older codepaths which may be better preserve certain older behaviors. Legacy mode -currently has the following effects: - -- $productName$ will switch back to the $productName$ 1.6 input-resource validator (which can significantly -increase configuration latency for $productName$ installations with many resources). -- $productName$ will use the shell boot sequence that was the default up through 1.9.1, rather than the Golang boot sequence that became the default in 1.10.0. -- `AMBASSADOR_FAST_RECONFIGURE` (see below) is not supported in legacy mode. - -## `AMBASSADOR_FAST_RECONFIGURE` - -Setting `AMBASSADOR_FAST_RECONFIGURE` to "true" enables incremental reconfiguration. When enabled, $productName$ will track deltas from one configuration to the next and recalculate only what is necessary to follow the change. When disabled (the default), $productName$ will recompute the entire configuration at every change. - -**`AMBASSADOR_FAST_RECONFIGURE` is not supported when `AMBASSADOR_LEGACY_MODE` is active.** - -## Configuration from the filesystem - -If desired, $productName$ can be configured from YAML files in the directory `$AMBASSADOR_CONFIG_BASE_DIR/ambassador-config` (by default, `/ambassador/ambassador-config`, which is empty in the images built by Datawire). You could volume mount an external configuration directory here, for example, or use a custom Dockerfile to build configuration directly into a Docker image. - -Note well that while $productName$ will read its initial configuration from this directory, configuration loaded from Kubernetes annotations will _replace_ this initial configuration. If this is not what you want, you will need to set the environment variable `AMBASSADOR_NO_KUBEWATCH` so that $productName$ will not try to update its configuration from Kubernetes resources. - -Also note that the YAML files in the configuration directory must contain the $productName$ resources, not Kubernetes resources with annotations. - -## Log levels and debugging - -The $OSSproductName$ and $AESproductName$ support more verbose debugging levels. If using $OSSproductName$, the [diagnostics](../diagnostics) service has a button to enable debug logging. Be aware that if you're running $productName$ on multiple pods, the debug log levels are not enabled for all pods -- they are configured on a per-pod basis. - -If using $AESproductName$, you can 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 format - -By default, $productName$ writes its own logs in a plain text format. To produce logs as JSON instead, set the `AMBASSADOR_JSON_LOGGING` environment variable: - -```yaml -env: -- name: AMBASSADOR_JSON_LOGGING - value: "true" -``` - -## Port assignments - -$productName$ uses some TCP ports in the range 8000-8499 internally, as well as port 8877. Third-party software integrating with $productName$ should not use ports in this range on the $productName$ pod. - -## $productName$ update checks (Scout) - -$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 $productName$ will run regardless of the status of Scout (i.e., our uptime has zero impact on your uptime.) - -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. - -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. - -Unless disabled, $productName$ will also report the following anonymized information back to Datawire: - -| Attribute | Type | Description | -| :------------------------ | :---- | :------------------------ | -| `cluster_count` | int | total count of clusters in use | -| `cluster_grpc_count` | int | count of clusters using GRPC upstream | -| `cluster_http_count` | int | count of clusters using HTTP or HTTPS upstream | -| `cluster_routing_envoy_rh_count` | int | count of clusters routing using Envoy `ring_hash` | -| `cluster_routing_envoy_maglev_count` | int | count of clusters routing using Envoy `maglev` | -| `cluster_routing_envoy_lr_count` | int | count of clusters routing using Envoy `least_request` | -| `cluster_routing_envoy_rr_count` | int | count of clusters routing using Envoy `round_robin` | -| `cluster_routing_kube_count` | int | count of clusters routing using Kubernetes | -| `cluster_tls_count` | int | count of clusters originating TLS | -| `custom_ambassador_id` | bool | has the `ambassador_id` been changed from 'default'? | -| `custom_listener_port` | bool | has the listener port been changed from 80/443? | -| `diagnostics` | bool | is the diagnostics service enabled? | -| `endpoint_grpc_count` | int | count of endpoints to which $productName$ will originate GRPC | -| `endpoint_http_count` | int | count of endpoints to which $productName$ will originate HTTP or HTTPS | -| `endpoint_routing` | bool | is endpoint routing enabled? | -| `endpoint_routing_envoy_rh_count` | int | count of endpoints being routed using Envoy `ring_hash` | -| `endpoint_routing_envoy_maglev_count` | int | count of endpoints being routed using Envoy `maglev` | -| `endpoint_routing_envoy_lr_count` | int | count of endpoints being routed using Envoy `least_request` | -| `endpoint_routing_envoy_rr_count` | int | count of endpoints being routed using Envoy `round_robin` | -| `endpoint_routing_kube_count` | int | count of endpoints being routed using Kubernetes | -| `endpoint_tls_count` | int | count of endpoints to which $productName$ will originate TLS | -| `extauth` | bool | is extauth enabled? | -| `extauth_allow_body` | bool | will $productName$ send the body to extauth? | -| `extauth_host_count` | int | count of extauth hosts in use | -| `extauth_proto` | str | extauth protocol in use ('http', 'grpc', or `null` if not active) | -| `group_canary_count` | int | count of Mapping groups that include more than one Mapping | -| `group_count` | int | total count of Mapping groups in use (length of the route table) | -| `group_header_match_count` | int | count of groups using header matching (including `host` and `method`) | -| `group_host_redirect_count` | int | count of groups using host_redirect | -| `group_host_rewrite_count` | int | count of groups using host_rewrite | -| `group_http_count` | int | count of HTTP Mapping groups | -| `group_precedence_count` | int | count of groups that explicitly set the precedence of the group | -| `group_regex_header_count` | int | count of groups using regex header matching | -| `group_regex_prefix_count` | int | count of groups using regex prefix matching | -| `group_resolver_consul` | int | count of groups using the Consul resolver | -| `group_resolver_kube_endpoint` | int | count of groups using the Kubernetes endpoint resolver | -| `group_resolver_kube_service` | int | count of groups using the Kubernetes service resolver | -| `group_shadow_count` | int | count of groups using shadows | -| `group_shadow_weighted_count` | int | count of groups using shadows but not shadowing all traffic | -| `group_tcp_count` | int | count of TCP Mapping groups | -| `host_count` | int | count of Host resources in use | -| `k8s_ingress_class_count` | int | count of IngressClass resources in use | -| `k8s_ingress_count` | int | count of Ingress resources in use | -| `listener_count` | int | count of active listeners (1 unless `redirect_cleartext_from` or TCP Mappings are in use) | -| `liveness_probe` | bool | are liveness probes enabled? | -| `managed_by` | string | tool that manages the $productName$ deployment, if any (e.g. helm, edgectl, etc.) | -| `mapping_count` | int | count of Mapping resources in use | -| `ratelimit` | bool | is rate limiting in use? | -| `ratelimit_custom_domain` | bool | has the rate limiting domain been changed from 'ambassador'? | -| `ratelimit_data_plane_proto` | bool | is rate limiting using the data plane proto? | -| `readiness_probe` | bool | are readiness probes enabled? | -| `request_4xx_count` | int | lower bound for how many requests have gotten a 4xx response | -| `request_5xx_count` | int | lower bound for how many requests have gotten a 5xx response | -| `request_bad_count` | int | lower bound for how many requests have failed (either 4xx or 5xx) | -| `request_elapsed` | float | seconds over which the request_ counts are valid | -| `request_hr_elapsed` | string | human-readable version of `request_elapsed` (e.g. "3 hours 35 minutes 20 seconds" | -| `request_ok_count` | int | lower bound for how many requests have succeeded (not a 4xx or 5xx) | -| `request_total_count` | int | lower bound for how many requests were handled in total | -| `statsd` | bool | is StatsD enabled? | -| `server_name` | bool | is the `server_name` response header overridden? | -| `service_resource_total` | int | total count of service resources loaded from all discovery sources | -| `tls_origination_count` | int | count of TLS origination contexts | -| `tls_termination_count` | int | count of TLS termination contexts | -| `tls_using_contexts` | bool | are new TLSContext resources in use? ? | -| `tls_using_module` | bool |is the old TLS module in use | -| `tracing` | bool | is tracing in use? | -| `tracing_driver` | str | tracing driver in use ('zipkin', 'lightstep', 'datadog', or `null` if not active) | -| `use_proxy_proto` | bool | is the `PROXY` protocol in use? | -| `use_remote_address` | bool | is $productName$ honoring remote addresses? | -| `x_forwarded_proto_redirect` | bool | is $productName$ redirecting based on `X-Forwarded-Proto`? | -| `xff_num_trusted_hops` | int | what is the count of trusted hops for `X-Forwarded-For`? | - -The `request_*` counts are always incremental: they contain only information about the last `request_elapsed` seconds. Additionally, they only provide a lower bound -- notably, if an $productName$ pod crashes or exits, no effort is made to ship out a final update, so it's very easy for counts to never be reported. - -To completely disable feature reporting, set the environment variable `AMBASSADOR_DISABLE_FEATURES` to any non-empty value. diff --git a/content/en/docs/3.4/topics/running/scaling.md b/content/en/docs/3.4/topics/running/scaling.md deleted file mode 100644 index 22fa743e..00000000 --- a/content/en/docs/3.4/topics/running/scaling.md +++ /dev/null @@ -1,194 +0,0 @@ -# Performance and scaling $productName$ - -Scaling any cloud native application is inherently domain specific, however the content here -reflects common issues, tips, and tricks that come up frequently. - -## Performance dimensions - -The performance of $productName$'s control plane can be characterized along a number of -different dimensions: - - - The number of `TLSContext` resources. - - The number of `Host` resources. - - The number of `Mapping` resources per `Host` resource. - - The number of `Mapping` resources that will span all `Host` resources (either because they're using `host_regex`, or because they're using `hostname: "*"`). - -If your application involves a larger than average number of any of the above resources, you may -find yourself in need of some of the content in this section. - -## Mysterious pod restarts (aka pushing the edge of the envelope) - -Whether your application is growing organically or whether you are deliberately scale testing, it's -helpful to recognize how $productName$ behaves as it reaches the edge of its performance -envelope along any of these dimensions. - -As $productName$ approaches the edge of its performance envelope, it will often manifest as -mysterious pod restarts triggered by Kubernetes. This does not always mean there is a problem, it -could just mean you need to tune some of the resource limits set in your deployment. When it comes -to scaling, Kubernetes will generally kill an $productName$ pod for one of two reasons: exceeding -memory limits or failed liveness/readiness probes. See the [Memory Limits](#memory-limits), -[Liveness Probes](#liveness-probes), and [Readiness Probes](#readiness-probes) -sections for more on how to cope with these situations. - -## Memory limits - -$productName$ can grow in memory usage and be killed by Kubernetes if it exceeds the limits -defined in its pod spec. When this happens it is confusing and difficult to catch because the only -indication that this has occurred is the pod transitioning momentarily into the `OOMKilled` -state. The only way to actually observe this is if you are lucky enough to be running the following -command (or have similar monitoring configured) when $productName$ gets `OOMKilled`: - -``` - kubectl get pods -n ambassador -w -``` - -In order to take the luck out of the equation, $productName$ will periodically log its -memory usage so you can see in the logs if memory limits might be a problem and require adjustment: - -``` -2020/11/26 22:35:20 Memory Usage 0.56Gi (28%) - PID 1, 0.22Gi: busyambassador entrypoint - PID 14, 0.04Gi: /usr/bin/python /usr/bin/diagd /ambassador/snapshots /ambassador/bootstrap-ads.json /ambassador/envoy/envoy.json --notices /ambassador/notices.json --port 8004 --kick kill -HUP 1 - PID 16, 0.12Gi: /ambassador/sidecars/amb-sidecar - PID 37, 0.07Gi: /usr/bin/python /usr/bin/diagd /ambassador/snapshots /ambassador/bootstrap-ads.json /ambassador/envoy/envoy.json --notices /ambassador/notices.json --port 8004 --kick kill -HUP 1 - PID 48, 0.08Gi: envoy -c /ambassador/bootstrap-ads.json --base-id 0 --drain-time-s 600 -l error -``` - -In general you should try to keep $productName$'s memory usage below 50% of the pod's limit. This may -seem like a generous safety margin, but when reconfiguration occurs, $productName$ requires additional -memory to avoid disrupting active connections. At each reconfiguration, $productName$ keeps around the -old version for the duration of the configured drain time. See -[AMBASSADOR_DRAIN_TIME](#ambassador_drain_time) for more details on how to tune this -behavior. - -$productName$'s exact memory usage depends on (among other things) how many `Host` and -`Mapping` resources are defined in your cluster. If this number has grown over time, you may need to -increase the memory limit defined in your deployment. - -## Liveness probes - -$productName$ defines the `/ambassador/v0/check_alive` endpoint on port `8877` for use with Kubernetes -liveness probes. See the Kubernetes documentation for more details on [HTTP liveness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-a-liveness-http-request). - -Kubernetes will restart the $productName$ pod if it fails to get a 200 result from the endpoint. If -this happens it won't necessarily show up in an easily recognizable way in the pod logs. You can -look for Kubernetes events to see if this is happening. Use `kubectl describe pod -n ambassador` or -`kubectl get events -n ambassador` or equivalent. - -The purpose of liveness probes is to rescue an $productName$ instance that is wedged, however if -liveness probes are too sensitive they can take out $productName$ instances that are functioning -normally. This is more prone to happen as the number of $productName$ inputs increase. The -`timeoutSeconds` and `failureThreshold` fields of the $productName$ deployment's liveness Probe -determines how tolerant Kubernetes is with its probes. If you observe pod restarts along with -`Unhealthy` events, try tuning these fields upwards from their default values. See the Kubernetes documentation for more details on [tuning probes](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#probe-v1-core). - -Note that whatever changes you make to $productName$'s liveness probes should most likely be made to -its readiness probes also. - -## Readiness probes - -$productName$ defines the `/ambassador/v0/check_ready` endpoint on port `8877` for use with Kubernetes -readiness probes. See the Kubernetes documentation for more details on [readiness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-readiness-probes). - -Kubernetes uses readiness checks to prevent traffic from going to pods that are not ready to handle -requests. The only time $productName$ cannot usefully handle requests is during initial startup when it -has not yet loaded all the routing information from Kubernetes and/or consul. During this bootstrap -period there is no guarantee $productName$ would know where to send a given request. The `check_ready` -endpoint will only return 200 when all routing information has been loaded. After the initial -bootstrap period it behaves identically to the `check_alive` endpoint. - -Generally $productName$'s readiness probes should be configured with the same settings as its liveness -probes. - -## `AMBASSADOR_FAST_RECONFIGURE` and `AMBASSADOR_LEGACY_MODE` flags - -`AMBASSADOR_FAST_RECONFIGURE` is a feature flag that enables a higher performance implementation of -the code $productName$ uses to validate and generate envoy configuration. It will eventually be enabled -by default, but if you are experiencing performance problems you should try setting -`AMBASSADOR_FAST_RECONFIGURE` to `true` to see if this helps. - -`AMBASSADOR_LEGACY_MODE` is **not** recommended when performance is critical. - -## `AMBASSADOR_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. - -## Unconstrained Mappings with many hosts - -When working with a large number of `Host` resources, it's important to understand the impact of -unconstrained `Mapping`s. An unconstrained `Mapping` is one that is not restricted to a specific -`Host`. Such a `Mapping` will create a route for all of your `Host`s. If this is what you want then -it is the appropriate thing to do, however if you do not intend to do this, then you can end up with -many more routes than you had intended and this can adversely impact performance. - -## Inspecting $productName$ performance - -$productName$ internally tracks a number of key performance indicators. You can inspect these via the -debug endpoint at `localhost:8877/debug`. Note that the `AMBASSADOR_FAST_RECONFIGURE` flag needs to -be set to `"true"` for this endpoint to be present: - -``` -$ kubectl exec -n ambassador -it ${POD} curl localhost:8877/debug -{ - "timers": { - # These two timers track how long it takes to respond to liveness and readiness probes. - "check_alive": "7, 45.411495ms/61.85999ms/81.358927ms", - "check_ready": "7, 49.951304ms/61.976205ms/86.279038ms", - - # These two timers track how long we spend updating our in-memory snapshot when our Kubernetes - # watches tell us something has changed. - "consulUpdate": "0, 0s/0s/0s", - "katesUpdate": "3382, 28.662µs/102.784µs/95.220222ms", - - # These timers tell us how long we spend notifying the sidecars if changed input. This - # includes how long the sidecars take to process that input. - "notifyWebhook:diagd": "2, 1.206967947s/1.3298432s/1.452718454s", - "notifyWebhooks": "2, 1.207007216s/1.329901037s/1.452794859s", - - # This timer tells us how long we spend parsing annotations. - "parseAnnotations": "2, 21.944µs/22.541µs/23.138µs", - - # This timer tells us how long we spend reconciling changes to consul inputs. - "reconcileConsul": "2, 50.104µs/55.499µs/60.894µs", - - # This timer tells us how long we spend reconciling secrets related changes to $productName$ - # inputs. - "reconcileSecrets": "2, 18.704µs/20.786µs/22.868µs" - }, - "values": { - "envoyReconfigs": { - "times": [ - "2020-11-06T13:13:24.218707995-05:00", - "2020-11-06T13:13:27.185754494-05:00", - "2020-11-06T13:13:28.612279777-05:00" - ], - "staleCount": 2, - "staleMax": 0, - "synced": true - }, - "memory": "39.73Gi of Unlimited (0%)" - } -} -``` - -## Running profiles - -$productName$ exposes endpoints at `localhost:8877/debug/pprof` to run Golang profiles to aid in live debugging. The endpoints are equivalent to those found in the [http/pprof](https://pkg.go.dev/net/http/pprof) package. `/debug/pprof/` returns an HTML page listing the available profiles. - -The following are the different types of profiles you can run: - -| Profile | Function | -| :------- | :-------- | -| /debug/pprof/allocs | Returns a sampling of all past memory allocations. | -| /debug/pprof/block | Returns stack traces of goroutines that led to blocking on sychronization primitives. | -| /debug/pprof/cmdline | Returns the command line that was invoked by the current program. | -| /debug/pprof/goroutine | Returns stack traces of all current goroutines. | -| /debug/pprof/heap | Returns a sampling of memory allocations of live objects. | -| /debug/pprof/mutex | Returns stack traces of goroutines holding contended mutexes. | -| /debug/pprof/profile | Returns pprof-formatted cpu profile. You can specify the duration using the seconds `GET` parameter. The default duration is 30 seconds. | -| /debug/pprof/symbol | Returns the program counters listed in the request. | -| /debug/pprof/threadcreate | Returns stack traces that led to creation of new OS threads. | -| /debug/pprof/trace | Returns the execution trace in binary form. You can specify the duration using the seconds `GET` parameter. The default duration is 1 second. | diff --git a/content/en/docs/3.4/topics/running/services/auth-service.md b/content/en/docs/3.4/topics/running/services/auth-service.md deleted file mode 100644 index adfb77e4..00000000 --- a/content/en/docs/3.4/topics/running/services/auth-service.md +++ /dev/null @@ -1,150 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Authentication service - -$productName$ provides a highly flexible mechanism for authentication, -via the `AuthService` resource. An `AuthService` configures -$productName$ to use an external service to check authentication and -authorization for incoming requests. Each incoming request is -authenticated before routing to its destination. - -All requests are validated by the `AuthService` (unless the `Mapping` -applied to the request sets `bypass_auth`). It is not possible to -combine multiple `AuthServices`. While it is possible to create -multiple `AuthService` resources, $productName$ load-balances between -them in a round-robin fashion. This is useful for canarying an -`AuthService` change, but is not useful for deploying multiple -distinct `AuthServices`. In order to combine multiple external -services (either having multiple services apply to the same request, -or selecting between different services for the different requests), -instead of using an `AuthService`, use an [$AESproductName$ `External` -`Filter`](/docs/edge-stack/latest/topics/using/filters/). - - - -Because of the limitations described above, **$AESproductName$ does -not support `AuthService` resources, and you should instead use an -[`External` -`Filter`](/docs/edge-stack/latest/topics/using/filters/external),** -which is mostly a drop-in replacement for an `AuthService`. The -`External` `Filter` relies on the $AESproductName$ `AuthService`. -Make sure the $AESproductName$ `AuthService` is deployed before -configuring `External` `Filters`. - - - -The currently supported version of the `AuthService` resource is -`getambassador.io/v3alpha1`. Earlier versions are deprecated. - -## Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: AuthService -metadata: - name: authentication -spec: - ambassador_id: [ "ambassador-1" ] - auth_service: "example-auth.authentication:3000" - tls: true - proto: http - timeout_ms: 5000 - include_body: - max_bytes: 4096 - allow_partial: true - status_on_error: - code: 403 - failure_mode_allow: false - - # proto: grpc only, default is v2. If upgrading from 2.x then you must set this to v3. - protocol_version: v3 - - # proto: http only - path_prefix: "/path" - allowed_request_headers: - - "x-example-header" - allowed_authorization_headers: - - "x-qotm-session" - add_auth_headers: - x-added-auth: auth-added - add_linkerd_headers: false -``` - -## Fields - -`auth_service` is the only required field, all others are optional. - -| Attribute | Default value | Description | -| ---------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `ambassador_id` | `[ "default" ]` | Which [Ambassador ID](../../running/#ambassador_id) the `AuthService` should apply to. | -| `auth_service` | (none; a value is required) | Identifies the external auth service to talk to. The format of this field is `scheme://host:port` where `scheme://` and `:port` are optional. The scheme-part, if present, must be either `http://` or `https://`; if the scheme-part is not present, it behaves as if `http://` is given. The scheme-part controls whether TLS or plaintext is used and influences the default value of the port-part. The host-part must be the [namespace-qualified DNS name](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#namespaces-of-services) of the service you want to use for authentication. | -| `tls` | `""` | This field is populated with the name of the defined TLSContext, which determines the TLS certificate presented to external auth services. | -| `proto` | `http` | Specifies which variant of the [`ext_authz` protocol](../ext-authz/) to use when communicating with the external auth service. Valid options are `http` or `grpc`. | -| `timeout_ms` | `5000` | The total maximum duration in milliseconds for the request to the external auth service, before triggering `status_on_error` or `failure_mode_allow`. | -| `include_body` | `null` | Controls how much to buffer the request body to pass to the external auth service, for use cases such as computing an HMAC or request signature. If `include_body` is `null` or unset, then the request body is not buffered at all, and an empty body is passed to the external auth service. If `include_body` is not `null`, the `max_bytes` and `allow_partial` subfields are required. | -| `include_body.max_bytes` | (none; a value is required if `include_body` is not `null`) | Controls the amount of body data that is passed to the external auth service. | -| `include_body.allow_partial` | (none; a value is required if `include_body` is not `null`) | Controls what happens to requests with bodies larger than `max_bytes`. If `allow_partial` is `true`, the first `max_bytes` of the body are sent to the external auth service. If `false`, the message is rejected with HTTP 413 ("Payload Too Large"). | -| `status_on_error.code` | `403` | Controls the status code returned when unable to communicate with external auth service. This is ignored if `failure_mode_allow: true`. | -| `failure_mode_allow` | `false` | Controls whether to allow or reject requests when there is an error communicating with the external auth service; a value of `true` allows the request through to the upstream backend service, a value of `false` returns a `status_on_error.code` response to the client. | -| `stats_name` | the `auth_service` value with non-alphanumeric characters replaced with underscores | See [Overriding Statistics Names](../../statistics/#overriding-statistics-names). | -| `circuit_breakers` | the value set in the [`ambassador` `Module`](../../../using/defaults) | See [Circuit Breakers](../../../using/circuit-breakers/). | - -The following field is only used if `proto` is set to `grpc`. It is -ignored if `proto` is `http`. - -| Attribute | Default value | Description | -| ------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `protocol_version` | `v3` | Allowed values are `v3` and `v2`(defualt). `protocol_version` was used in previous versions of $productName$ to control the protocol used by the gRPC service. $productName$ 3.x is running an updated version of Envoy that has dropped support for the `v2` protocol, so starting in 3.x, if `protocol_version` is not specified, 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. | - -The following fields are only used if `proto` is set to `http`. They -are ignored if `proto` is `grpc`. - -| Attribute | Default value | Description | -| ------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `path_prefix` | `""` | Prepends a string to the request path of the request when sending it to the external auth service. By default this is empty, and nothing is prepended. For example, if the client makes a request to `/foo`, and `path_prefix: /bar`, then the path in the request made to the external auth service will be `/foo/bar`. | -| `allowed_request_headers` | `[]` | Lists the headers (case-insensitive) that are copied from the incoming request to the request made to the external auth service. In addition to the headers listed in this field, the following headers are always included: `Authorization`, `Cookie`, `From`, `Proxy-Authorization`, `User-Agent`, `X-Forwarded-For`, `X-Forwarded-Host`, and `X-Forwarded-Proto`. | -| `allowed_authorization_headers` | `[]` | Lists the headers (case-insensitive) that are copied from the response from the external auth service to the request sent to the upstream backend service (if the external auth service indicates that the request to the upstream backend service should be allowed). In addition to the headers listed in this field, the following headers are always included: `Authorization`, `Location`, `Proxy-Authenticate`, `Set-cookie`, `WWW-Authenticate` | -| `add_auth_headers` | `{}` | A dictionary of `header: value` pairs that are added to the request made to the external auth service. | -| `add_linkerd_headers` | Defaults to the value set in the [`ambassador` `Module`](../../ambassador) | When true, in the request to the external auth service, adds an `l5d-dst-override` HTTP header that is set to the hostname and port number of the external auth service. | - -## Canarying multiple `AuthServices` - -You may create multiple `AuthService` manifests to round-robin -authentication requests among multiple services. **All services must -use the same `path_prefix` and header definitions.** If you try to -have different values, you'll see an error in the [diagnostics -service](../../ambassador/#diagnostics), telling you which value is -being used. - -## Configuring public `Mappings` - -An `AuthService` can be disabled for a `Mapping` by setting -`bypass_auth` to `true`. This will tell $productName$ to allow all -requests for that `Mapping` through without interacting with the -external auth service. - - - -## Transport Protocol Migration - - -> **Note:** The following information is only applicable to `AuthServices` using `proto: grpc` -As of $productName$ version 2.3, the `v2` transport protocol is deprecated and any AuthServices making use -of it should migrate to `v3` before support for `v2` is removed in a future release. - -The following imports simply need to be updated to migrate an AuthService - -`v2` Imports: -``` - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" -``` - -`v3` Imports: -``` - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" -``` diff --git a/content/en/docs/3.4/topics/running/services/ext-authz.md b/content/en/docs/3.4/topics/running/services/ext-authz.md deleted file mode 100644 index d850ba4b..00000000 --- a/content/en/docs/3.4/topics/running/services/ext-authz.md +++ /dev/null @@ -1,83 +0,0 @@ -# ExtAuth protocol - -By design, the ExtAuth protocol used by [the AuthService](../auth-service) and by [External Filters](/docs/edge-stack/latest/topics/using/filters/external) is highly flexible. The authentication service is the first external service invoked on an incoming request (e.g., it runs before the rate limit filter). Because the logic of authentication is encapsulated in an external service, you can use this to support a wide variety of use cases. For example: - -* Supporting traditional SSO authentication protocols, e.g., OAuth, OpenID Connect, etc. -* Supporting HTTP basic authentication ([see a sample implementation](https://github.com/datawire/ambassador-auth-httpbasic)). -* Only authenticating requests that are under a rate limit and rejecting authentication requests above the rate limit. -* Authenticating specific services (URLs), and not others. - -For each request, the ExtAuth service may either: - 1. return a direct HTTP *response*, intended to be sent back to the requesting HTTP client (normally *denying* the request from being forwarded to the upstream backend service) or - 2. return a modification to make to the HTTP *request* before sending it to the upstream backend service (normally *allowing* the request to be forwarded to the upstream backend service with modifications). - -The ExtAuth service receives information about every request through $productName$ and must indicate whether the request is to be allowed or not. If not, the ExtAuth service provides the HTTP response which is to be handed back to the client. A potential control flow for Authentication is shown in the image below. - -Giving the ExtAuth service the ability to control the response allows many different types of auth mechanisms, for example: - -- The ExtAuth service can simply return an error page with an HTTP 401 response. -- The ExtAuth service can choose to include a `WWW-Authenticate` header in the 401 response, to ask the client to perform HTTP Basic Auth. -- The ExtAuth service can issue a 301 `Redirect` to divert the client into an OAuth or OIDC authentication sequence. The control flow of this is shown below. ![Authentication flow](../../../images/auth-flow.png) - -There are two variants of the ExtAuth: gRPC and plain HTTP. - -### The gRPC protocol - -When `proto: grpc` is set, the ExtAuth service must implement the `Authorization` gRPC interface, defined in [Envoy's `external_auth.proto`](https://github.com/emissary-ingress/emissary/blob/master/api/envoy/service/auth/v3/external_auth.proto). - -### The HTTP protocol - -External services for `proto: http` are often easier to implement, but have several limitations compared to `proto: grpc`. - - The list of headers that the ExtAuth service is interested in reading must be known ahead of time, in order to set `allow_request_headers`. Inspecting headers that are not known ahead of time requires instead using `proto: grpc`. - - The list of headers that the ExtAuth service would like to set or modify must be known ahead of time, in order to set `allow_authorization_headers`. Setting headers that are not known ahead of time requires instead using `proto: grpc`. - - When returning a direct HTTP response, the HTTP status code cannot be 200 or in the 5XX range. Intercepting with a 200 or 5XX response requires instead using `proto: grpc`. - -#### The request From $productName$ to the ExtAuth service - -For every incoming request, a similar request is made to the ExtAuth service that mimics the: - - HTTP request method - - HTTP request path, potentially modified by `path_prefix` - - HTTP request headers that are either named in `allowed_request_headers` or in the fixed list of headers that are always included - - first `include_body.max_bytes` of the HTTP request body. - -The `Content-Length` HTTP header is set to the number of bytes in the body of the request sent to the ExtAuth service (`0` if `include_body` is not set). - -**ALL** request methods will be proxied, which implies that the ExtAuth service must be able to handle any request that any client could make. - -Take this incoming request for example: - -``` -PUT /path/to/service HTTP/1.1 -Host: myservice.example.com:8080 -User-Agent: curl/7.54.0 -Accept: */* -Content-Type: application/json -Content-Length: 27 - -{ "greeting": "hello world!", "spiders": "OMG no" } -``` - -The request $productName$ will make of the auth service is: - -``` -PUT /path/to/service HTTP/1.1 -Host: extauth.example.com:8080 -User-Agent: curl/7.54.0 -Accept: */* -Content-Type: application/json -Content-Length: 0 -``` - -#### The response returned from the ExtAuth service to $productName$ - - - If the HTTP response returned from the ExtAuth service to $productName$ has an HTTP status code of 200, then the request is allowed through to the upstream backend service. **Only** 200 indicates this; other 2XX status codes will prevent the request from being allowed through. - - The 200 response should not contain anything in the body, but may contain arbitrary headers. Any header present in the ExtAuth service' response that is also either listed in the `allow_authorization_headers` attribute of the AuthService resource or in the fixed list of headers that are always included will be copied from the ExtAuth service's response into the request going to the upstream backend service. This allows the ExtAuth service to inject tokens or other information into the request, or to modify headers coming from the client. - - The big limitation here is that the list of headers to be set must be known ahead of time, in order to set `allow_request_headers`. Setting headers that are not known ahead of time requires instead using `proto: grpc`. - - - If $productName$ cannot reach the ExtAuth service at all, if the ExtAuth service does not return a valid HTTP response, or if the HTTP response has an HTTP status code in the 5XX range, then the communication with the ExtAuth service is considered to have failed, and the `status_on_error` or `failure_mode_allow` behavior is triggered. - - - Any HTTP status code other than 200 or 5XX from the ExtAuth service tells $productName$ to **not** allow the request to continue to the upstream backend service, but that the ExtAuth service is instead intercepting the request. The entire HTTP response from the ExtAuth service--including the status code, the headers, and the body--is handed back to the client verbatim. This gives the ExtAuth service **complete** control over the entire response presented to the client. - - The big limitation here is that you cannot directly return a 200 or 5XX response. Intercepting with a 200 of 5XX response requires instead using `proto: grpc`. diff --git a/content/en/docs/3.4/topics/running/services/index.md b/content/en/docs/3.4/topics/running/services/index.md deleted file mode 100644 index 1646aa5a..00000000 --- a/content/en/docs/3.4/topics/running/services/index.md +++ /dev/null @@ -1,11 +0,0 @@ -# Available plugins - -You may need an API Gateway to enforce policies specific to your organization. $productName$ supports custom policies through external service plugins. The policy logic specific to your organization is implemented in the external service, and $productName$ is configured to send RPC requests to your service. - -Currently, $productName$ supports plugins for authentication, -access logging, rate limiting, and tracing. - -* [AuthService](auth-service) Plugin -* [LogService](log-service) Plugin -* [RateLimitService](rate-limit-service) Plugin -* [TracingService](tracing-service) Plugin diff --git a/content/en/docs/3.4/topics/running/services/log-service.md b/content/en/docs/3.4/topics/running/services/log-service.md deleted file mode 100644 index b3e90c7c..00000000 --- a/content/en/docs/3.4/topics/running/services/log-service.md +++ /dev/null @@ -1,116 +0,0 @@ -# Log service - -By default, $productName$ puts the access logs on stdout; such -that the can be read using `kubectl logs`. The format of those logs, -and the local destination of them, can be configured using the -[`envoy_log_` settings in the `ambassador -Module`](../../ambassador). However, the -options there only allow for logging local to $productName$'s Pod. By -configuring a `LogService`, you can configure $productName$ to -report its access logs to a remote service, in addition to the usual -`ambassador Module` configured logging. - -The remote access log service (or ALS) must implement the -`AccessLogService` gRPC interface, defined in [Envoy's `als.proto`][als.proto]. - -[als.proto]: https://github.com/emissary-ingress/emissary/blob/master/api/envoy/service/accesslog/v3/als.proto - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: LogService -metadata: - name: example-log-service -spec: - # Common to all $productName$ resources - ambassador_id: []string # optional; default is ["default"] - - # LogService specific - service: "string" # required - driver: "enum-string:[tcp, http]" # required - driver_config: # required - additional_log_headers: # optional; default is [] (only for `driver: http`) - - header_name: string # required - during_request: boolean # optional; default is true - during_response: boolean # optional; default is true - during_trailer: boolean # optional; default is true - flush_interval_time: int-seconds # optional; default is 1 - flush_interval_byte_size: integer # optional; default is 16384 - grpc: boolean # optional; default is false - protocol_version: enum # optional; default is v2 -``` - - - `service` is where to route the access log gRPC requests to - - - `driver` identifies which type of accesses to log; HTTP requests (`"http"`) or - TLS connections (`"tcp"`). - - - `driver_config` stores the configuration that is specific to the `driver`: - - * `driver: tcp` has no additional configuration; the config must - be set as `driver_config: {}`. - - * `driver: http` - - - `additional_log_headers` identifies HTTP headers to include in - the access log, and when in the logged-request's lifecycle to - include them. - - - `flush_interval_time` is the maximum number of seconds to buffer - accesses for before sending them to the ALS. The logs will be - flushed to the ALS every time this duration is reached, or when the - buffered data reaches `flush_interval_byte_size`, whichever comes - first. See the [Envoy documentation on - `buffer_flush_interval`][buffer_flush_interval] for more - information. - - - `flush_interval_byte_size` is a soft size limit for the access log - buffer. The logs will be flushed to the ALS every time the - buffered data reaches this size, or whenever `flush_interval_time` - elapses, whichever comes first. See the [Envoy documentation on - `buffer_size_bytes`][buffer_size_bytes] for more information. - - - `grpc` must be `true`. - -[buffer_flush_interval]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/access_loggers/grpc/v3/als.proto.html#extensions-access-loggers-grpc-v3-commongrpcaccesslogconfig -[buffer_size_bytes]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/access_loggers/grpc/v3/als.proto.html#extensions-access-loggers-grpc-v3-commongrpcaccesslogconfig - - - `protocol_version` was used in previous versions of $productName$ to control the gRPC service name used to communicate with the `LogService`. $productName$ 3.x is running an updated version of Envoy that has dropped support for the `v2` protocol, so starting in 3.x, if `protocol_version` is not specified, 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. - -## Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: LogService -metadata: - name: als -spec: - service: "als.default:3000" - driver: http - driver_config: {} # NB: driver_config must be set, even if it's empty - grpc: true # NB: grpc must be true and it will use the V3 transport protocol -``` - -## Transport Protocol Migration - - -> **Note:** The following information is only applicable to `AuthServices` using `proto: grpc` -As of $productName$ version 2.3, the `v2` transport protocol is deprecated and any AuthServices making use -of it should migrate to `v3` before support for `v2` is removed in a future release. - -The following imports simply need to be updated to migrate an AuthService - -`v2` Imports: -``` - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" -``` - -`v3` Imports: -``` - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" -``` diff --git a/content/en/docs/3.4/topics/running/services/rate-limit-service.md b/content/en/docs/3.4/topics/running/services/rate-limit-service.md deleted file mode 100644 index 39c2b0ce..00000000 --- a/content/en/docs/3.4/topics/running/services/rate-limit-service.md +++ /dev/null @@ -1,118 +0,0 @@ -# Rate limit service - -Rate limiting is a powerful technique to improve the [availability and -resilience of your -services](https://blog.getambassador.io/rate-limiting-a-useful-tool-with-distributed-systems-6be2b1a4f5f4). -In $productName$, each request can have one or more _labels_. These labels are -exposed to a third-party service via a gRPC API. The third-party service can -then rate limit requests based on the request labels. - -**Note that `RateLimitService` is only applicable to $OSSproductName$, -and not $AESproductName$, as $AESproductName$ includes a -built-in rate limit service.** - -## Request labels - -See [Attaching labels to -requests](../../../using/rate-limits#attaching-labels-to-requests) -for how to configure the labels that are attached to a request. - -## Domains - -In $productName$, each engineer (or team) can be assigned its own _domain_. A -domain is a separate namespace for labels. By creating individual domains, each -team can assign their own labels to a given request, and independently set the -rate limits based on their own labels. - -See [Attaching labels to -requests](../../../using/rate-limits/#attaching-labels-to-requests) -for how to labels under different domains. - -## External rate limit service - -In order for $productName$ to rate limit, you need to implement a -gRPC `RateLimitService`, as defined in [Envoy's `v3/rls.proto`] -interface. If you do not have the time or resources to implement your own rate -limit service, $AESproductName$ integrates a high-performance rate -limiting service. - -[envoy's `v3/rls.proto`]: https://github.com/emissary-ingress/emissary/tree/master/api/envoy/service/ratelimit/v3/rls.proto - -$productName$ generates a gRPC request to the external rate limit -service and provides a list of labels on which the rate limit service can base -its decision to accept or reject the request: - -``` -[ - {"source_cluster", ""}, - {"destination_cluster", ""}, - {"remote_address", ""}, - {"generic_key", ""}, - {"", ""} -] -``` - -If $productName$ cannot contact the rate limit service, it will -allow the request to be processed as if there were no rate limit service -configuration. - -It is the external rate limit service's responsibility to determine whether rate -limiting should take place, depending on custom business logic. The rate limit -service must simply respond to the request with an `OK` or `OVER_LIMIT` code: - -- If Envoy receives an `OK` response from the rate limit service, then $productName$ allows the client request to resume being processed by - the normal flow. -- If Envoy receives an `OVER_LIMIT` response, then $productName$ - will return an HTTP 429 response to the client and will end the transaction - flow, preventing the request from reaching the backing service. - -The headers injected by the [AuthService](../auth-service) can also be passed to -the rate limit service since the `AuthService` is invoked before the -`RateLimitService`. - -## Configuring the rate limit service - -A `RateLimitService` manifest configures $productName$ to use an -external service to check and enforce rate limits for incoming requests: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: RateLimitService -metadata: - name: ratelimit -spec: - service: 'example-rate-limit.default:5000' - protocol_version: # default is v2, if upgrading from 2.x then you must set this to v3. - failure_mode_deny: false # when set to true envoy will return 500 error when unable to communicate with RateLimitService -``` - -- `service` gives the URL of the rate limit service. If using a Kubernetes service, this should be the [namespace-qualified DNS name](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#namespaces-of-services) of that service. -- `protocol_version` Allowed values are `v3` and `v2`(default). `protocol_version` was used in previous versions of $productName$ to control the protocol used by the gRPC service to communicate with the `RateLimitService`. $productName$ 3.x is running an updated version of Envoy that has dropped support for the `v2` protocol, so starting in 3.x, if `protocol_version` is not specified, 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. -- `failure_mode_deny` By default, Envoy will fail open when unable to communicate with the service due to it becoming unvailable or due to timeouts. When this happens the upstream service that is being protected by a rate limit may be overloaded due to this behavior. When set to `true` Envoy will be configured to return a `500` status code when it is unable to communicate with the RateLimit service and will fail closed by rejecting request to the upstream service. - -You may only use a single `RateLimitService` manifest. - -## Rate limit service and TLS - -You can tell $productName$ to use TLS to talk to your service by -using a `RateLimitService` with an `https://` prefix. However, you may also -provide a `tls` attribute: if `tls` is present and `true`, $productName$ will originate TLS even if the `service` does not have the `https://` -prefix. - -If `tls` is present with a value that is not `true`, the value is assumed to be the name of a defined TLS context, which will determine the certificate presented to the upstream service. - -## Example - -The [$OSSproductName$ Rate Limiting -Tutorial](../../../../howtos/rate-limiting-tutorial) has a simple rate limiting -example. For a more advanced example, read the [advanced rate limiting -tutorial](../../../../../2.0/howtos/advanced-rate-limiting), which uses the rate limit -service that is integrated with $AESproductName$. - -## Further reading - -- [Rate limiting: a useful tool with distributed systems](https://blog.getambassador.io/rate-limiting-a-useful-tool-with-distributed-systems-6be2b1a4f5f4) -- [Rate limiting for API Gateways](https://blog.getambassador.io/rate-limiting-for-api-gateways-892310a2da02) -- [Implementing a Java Rate Limiting Service for $productName$](https://blog.getambassador.io/implementing-a-java-rate-limiting-service-for-the-ambassador-api-gateway-e09d542455da) -- [Designing a Rate Limit Service for $productName$](https://blog.getambassador.io/designing-a-rate-limiting-service-for-ambassador-f460e9fabedb) diff --git a/content/en/docs/3.4/topics/running/services/tracing-service.md b/content/en/docs/3.4/topics/running/services/tracing-service.md deleted file mode 100644 index f7f780d3..00000000 --- a/content/en/docs/3.4/topics/running/services/tracing-service.md +++ /dev/null @@ -1,132 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Tracing service - -Applications that consist of multiple services can be difficult to debug, as a single request can span multiple services. Distributed tracing tells the story of your request as it is processed through your system. Distributed tracing is a powerful tool to debug and analyze your system in addition to request logging and metrics. - -When enabled, the `TracingService` will instruct $productName$ to initiate a trace on requests by generating and populating an `x-request-id` HTTP header. Services can make use of this `x-request-id` header in logging and forward it in downstream requests for tracing. $productName$ also integrates with external trace visualization services, including Zipkin-compatible APIs such as [Zipkin](https://zipkin.io/) and [Jaeger](https://github.com/jaegertracing/) to allow you to store and visualize traces. You can read further on [Envoy's Tracing capabilities](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/tracing). - -A `TracingService` manifest configures $productName$ to use an external trace visualization service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TracingService -metadata: - name: tracing -spec: - service: "example-zipkin:9411" - driver: zipkin - config: {} - custom_tags: # optional - - tag: host - request_header: - name: ":authority" - default_value: "unknown" - - tag: path - request_header: - name: ":path" - default_value: "unknown" - sampling: - overall: 100 -``` - -| Field | Description | values | -| --------- | ----------- | ------------- | -| `service` | gives the URL of the external HTTP trace service. | ex. `example-zipkin:9411` | -| `driver` | provides the driver information that handles communicating with the service | enum:
`zipkin`
`datadog` | -| `config` | provides additional configuration options for the selected `driver`. Supported configuration for each driver is found below. | | -| `tag_headers` | **Deprecated** - it is recommend that you switch to using `custom_tags`| | -| `custom_tags` | configure tags to attach to traces. See section below for more details. | | -| `propagation_modes` | (optional) if present, specifies a list of the propogation modes to be used | enum:
`ENVOY`
`B3`
`TRACE_CONTEXT` | -| `sampling` | (optional) if present, specifies some target percentages of requests that will be traced. | | - -Please note that you must use the HTTP/2 pseudo-header names. For example: - -- the `host` header should be specified as the `:authority` header; and -- the `method` header should be specified as the `:method` header. - - - -The TraceService is configured globally during Envoy bootstrap, therefore $productName$ must be restarted for changes to take affect. - - - -## Supported Tracing Drivers - -The `TraceService` currently supports the following drivers: - -- `zipkin` -- `datadog` - - -In Envoy 1.24, support for the LightStep driver was removed. As of $produceName$ 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 - - -## Sampling - -Configuring `sampling` will specify some target percentages of requests that will be traced. This is beneficial for high-volume services to control the amount of tracing data collected. Sampling can be configured with the following fields: - -- `client`: percentage of requests that will be force traced if the `x-client-trace-id` header is set. Defaults to 100. -- `random`: percentage of requests that will be randomly traced. Defaults to 100. -- `overall`: percentage of requests that will be traced after all other checks have been applied (force tracing, sampling, etc.). -This field functions as an upper limit on the total configured sampling rate. For instance, setting `client` -to `100%` but `overall` to `1%` will result in only `1%` of client requests with the appropriate headers to be force -traced. Defaults to 100. - -## Custom Tags and Tag Headers - -When collecting traces, $productName$ will attach tags to the `span`'s that are generated which are useful for observability. See the [Envoy Tracing Docs](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/tracing#what-data-each-trace-contains) for the default list of data collected. - -Previous versions of $productName$ only supported adding additional tags through the use of the `tag_headers` field. This field is now **deprecated** and it is recommended to use `custom_tags` which supports a more powerful set of features for adding additional tags to a span. - - -If both tag_headers and custom_tags are set then tag_headers will be ignored. - - -`custom_tags` provides support for configuring additional tags based on [Envoy Custom Tags](https://www.envoyproxy.io/docs/envoy/latest/api-v3/type/tracing/v3/custom_tag.proto%23custom-tag). The following custom tag kinds supported are: - -- `request_header` - set tag from header in the request -- `environment` - set tag from an environment variable -- `literal` - set tag based on a configured literal value - -Each custom_tag supports setting oneOf `request_header`, `literal` or `environment`. Each tag should have its own entry in `custom_tags`. - -For example: - -```yaml -custom_tags: - - tag: host - request_header: - name: ":authority" - default_value: "unknown host" # optional - - tag: path - request_header: ":path" - name: ":authority" - default_value: "unknown path" # optional - - tag: cluster - literal: - value: "us-east-cluster" - - tag: nodeID - environment: - name: SERVER_ID - default_value: "unknown" # optional -``` - -### Zipkin driver configurations - -- `collector_endpoint` gives the API endpoint of the Zipkin service where the spans will be sent. The default value is `/api/v2/spans` -- `collector_endpoint_version` gives the transport version used when sending data to your Zipkin collector. The default value is `HTTP_JSON` and it must be one of `HTTP_JSON` or `HTTP_PROTO`. -- `collector_endpoint_hostname` sets the hostname Envoy will use when sending data to your Zipkin collector. The default value is the name of the underlying Envoy cluster. -- `trace_id_128bit` whether a 128-bit `trace id` will be used when creating a new trace instance. Defaults to `true`. Setting to `false` will result in a 64-bit trace id being used. -- `shared_span_context` whether client and server spans will share the same `span id`. The default value is `true`. - -### Datadog Driver Configurations - -- `service_name` the name of the service which is attached to the traces. The default value is `ambassador`. - -You may only use a single `TracingService` manifest per $productName$ deployment. Ensure [ambassador_id](../../running#ambassador_id) is set correctly in the `TracingService` manifest. - -## Example - -Check out the [DataDog](../../../../howtos/tracing-datadog) and [Zipkin](../../../../howtos/tracing-zipkin) HOWTOs. diff --git a/content/en/docs/3.4/topics/running/statistics/8877-metrics.md b/content/en/docs/3.4/topics/running/statistics/8877-metrics.md deleted file mode 100644 index 94bd2043..00000000 --- a/content/en/docs/3.4/topics/running/statistics/8877-metrics.md +++ /dev/null @@ -1,64 +0,0 @@ -# The metrics endpoint - -> For an overview of other options for gathering statistics on -> $productName$, see the [Statistics and Monitoring](../) overview. - -Each $productName$ pod exposes statistics and metrics for that pod at -`http://{POD}:8877/metrics`. The response is in the text-based -Prometheus [exposition format][]. - -[exposition format]: https://prometheus.io/docs/instrumenting/exposition_formats/ - -## Understanding the statistics - -The Prometheus exposition format includes special "HELP" lines that -make the file self-documenting as to what specific statistics mean. - - - -- `envoy_*`: See the [Envoy documentation][`GET /stats/prometheus`]. -- `ambassador_*`: - - `ambassador_edge_stack_*` (not present in $OSSproductName$): - - `ambassador_edge_stack_go_*`: See [`promethus.NewGoCollector()`][]. - - `ambassador_edge_stack_promhttp_*` See [`promhttp.Handler()`][]. - - `ambassador_edge_stack_process_*`: See [`promethus.NewProcessCollector()`][].. - - `ambassador_*_time_seconds` (for `*` = one of `aconf`, `diagnostics`, `econf`, `fetcher`, `ir`, or `reconfiguration`): - Gauges of how long the various core operations take in the diagd - process. - - `ambassador_diagnostics_(errors|notices)`: The number of - diagnostics errors and notices that would be shown in the - diagnostics UI or the Edge Policy Console. - - `ambassador_diagnostics_info`: [Info][`prometheus_client.Info`] - about the $productName$ install; all information is presented in - labels; the value of the Gauge is always "1". - - `ambassador_process_*`: See [`prometheus_client.ProcessCollector`][]. - -[`GET /stats/prometheus`]: https://www.envoyproxy.io/docs/envoy/v1.23.0/operations/admin.html#get--stats-prometheus -[`prometheus.NewProcessCollector`]: https://godoc.org/github.com/prometheus/client_golang/prometheus#NewProcessCollector -[`prometheus.NewGoCollector`]: https://godoc.org/github.com/prometheus/client_golang/prometheus#NewGoCollector -[`promhttp.Handler()`]: https://godoc.org/github.com/prometheus/client_golang/prometheus/promhttp#Handler -[`prometheus_client.Info`]: https://github.com/prometheus/client_python#info -[`prometheus_client.ProcessCollector`]: https://github.com/prometheus/client_python#process-collector - -## Polling the `:8877/metrics` endpoint with Prometheus - -To scrape metrics directly, follow the instructions for [Monitoring -with Prometheus and Grafana](../../../../howtos/prometheus). - -### Using Grafana to visualize statistics gathered by Prometheus - -#### Sample dashboard - -We provide a [sample Grafana dashboard](https://grafana.com/grafana/dashboards/4698-ambassador-edge-stack/) -that displays information collected by Prometheus from the -`:8877/metrics` endpoint. - -![Screenshot of a Grafana dashboard that displays just information from Envoy](../../../images/grafana.png) diff --git a/content/en/docs/3.4/topics/running/statistics/envoy-statsd.md b/content/en/docs/3.4/topics/running/statistics/envoy-statsd.md deleted file mode 100644 index 7cbcc208..00000000 --- a/content/en/docs/3.4/topics/running/statistics/envoy-statsd.md +++ /dev/null @@ -1,109 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Envoy statistics with StatsD - -> For an overview of other options for gathering statistics on -> $productName$, see the [Statistics and Monitoring](../) overview. - -At the core of $productName$ is [Envoy Proxy], which has built-in -support for exporting a multitude of statistics about its own -operations to StatsD (or to the modified DogStatsD used by Datadog). - -[Envoy Proxy]: https://www.envoyproxy.io - -If enabled, then $productName$ has Envoy expose this information via the -[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: - -```diff - spec: - containers: - - env: -+ - name: STATSD_ENABLED -+ value: "true" - - name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: -``` - -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. - -We have included a few example configurations in -[the `statsd-sink/` directory](https://github.com/emissary-ingress/emissary/tree/master/deployments/statsd-sink) -to help you get started. Clone or download the -repository to get local, editable copies and open a terminal -window in the `emissary/deployments/` folder. - -## Using Graphite as the StatsD sink - -[Graphite] is a web-based real-time graphing system. Spin up an -example Graphite setup: - -[Graphite]: http://graphite.readthedocs.org/ - -``` -kubectl apply -f statsd-sink/graphite/graphite-statsd-sink.yaml -``` - -This sets up the `statsd-sink` service and a deployment that contains -Graphite and its related infrastructure. Graphite's web interface is -available at `http://statsd-sink/` from within the cluster. Use port -forwarding to access the interface from your local machine: - -``` -SINKPOD=$(kubectl get pod -l service=statsd-sink -o jsonpath="{.items[0].metadata.name}") -kubectl port-forward $SINKPOD 8080:80 -``` - -This sets up Graphite access at `http://localhost:8080/`. - -## Using Datadog DogStatsD as the StatsD sink - -If you are a user of the [Datadog] monitoring system, pulling in the -Envoy statistics from $productName$ is very easy. - -[Datadog]: https://www.datadoghq.com/ - -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: - -```diff - spec: - containers: - - env: -+ - name: STATSD_ENABLED -+ value: "true" -+ - name: DOGSTATSD -+ value: "true" - - name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: -``` - -Then, you will need to deploy the DogStatsD agent in to your cluster -to act as the StatsD sink. To do this, replace the sample API key in -our [sample YAML file][`dd-statsd-sink.yaml`] with your own, then -apply that YAML: - -[`dd-statsd-sink.yaml`]: https://github.com/emissary-ingress/emissary/blob/master/deployments/statsd-sink/datadog/dd-statsd-sink.yaml - -``` -kubectl apply -f statsd-sink/datadog/dd-statsd-sink.yaml -``` - -This sets up the `statsd-sink` service and a deployment of the -DogStatsD agent that forwards the $productName$ statistics to your -Datadog account. - -Additionally, $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). diff --git a/content/en/docs/3.4/topics/running/statistics/index.md b/content/en/docs/3.4/topics/running/statistics/index.md deleted file mode 100644 index ab44009f..00000000 --- a/content/en/docs/3.4/topics/running/statistics/index.md +++ /dev/null @@ -1,84 +0,0 @@ -# Statistics and monitoring - -$productName$ collects many statistics internally, and makes it easy to -direct this information to a statistics and monitoring tool of your -choice. - -As an example, here are some interesting statistics to investigate: - -- `upstream_rq_total` is the total - number of requests that a particular service has received via $productName$. The rate of change of this value is one basic measure of - service utilization, i.e. requests per second. -- `upstream_rq_xx` is the total number - of requests to which a service responded with a given status code. - This value divided by the prior one, taken on - a rolling window basis, represents the recent response rate of the - service. There are corresponding classes for `2xx`, `3xx`, `4xx` and `5xx` counters that can - help clarify the nature of responses. -- `upstream_rq_time` is a Prometheus histogram or StatsD timer - that tracks the latency in milliseconds of a given service from $productName$'s perspective. - -## Overriding Statistics Names - -The optional `stats_name` element of every CRD that references a service (`Mapping`, `TCPMapping`, -`AuthService`, `LogService`, `RateLimitService`, and `TracingService`) can override the name under which cluster statistics -are logged (`usersvc` above). If not set, the default is the `service` value, with non-alphanumeric characters replaced by -underscores: - -- `service: foo` will just use `foo` -- `service: foo:8080` will use `foo_8080` -- `service: http://foo:8080` will use `http___foo_8080` -- `service: foo.othernamespace` will use `foo_othernamespace` - -The last example is worth special mention: a resource in a different namespace than the one in which $productName$ is running will automatically be qualified with the namespace of the resource itself. So, for example, if $productName$ is running in the `ambassador` namespace, and this `Mapping` is present in the `default` namespace: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: default-mapping - namespace: default -spec: - prefix: /default/ - service: default-service -``` - -then the `service` will be qualified to `default-service.default`, so the `stats_name` will be `default_service_default` rather than simply `default_service`. To change this behavior, set `stats_name` explicitly. - -## Monitoring Statistics - -There are several ways to get different statistics out of $productName$: - -- [The `:8877/metrics` endpoint](./8877-metrics) can be polled for - aggregated statistics (in a Prometheus-compatible format). This is - our recommended method as both Envoy metrics and $productName$ control plane - metrics are collected. -- $productName$ can push [Envoy statistics](./envoy-statsd) over the - StatsD or DogStatsD protocol. - -## The Four Golden Signals - -The [Four Golden Signals](https://sre.google/sre-book/monitoring-distributed-systems/) are four generally-accepted metrics -that are important to monitor for good information about service health: - -### Latency - -The time it takes to service a request as a histogram of time taken by individual requests, which can be an effective latency metric. -In StatsD, this stat would be expressed as `cluster.$name.upstream_rq_time`. -While in Prometheus format, this metric would be expressed as `envoy_cluster_upstream_rq_time_bucket{envoy_cluster_name="$name"}`. - -### Traffic - -The amount of demand being placed on your system as a gauge that shows the number of active outstanding requests, which can be a good proxy for traffic. -In StatsD, this stat would be expressed as `cluster.$name.upstream_rq_active`. -While in Prometheus format, this metric would be expressed as `envoy_cluster_upstream_rq_active{envoy_cluster_name="$name"}`. - -### Errors - -The number of failing requests. Some errors (e.g. a request succeeds, but gives the wrong answer) can only be detected by application-specific monitoring; however, many errors can be spotted simply by looking at the HTTP status code of requests. Monitoring it over time can show error rates. -In StatsD, `cluster.$name.upstream_rq_5xx` is a counter of HTTP `5xx` responses. -While in Prometheus, `envoy_cluster_upstream_rq_xx{envoy_response_code_class="5", envoy_cluster_name="$name"}` is a counter of HTTP `5xx` responses. - -### Saturation - -The hardest metric to measure, saturation describes how much of the total capability of the system to respond to requests is being used. Fully measuring saturation often requires application-specific monitoring, but looking at the 99th percentile of latency over a short window - perhaps a minute - can often give an early indication of saturation problems. diff --git a/content/en/docs/3.4/topics/running/tls/cleartext-redirection.md b/content/en/docs/3.4/topics/running/tls/cleartext-redirection.md deleted file mode 100644 index 7144b1a3..00000000 --- a/content/en/docs/3.4/topics/running/tls/cleartext-redirection.md +++ /dev/null @@ -1,76 +0,0 @@ -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`. - - - The 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. - - -## Cleartext Routing - -To allow cleartext to be routed, set the `requestPolicy.insecure.action` of a `Host` to `Route`: - -```yaml -requestPolicy: - insecure: - action: Redirect -``` - -This allows routing for either HTTP and HTTPS, or _only_ HTTP, depending on `tlsSecret` configuration: - -- If the `Host` does not specify a `tlsSecret`, it will only route HTTP, not terminating TLS at all. -- If the `Host` does specify a `tlsSecret`, it will route both HTTP and HTTPS. - - - The 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. - - -## HTTP->HTTPS redirection - -Most websites that force HTTPS will also automatically redirect any -requests that come into it over HTTP: - -``` -Client $productName$ -| | -| http:///api | -| --------------------------> | -| | -| 301: https:///api | -| <-------------------------- | -| | -| https:///api | -| --------------------------> | -| | -``` - -In $productName$, this is configured by setting the `insecure.action` in a `Host` to `Redirect`. - -```yaml -requestPolicy: - insecure: - action: Redirect -``` - -$productName$ determines which requests are secure and which are insecure using the -`securityModel` of the [`Listener`] that accepts the request. - -[`Listener`]: ../../listener - - - The 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. - diff --git a/content/en/docs/3.4/topics/running/tls/index.md b/content/en/docs/3.4/topics/running/tls/index.md deleted file mode 100644 index 850fb5c0..00000000 --- a/content/en/docs/3.4/topics/running/tls/index.md +++ /dev/null @@ -1,487 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Transport Layer Security (TLS) - -$productName$'s robust TLS support exposes configuration options -for many different TLS use cases, using the [`Host`](#host) and -[`TLSContext`](#host-and-tlscontext) resources in concert. - -## Certificates and Secrets - -Properly-functioning TLS requires the use of [TLS certificates] to prove that the -various systems communicating are who they say they are. At minimum, $productName$ -must have a server certificate that identifies it to clients; when [mTLS] or -[client certificate authentication] are in use, additional certificates are needed. - -You supply certificates to $productName$ in Kubernetes [TLS Secrets]. These Secrets -_must_ contain valid X.509 certificates with valid PKCS1, PKCS8, or Elliptic Curve private -keys. If a Secret does not contain a valid certificate, an error message will be logged, for -example: - -``` -tls-broken-cert.default.1 2 errors:; 1. K8sSecret secret tls-broken-cert.default tls.key cannot be parsed as PKCS1 or PKCS8: asn1: syntax error: data truncated; 2. K8sSecret secret tls-broken-cert.default tls.crt cannot be parsed as x.509: x509: malformed certificate -``` - -If you set the `AMBASSADOR_FORCE_SECRET_VALIDATION` environment variable, the invalid -Secret will be rejected, and a `Host` or `TLSContext` resource attempting to use an invalid -certificate will be disabled entirely. **Note** that in $productName$ $version$, this -includes disabling cleartext communication for such a `Host`. - -[TLS Certificates]: https://protonmail.com/blog/tls-ssl-certificate/ -[mTLS]: mtls -[client certificate authentication]: ../../../howtos/client-cert-validation/ -[TLS Secrets]: https://kubernetes.io/docs/concepts/configuration/secret/#tls-secrets - -## `Host` - -A `Host` represents a domain in $productName$ and defines how the domain manages TLS. For more information on the Host resource, see [The Host CRD reference documentation](../host-crd). - -**If no `Host`s are present**, $productName$ synthesizes a `Host` that -allows only cleartext routing. You will need to explictly define `Host`s to enable -TLS termination. - - - The examples below do not define a requestPolicy; however, most real-world - usage of $productName$ will require defining the requestPolicy.
-
- For more information, please refer to the Host documentation. - - -### Bring your own certificate - -The `Host` can read a certificate from a Kubernetes Secret and use that certificate -to terminate TLS on a domain. - -The following example shows the certificate contained in the Kubernetes Secret named -`host-secret` configured to have $productName$ terminate TLS on the `host.example.com` -domain: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: host-secret -``` - -By default, `tlsSecret` will only look for the named secret in the same namespace as the `Host`. -In the above example, the secret `host-secret` will need to exist within the `default` namespace -since that is the namespace of the `Host`. - -To reference a secret that is in a different namespace from the `Host`, the `namespace` field is required. -The below example will configure the `Host` to use the `host-secret` secret from the `example` namespace. - -```yaml ---- -apiVersion: getambassador.io/v2 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - acmeProvider: - authority: none - tlsSecret: - name: host-secret - namespace: example -``` - - - - The Kubernetes Secret named by 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. - - - -### Advanced TLS configuration with the `Host` - -You can specify TLS configuration directly in the `Host` via the `tls` field. This is the -recommended method to do more advanced TLS configuration for a single `Host`. - -For example, the configuration to enforce a minimum TLS version on the `Host` looks as follows: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: min-secret - tls: - min_tls_version: v1.2 -``` - - - - The Kubernetes Secret named by 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. - - - -The following fields are accepted in the `tls` field: -```yaml -tls: - cert_chain_file: # string - private_key_file: # string - ca_secret: # string - cacert_chain_file: # string - alpn_protocols: # string - cert_required: # bool - min_tls_version: # string - max_tls_version: # string - cipher_suites: # array of strings - ecdh_curves: # array of strings - sni: # string - crl_secret: # string -``` - -These fields have the same function as in the [`TLSContext`](#tlscontext) resource, -as described below. - -### `Host` and `TLSContext` - -You can link a `Host` to a [`TLSContext`](#tlscontext) instead of defining `tls` -settings in the `Host` itself. This is primarily useful for sharing settings between -multiple `Host`s. - -#### Link a `TLSContext` to the `Host` - - - It is invalid to use both the 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. - - -To link a [`TLSContext`](#tlscontext) with a `Host`, create a [`TLSContext`](#tlscontext) -with the desired configuration and link it to the `Host` by setting the `tlsContext.name` -field in the `Host`. For example, to enforce a minimum TLS version on the `Host` above, -create a `TLSContext` with any name with the following configuration: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: min-tls-context -spec: - hosts: - - host.example.com - secret: min-secret - min_tls_version: v1.2 -``` - -Next, link it to the `Host` via the `tlsContext` field as shown: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: min-secret - tlsContext: - name: min-tls-context -``` - - - - The `Host` and the `TLSContext` must name the same Kubernetes Secret; if not, - $productName$ will disable TLS for the `Host`. - - - - - - The Kubernetes Secret named by 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. - - - - - - The `Host`'s `hostname` and the `TLSContext`'s `hosts` must have compatible settings. If - they do not, requests may not be accepted. - - - -See [`TLSContext`](#tlscontext) below to read more on the description of these fields. - -#### Create a `TLSContext` with the name `{{AMBASSADORHOST}}-context` (DEPRECATED) - - - This implicit 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. - - -The `Host` will implicitly link to the `TLSContext` when a `TLSContext` exists with the following: - -- the name `{{NAME_OF_AMBASSADORHOST}}-context` -- `hosts` in the `TLSContext` set to the same value as `hostname` in the `Host`, and -- `secret` in the `TLSContext` set to the same value as `tlsSecret` in the `Host` - -**As noted above, this implicit linking is deprecated.** - -For example, another way to enforce a minimum TLS version on the `Host` above would -be to simply create the `TLSContext` with the name `example-host-context` and then not modify the `Host`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-host-context -spec: - hosts: - - host.example.com - secret: host-secret - min_tls_version: v1.2 -``` - - - - The `Host` and the `TLSContext` must name the same Kubernetes Secret; if not, - $productName$ will disable TLS for the `Host`. - - - - - - The Kubernetes Secret named by 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. - - - - - - The `Host`'s `hostname` and the `TLSContext`'s `hosts` must have compatible settings. If - they do not, requests may not be accepted. - - - -Full reference for all options available to the `TLSContext` can be found [below](#tlscontext). - -## TLSContext - -The `TLSContext` is used to configure advanced TLS options in $productName$. -Remember, a `TLSContext` must always be paired with a `Host`. - -A full schema of the `TLSContext` can be found below with descriptions of the -different configuration options. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-host-context -spec: - # 'hosts' defines the hosts for which this TLSContext is relevant. - # It ties into SNI. A TLSContext without "hosts" is useful only for - # originating TLS. - # type: array of strings - # - # hosts: [] - - # 'sni' defines the SNI string to use on originated connections. - # type: string - # - # sni: None - - # 'secret' defines a Kubernetes Secret that contains the TLS certificate we - # use for origination or termination. If not specified, $productName$ will look - # at the value of cert_chain_file and private_key_file. - # type: string - # - # secret: None - - # 'ca_secret' defines a Kubernetes Secret that contains the TLS certificate we - # use for verifying incoming TLS client certificates. - # type: string - # - # ca_secret: None - - # Tells $productName$ whether to interpret a "." in the secret name as a "." or - # a namespace identifier. - # type: boolean - # - # secret_namespacing: true - - # 'cert_required' can be set to true to _require_ TLS client certificate - # authentication. - # type: boolean - # - # cert_required: false - - # 'alpn_protocols' is used to enable the TLS ALPN protocol. It is required - # if you want to do GRPC over TLS; typically it will be set to "h2" for that - # case. - # type: string (comma-separated list) - # - # alpn_protocols: None - - # 'min_tls_version' sets the minimum acceptable TLS version: v1.0, v1.1, - # v1.2, or v1.3. It defaults to v1.0. - # min_tls_version: v1.0 - - # 'max_tls_version' sets the maximum acceptable TLS version: v1.0, v1.1, - # v1.2, or v1.3. It defaults to v1.3. - # max_tls_version: v1.3 - - # Tells $productName$ to load TLS certificates from a file in its container. - # type: string - # - # cert_chain_file: None - # private_key_file: None - # cacert_chain_file: None -``` - - - - `secret` and (if used) `ca_secret` must specify Kubernetes Secrets containing valid TLS - certificates. If `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and either Secret contains - an invalid certificate, $productName$ will reject the Secret, which will also completely - disable any `Host` using the `TLSContext`; see [**Certificates and Secrets**](#certificates-and-secrets) - above. - - - -### ALPN protocols - -The `alpn_protocols` setting configures the TLS ALPN protocol. To use gRPC over -TLS, set `alpn_protocols: h2`. If you need to support HTTP/2 upgrade from -HTTP/1, set `alpn_protocols: h2,http/1.1` in the configuration. - -#### HTTP/2 support - -The `alpn_protocols` setting is also required for HTTP/2 support. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls -spec: - secret: ambassador-certs - hosts: ["*"] - alpn_protocols: h2[, http/1.1] -``` -Without setting alpn_protocols as shown above, HTTP2 will not be available via -negotiation and will have to be explicitly requested by the client. - -If you leave off http/1.1, only HTTP2 connections will be supported. - -### TLS parameters - -The `min_tls_version` setting configures the minimum TLS protocol version that -$productName$ will use to establish a secure connection. When a client -using a lower version attempts to connect to the server, the handshake will -result in the following error: `tls: protocol version not supported`. - -The `max_tls_version` setting configures the maximum TLS protocol version that -$productName$ will use to establish a secure connection. When a client -using a higher version attempts to connect to the server, the handshake will -result in the following error: -`tls: server selected unsupported protocol version`. - -The `cipher_suites` setting configures the supported ciphers found below using the -[configuration parameters for BoringSSL](https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#Cipher-suite-configuration) when negotiating a TLS 1.0-1.2 connection. -This setting has no effect when negotiating a TLS 1.3 connection. When a client does not -support a matching cipher a handshake error will result. - -The `ecdh_curves` setting configures the supported ECDH curves when negotiating -a TLS connection. When a client does not support a matching ECDH a handshake -error will result. - -``` - - AES128-SHA - - AES256-SHA - - AES128-GCM-SHA256 - - AES256-GCM-SHA384 - - ECDHE-RSA-AES128-SHA - - ECDHE-RSA-AES256-SHA - - ECDHE-RSA-AES128-GCM-SHA256 - - ECDHE-RSA-AES256-GCM-SHA384 - - ECDHE-RSA-CHACHA20-POLY1305 - - ECDHE-ECDSA-AES128-SHA - - ECDHE-ECDSA-AES256-SHA - - ECDHE-ECDSA-AES128-GCM-SHA256 - - ECDHE-ECDSA-AES256-GCM-SHA384 - - ECDHE-ECDSA-CHACHA20-POLY1305 - - ECDHE-PSK-AES128-CBC-SHA - - ECDHE-PSK-AES256-CBC-SHA - - ECDHE-PSK-CHACHA20-POLY1305 - - PSK-AES128-CBC-SHA - - PSK-AES256-CBC-SHA - - DES-CBC3-SHA -``` - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls -spec: - hosts: ["*"] - secret: ambassador-certs - min_tls_version: v1.0 - max_tls_version: v1.3 - cipher_suites: - - "[ECDHE-ECDSA-AES128-GCM-SHA256|ECDHE-ECDSA-CHACHA20-POLY1305]" - - "[ECDHE-RSA-AES128-GCM-SHA256|ECDHE-RSA-CHACHA20-POLY1305]" - ecdh_curves: - - X25519 - - P-256 -``` - - -The `crl_secret` field allows you to reference a Kubernetes Secret that contains a certificate revocation list. -If specified, $productName$ will verify that the presented peer certificate has not been revoked by this CRL even if they are otherwise valid. This provides a way to reject certificates before they expire or if they become compromised. -The `crl_secret` field takes a PEM-formatted [Certificate Revocation List](https://en.wikipedia.org/wiki/Certificate_revocation_list) in a `crl.pem` entry. - -Note that if a CRL is provided for any certificate authority in a trust chain, a CRL must be provided for all certificate authorities in that chain. Failure to do so will result in verification failure for both revoked and unrevoked certificates from that chain. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls-crl -spec: - hosts: ["*"] - secret: ambassador-certs - min_tls_version: v1.0 - max_tls_version: v1.3 - crl_secret: 'ambassador-crl' ---- -apiVersion: v1 -kind: Secret -metadata: - name: ambassador-crl - namespace: ambassador -type: Opaque -data: - crl.pem: | - {BASE64 CRL CONTENTS} ---- -``` diff --git a/content/en/docs/3.4/topics/running/tls/mtls.md b/content/en/docs/3.4/topics/running/tls/mtls.md deleted file mode 100644 index 1b039cf8..00000000 --- a/content/en/docs/3.4/topics/running/tls/mtls.md +++ /dev/null @@ -1,88 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Mutual TLS (mTLS) - -Many organizations have security concerns that require all network traffic -throughout their cluster be encrypted. With traditional architectures, -this was not that complicated of a requirement since internal network traffic -was fairly minimal. With microservices, we are making many more requests over -the network that must all be authenticated and secured. - -In order for services to authenticate with each other, they will each need to -provide a certificate and key that the other trusts before establishing a -connection. This action of both the client and server providing and validating -certificates is referred to as mutual TLS. - -## mTLS with $productName$ - -Since $productName$ is a reverse proxy acting as the entry point to your cluster, -$productName$ is acting as the client as it proxies requests to services upstream. - -It is trivial to configure $productName$ to simply originate TLS connections as -the client to upstream services by setting -`service: https://{{UPSTREAM_SERVICE}}` in the `Mapping` configuration. -However, in order to do mTLS with services upstream, $productName$ must also -have certificates to authenticate itself with the service. - -To do this, we can use the `TLSContext` object to get certificates from a -Kubernetes `Secret` and use those to authenticate with the upstream service. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: upstream-context -spec: - hosts: [] - secret: upstream-certs -``` - -We use `hosts: []` for this `TLSContext` since we do not want to use it to terminate -TLS connections from the client. We are just using this to load certificates for -requests upstream. - - - - The Kubernetes Secret must contain a valid TLS certificate. If the environment - variable `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) in the TLS overview. - - - -After loading the certificates, we can tell $productName$ when to use them by -setting the `tls` parameter in a `Mapping`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: upstream-mapping -spec: - hostname: "*" - prefix: /upstream/ - service: upstream-service - tls: upstream-context -``` - -Now, when $productName$ proxies a request to `upstream-service`, it will provide -the certificates in the `upstream-certs` secret for authentication when -encrypting traffic. - -## Service mesh - -As you can imagine, when you have many services in your cluster all -authenticating with each other, managing all of those certificates can become a -very big challenge. - -For this reason, many organizations rely on a service mesh for their -service-to-service authentication and encryption. - -$productName$ integrates with multiple service meshes and makes it easy to -configure mTLS to upstream services for all of them. Click the links below to -see how to configure $productName$ to do mTLS with any of these service meshes: - -- [Consul Connect](../../../../howtos/consul/) - -- [Istio](../../../../howtos/istio/) diff --git a/content/en/docs/3.4/topics/running/tls/origination.md b/content/en/docs/3.4/topics/running/tls/origination.md deleted file mode 100644 index b15dd5f8..00000000 --- a/content/en/docs/3.4/topics/running/tls/origination.md +++ /dev/null @@ -1,82 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# TLS origination - -Sometimes you may want traffic from $productName$ to your services to be encrypted. For the cases where terminating TLS at the ingress is not enough, $productName$ can be configured to originate TLS connections to your upstream services. - -## Basic configuration - -Telling $productName$ to talk to your services over HTTPS is easily configured in the `Mapping` definition by setting `https://` in the `service` field. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: basic-tls -spec: - hostname: "*" - prefix: / - service: https://example-service -``` - -## Advanced configuration using a `TLSContext` - -If your upstream services require more than basic HTTPS support (for example, providing a client certificate or -setting the minimum TLS version support) you must create a `TLSContext` for $productName$ to use when -originating TLS. For example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls-context -spec: - secret: self-signed-cert - min_tls_version: v1.3 - sni: some-sni-hostname -``` - - - - The Kubernetes Secret named by `secret` must contain a valid TLS certificate. If the - environment variable `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and the Secret contains - an invalid certificate, $productName$ will reject the `TLSContext` and prevent its use; - see [**Certificates and Secrets**](../#certificates-and-secrets) in the TLS overview. - - - -Configure $productName$ to use this `TLSContext` for connections to upstream services by setting the `tls` attribute of a `Mapping`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-with-tls-context -spec: - hostname: "*" - prefix: / - service: https://example-service - tls: tls-context -``` - -The `example-service` service must now support TLS v1.3 for $productName$ to connect. - - - - The Kubernetes Secret named by `secret` must contain a valid TLS certificate. If the - environment variable `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and the Secret contains - an invalid certificate, $productName$ will reject the `TLSContext` and prevent its use; - see [**Certificates and Secrets**](../#certificates-and-secrets) in the TLS overview. - - - - - - A `TLSContext` requires a certificate be provided, even in cases where the upstream - service does not require it (for origination) and the `TLSContext` is not being used - to terminate TLS. In this case, simply generate and provide a self-signed certificate. - - diff --git a/content/en/docs/3.4/topics/running/tls/sni.md b/content/en/docs/3.4/topics/running/tls/sni.md deleted file mode 100644 index 92e4992f..00000000 --- a/content/en/docs/3.4/topics/running/tls/sni.md +++ /dev/null @@ -1,103 +0,0 @@ -# Server Name Indication (SNI) - -$productName$ supports serving multiple `Host`s behind a single IP address, each -with their own certificate. - -This is as easy to do as creating a `Host` for each domain or subdomain you -want $productName$ to serve, getting a certificate for each, and telling -$productName$ which `Host` the route should be created for. - -The example below configures two `Host`s and assigns routes to them. - -## Configuring a `Host` - -The `Host` resources lets you separate configuration for each distinct domain -and subdomain you plan on serving behind $productName$. - -Let's start by creating a simple `Host` and providing our own certificate in -the `host-cert` secret. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: host-cert -``` - -Now let's create a second `Host` for a different domain we want to serve behind -$productName$. This second `Host` uses $AESproductName$'s automatic TLS -to get a certificate from Let's Encrypt. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: host.foo.com - acmeProvider: - email: julian@example.com -``` - -We now have two `Host`s with two different certificates. - - - A minimum version of TLS 1.1 is required to properly use SNI. When setting up your TLS configuration, be sure you are not using TLS 1.0 or older. - - -## Configuring routes - -Now that we have two domains behind $productName$, we can create routes for either -or both of them. - -We do this by setting the `hostname` attribute of a `Mapping` to the domain the -`Mapping` should be created for. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin -spec: - prefix: /httpbin/ - service: httpbin.org:80 - host_rewrite: httpbin.org - hostname: host.example.com -``` - -The above creates a `/httpbin/` endpoint for `host.example.com`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mockbin -spec: - prefix: /foo/ - service: foo-service - hostname: host.foo.com -``` - -The above creates a `/foo/` endpoint for `host.foo.com`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: frontend -spec: - hostname: "*" - prefix: /bar/ - service: bar-endpoint -``` - -The above creates a `/bar/` endpoint for all `Host`s. diff --git a/content/en/docs/3.4/topics/using/authservice.md b/content/en/docs/3.4/topics/using/authservice.md deleted file mode 100644 index cfe3598b..00000000 --- a/content/en/docs/3.4/topics/using/authservice.md +++ /dev/null @@ -1,23 +0,0 @@ -# AuthService settings - -A Mapping can pass these settings along to an [AuthService](../../running/services/auth-service). This is helpful to allow these specific configurations to apply only to certain Mappings and not globally. - -## Bypass authentication - -An AuthService can be disabled for a specific Mapping with the `bypass_auth` attribute. This will tell $productName$ to allow all requests for that Mapping through without interacting with the external auth service. This could be helpful, for example, for a public API. - -```yaml -bypass_auth: true -``` - -## Context extensions - -The `auth_context_extensions` attribute will pass the given values along to the AuthService when authentication happens. The values are arbitrary key value pairs formatted as strings. - -```yaml -auth_context_extensions: - foo: bar - baz: zing -``` - -More information is available on [the Envoy documentation on external authentication](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto.html#extensions-filters-http-ext-authz-v3-checksettings). diff --git a/content/en/docs/3.4/topics/using/canary.md b/content/en/docs/3.4/topics/using/canary.md deleted file mode 100644 index f99de1a3..00000000 --- a/content/en/docs/3.4/topics/using/canary.md +++ /dev/null @@ -1,41 +0,0 @@ -# Canary releases - -Canary releasing is a deployment pattern where a small percentage of traffic is diverted to an early ("canary") release of a particular service. This technique lets you test a release on a small subset of users, mitigating the impact of any given bug. Canary releasing also allows you to quickly roll back to a known good version in the event of an unexpected error. Detailed monitoring of core service metrics is an essential part of canary releasing, as monitoring enables the rapid detection of problems in the canary release. - -## Canary releases in Kubernetes - -Kubernetes supports a basic canary release workflow using its core objects. In this workflow, a service owner can create a Kubernetes [service](https://kubernetes.io/docs/concepts/services-networking/service/). This service can then be pointed to multiple [deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/). Each deployment can be a different version. By specifying the number of `replicas` in a given deployment, you can control how much traffic goes between different versions. For example, you could set `replicas: 3` for `v1`, and `replicas: 1` for `v2`, to ensure that 25% of traffic goes to `v2`. This approach works but is fairly coarse-grained unless you have lots of replicas. Moreover, auto-scaling doesn't work well with this strategy. - -## Canary releases in $productName$ - -$productName$ supports fine-grained canary releases. $productName$ uses a weighted round-robin scheme to route traffic between multiple services. Full metrics are collected for all services, making it easy to compare the relative performance of the canary and production. - -### The weight attribute - -The `weight` attribute specifies how much traffic for a given resource will be routed using a given mapping. Its value is an integer percentage between 0 and 100. $productName$ will balance weights to make sure that, for every resource, the mappings for that resource will have weights adding to 100%. (In the simplest case, a single mapping is guaranteed to receive 100% of the traffic no matter whether it's assigned a `weight` or not.) - -Specifying a weight only makes sense if you have multiple mappings for the same resource, and typically you would _not_ assign a weight to the "default" mapping (the mapping expected to handle most traffic): letting $productName$ assign that mapping all the traffic not otherwise spoken for tends to make life easier when updating weights. - -Here's an example, which might appear during a canary deployment: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - prefix: /backend/ - service: quotev2 - weight: 10 -``` - -In this case, the quote-backend2 will receive 10% of the requests for `/backend/`, and $productName$ will assign the remaining 90% to the quote-backend. diff --git a/content/en/docs/3.4/topics/using/circuit-breakers.md b/content/en/docs/3.4/topics/using/circuit-breakers.md deleted file mode 100644 index 97b40f57..00000000 --- a/content/en/docs/3.4/topics/using/circuit-breakers.md +++ /dev/null @@ -1,116 +0,0 @@ -# Circuit breakers - -Circuit breakers are a powerful technique to improve resilience. By preventing additional connections or requests to an overloaded service, circuit breakers limit the ["blast radius"](https://www.ibm.com/garage/method/practices/manage/practice_limited_blast_radius/) of an overloaded service. By design, $productName$ circuit breakers are distributed, i.e., different $productName$ instances do not coordinate circuit breaker information. - -## Circuit breaker configuration - -A default circuit breaking configuration can be set for all -$productName$ resources in the [`ambassador -Module`](../../running/ambassador), or set to a different value on a -per-resource basis for [`Mappings`](../mappings), -[`TCPMappings`](../tcpmappings/), and -[`AuthServices`](../../running/services/auth-service/). - -The `circuit_breakers` attribute configures circuit breaking. The following fields are supported: - -```yaml -circuit_breakers: -- priority: - max_connections: - max_pending_requests: - max_requests: - max_retries: -``` - -|Key|Default value|Description| -|---|---|---| -|`priority`|`default`|Specifies the priority to which the circuit breaker settings apply to; it can be set to either `default` or `high`.| -|`max_connections`|`1024`|Specifies the maximum number of connections that $productName$ will make to the services. In practice, this is more applicable to HTTP/1.1 than HTTP/2.| -|`max_pending_requests`|`1024`|Specifies the maximum number of requests that will be queued while waiting for a connection. In practice, this is more applicable to HTTP/1.1 than HTTP/2.| -|`max_requests`|`1024`|Specifies the maximum number of parallel outstanding requests to an upstream service. In practice, this is more applicable to HTTP/2 than HTTP/1.1.| -|`max_retries`|`3`|Specifies the maximum number of parallel retries allowed to an upstream service.| - -The `max_*` fields can be reduced to shrink the "blast radius," or -increased to enable $productName$ to handle a larger number of -concurrent requests. - -## Examples - -Circuit breakers defined on a single `Mapping`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - circuit_breakers: - - max_connections: 2048 - max_pending_requests: 2048 -``` - -Circuit breakers defined on a single `AuthService`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: AuthService -metadata: - name: dancing-walrus -spec: - auth_service: http://dancing-walrus:8500 - proto: grpc - circuit_breakers: - - max_requests: 4096 -``` - -A global circuit breaker: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - circuit_breakers: - - max_connections: 2048 - max_pending_requests: 2048 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote -``` - -## Circuit breakers and automatic retries - -Circuit breakers are best used in conjunction with [automatic retries](../retries). Here are some examples: - -* You've configured automatic retries for failed requests to a service. Your service is under heavy load, and starting to time out on servicing requests. In this case, automatic retries can exacerbate your problem, increasing the total request volume by 2x or more. By aggressively circuit breaking, you can mitigate failure in this scenario. -* To circuit break when services are slow, you can combine circuit breakers with retries. Reduce the time out for retries, and then set a circuit breaker that detects many retries. In this setup, if your service doesn't respond quickly, a flood of retries will occur, which can then trip the circuit breaker. - -Note that setting circuit breaker thresholds requires careful monitoring and experimentation. We recommend you start with conservative values for circuit breakers and adjust them over time. - -## More about circuit breakers - -Responses from a broken circuit contain the `x-envoy-overloaded` header. - -The following are the default values for circuit breaking if nothing is specified: - -```yaml -circuit_breakers: -- priority: default - max_connections: 1024 - max_pending_requests: 1024 - max_requests: 1024 - max_retries: 3 -``` - -Circuit breaker metrics are exposed in StatsD. For more information about the specific statistics, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/circuit_breaking.html). diff --git a/content/en/docs/3.4/topics/using/cors.md b/content/en/docs/3.4/topics/using/cors.md deleted file mode 100644 index 315e4694..00000000 --- a/content/en/docs/3.4/topics/using/cors.md +++ /dev/null @@ -1,155 +0,0 @@ -# Cross-Origin Resource Sharing (CORS) - -Cross-Origin resource sharing lets users request resources (e.g., images, fonts, videos) from domains outside the original domain. - -CORS configuration can be set for all $productName$ mappings in the [`ambassador Module`](../../running/ambassador), or set per [`Mapping`](../mappings). - -When the CORS attribute is set at either the `Mapping` or `Module` level, $productName$ will intercept the pre-flight `OPTIONS` request and respond with the appropriate CORS headers. This means you will not need to implement any logic in your upstreams to handle these CORS `OPTIONS` requests. - -The flow of the request will look similar to the following: -``` -Client $productName$ Upstream - | OPTIONS | | - | —————————————————> | | - | CORS_RESP | | - | <————————————————— | | - | GET /foo/ | | - | —————————————————> | ————————————> | - | | RESP | - | <————————————————————————————————— | -``` -## The `cors` attribute - -The `cors` attribute enables the CORS filter. The following settings are supported: - -- `origins`: Specifies a list of allowed domains for the `Access-Control-Allow-Origin` header. To allow all origins, use the wildcard `"*"` value. Format can be either of: - - comma-separated list, e.g. - ```yaml - origins: http://foo.example,http://bar.example - ``` - - YAML array, e.g. - ```yaml - origins: - - http://foo.example - - http://bar.example - ``` - -- `methods`: if present, specifies a list of allowed methods for the `Access-Control-Allow-Methods` header. Format can be either of: - - comma-separated list, e.g. - ```yaml - methods: POST, GET, OPTIONS - ``` - - YAML array, e.g. - ```yaml - methods: - - GET - - POST - - OPTIONS - ``` - -- `headers`: if present, specifies a list of allowed headers for the `Access-Control-Allow-Headers` header. Format can be either of: - - comma-separated list, e.g. - ```yaml - headers: Content-Type - ``` - - YAML array, e.g. - ```yaml - headers: - - Content-Type - ``` - -- `credentials`: if present with a true value (boolean), will send a `true` value for the `Access-Control-Allow-Credentials` header. - -- `exposed_headers`: if present, specifies a list of allowed headers for the `Access-Control-Expose-Headers` header. Format can be either of: - - comma-separated list, e.g. - ```yaml - exposed_headers: X-Custom-Header - ``` - - YAML array, e.g. - ```yaml - exposed_headers: - - X-Custom-Header - ``` - -- `max_age`: if present, indicated how long the results of the preflight request can be cached, in seconds. This value must be a string. - -## Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cors -spec: - prefix: /cors/ - service: cors-example - cors: - origins: http://foo.example,http://bar.example - methods: POST, GET, OPTIONS - headers: Content-Type - credentials: true - exposed_headers: X-Custom-Header - max_age: "86400" -``` - -## AuthService and Cross-Origin Resource Sharing - -When you use external authorization, each incoming request is authenticated before routing to its destination, including pre-flight `OPTIONS` requests. - -By default, many [`AuthService`](../../running/services/auth-service) implementations will deny these requests. If this is the case, you will need to add some logic to your `AuthService` to accept all CORS headers. - -For example, a possible configuration for Spring Boot 2.0.1: - -```java -@EnableWebSecurity -class SecurityConfig extends WebSecurityConfigurerAdapter { - - public void configure(final HttpSecurity http) throws Exception { - http - .cors().configurationSource(new PermissiveCorsConfigurationSource()).and() - .csrf().disable() - .authorizeRequests() - .antMatchers("**").permitAll(); - } - - private static class PermissiveCorsConfigurationSource implements CorsConfigurationSource { - /** - * Return a {@link CorsConfiguration} based on the incoming request. - * - * @param request - * @return the associated {@link CorsConfiguration}, or {@code null} if none - */ - @Override - public CorsConfiguration getCorsConfiguration(final HttpServletRequest request) { - final CorsConfiguration configuration = new CorsConfiguration(); - configuration.setAllowCredentials(true); - configuration.setAllowedHeaders(Collections.singletonList("*")); - configuration.setAllowedMethods(Collections.singletonList("*")); - configuration.setAllowedOrigins(Collections.singletonList("*")); - return configuration; - } - } -} -``` - -This is okay since CORS is being handled by $productName$ after authentication. - -The flow of this request will look similar to the following: - -``` -Client $productName$ Auth Upstream - | OPTIONS | | | - | —————————————————> | ————————————> | | - | | CORS_ACCEPT_* | | - | CORS_RESP |<——————————————| | - | <——————————————————| | | - | GET /foo/ | | | - | —————————————————> | ————————————> | | - | | AUTH_RESP | | - | | <———————————— | | - | | AUTH_ALLOW | | - | | ————————————————————————————> | - | | | RESP | - | <————————————————————————————————————————————————— | - ``` diff --git a/content/en/docs/3.4/topics/using/defaults.md b/content/en/docs/3.4/topics/using/defaults.md deleted file mode 100644 index d08a84d8..00000000 --- a/content/en/docs/3.4/topics/using/defaults.md +++ /dev/null @@ -1,32 +0,0 @@ -# Using `ambassador` `Module` defaults - -## The defaults element - -If present, the `ambassador Module` can define a set of defaults that will automatically be applied to certain resources: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - class1: # This is a class. Different resource types will look in different classes. - key1: value1 # Within a class, you can set different keys. - key2: value2 - ... - class2: - ... - top_key1: value1 # If a key isn't found in a resource's class, the system will look in the - top_key2: value2 # toplevel defaults dictionary for it. -``` - -### Mapping - -Currently, only the `Mapping` resource uses the `defaults` mechanism. `Mapping` looks first for defaultable resources in the `httpmapping` class, including: - -- [`add_request_headers`](../../using/headers/add-request-headers) -- [`add_response_headers`](../../using/headers/add-response-headers) -- [`remove_request_headers`](../../using/headers/remove-request-headers) -- [`remove_response_headers`](../../using/headers/remove-response-headers) diff --git a/content/en/docs/3.4/topics/using/gateway-api.md b/content/en/docs/3.4/topics/using/gateway-api.md deleted file mode 100644 index 5e92cd0d..00000000 --- a/content/en/docs/3.4/topics/using/gateway-api.md +++ /dev/null @@ -1,19 +0,0 @@ -# Gateway API - -## Using the Gateway API - -$productName$ now supports a limited subset of the new `v1alpha1` [Gateway API](https://gateway-api.sigs.k8s.io/). -Note that the Gateway API is not supported when `AMBASSADOR_LEGACY_MODE` is set. - -Support is currently limited to the following fields, however this will expand in future releases: - - - `Gateway.spec.listeners.port` - - `HTTPRoute.spec.rules.matches.path.type` (`Exact`, `Prefix`, and `RegularExpression`) - - `HTTPRoute.spec.rules.matches.path.value` - - `HTTPRoute.spec.rules.matches.header.type` (`Exact` and `RegularExpression`) - - `HTTPRoute.spec.rules.matches.header.values` - - `HTTPRoute.spec.rules.forwardTo.serviceName` - - `HTTPRoute.spec.rules.forwardTo.port` - - `HTTPRoute.spec.rules.forwardTo.weight` - -Please see the [specification](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/) for more details. diff --git a/content/en/docs/3.4/topics/using/headers/add-request-headers.md b/content/en/docs/3.4/topics/using/headers/add-request-headers.md deleted file mode 100644 index c6ad4956..00000000 --- a/content/en/docs/3.4/topics/using/headers/add-request-headers.md +++ /dev/null @@ -1,77 +0,0 @@ -# Add request headers - -$productName$ can add a dictionary of HTTP headers that can be added to each request that is passed to a service. - -## The `add_request_headers` attribute - -The `add_request_headers` attribute is a dictionary of `header`: `value` pairs. The `value` can be a `string`, `bool` or `object`. When it is an `object`, the object should have a `value` property, which is the actual header value, and the remaining attributes are additional envoy properties. - -Envoy dynamic values `%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%` and `%PROTOCOL%` are supported, in addition to static values. - -`add_request_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -### Mapping example - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: "*" - prefix: /backend/ - add_request_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-static-2: - value: This the test header #same as above "x-test-static header" - x-test-object: - value: This the value - append: False #True by default - service: quote - ``` - -will add the protocol, client IP, and a static header to `/backend/`. - -### Defaults example - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - add_request_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-static-2: - value: This the test header #same as above "x-test-static header" - x-test-object: - value: This the value - append: False #True by default ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - hostname: "*" - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - hostname: "*" - prefix: /backend2/ - service: quote -``` - -This example will add the same headers for both mappings. diff --git a/content/en/docs/3.4/topics/using/headers/add-response-headers.md b/content/en/docs/3.4/topics/using/headers/add-response-headers.md deleted file mode 100644 index 236ace61..00000000 --- a/content/en/docs/3.4/topics/using/headers/add-response-headers.md +++ /dev/null @@ -1,73 +0,0 @@ -# Add response headers - -$productName$ can add a dictionary of HTTP headers that can be added to each response that is returned to the client. - -## The `add_response_headers` attribute - -The `add_response_headers` attribute is a dictionary of `header`: `value` pairs. The `value` can be a `string`, `bool` or `object`. When it is an `object`, the object should have a `value` property, which is the actual header value, and the remaining attributes are additional envoy properties. - -Envoy dynamic values `%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%` and `%PROTOCOL%` are supported, in addition to static values. - -`add_response_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -### Mapping example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - add_response_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-object: - append: False - value: this is from object header config - service: quote -``` - -will add the protocol, client IP, and a static header to the response returned to the client. - -### Defaults example - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - add_response_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-object: - append: False - value: this is from object header config ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - hostname: "*" - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - hostname: "*" - prefix: /backend2/ - service: quote -``` - -This example will add the same headers for both mappings. diff --git a/content/en/docs/3.4/topics/using/headers/headers.md b/content/en/docs/3.4/topics/using/headers/headers.md deleted file mode 100644 index 126653b0..00000000 --- a/content/en/docs/3.4/topics/using/headers/headers.md +++ /dev/null @@ -1,76 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Header-based routing - -$productName$ can route to target services based on HTTP headers with the `headers` and `regex_headers` specifications. Multiple mappings with different annotations can be applied to construct more complex routing rules. - -## The `headers` annotation - -The `headers` attribute is a dictionary of `header`: `value` pairs. $productName$ will only allow requests that match the specified `header`: `value` pairs to reach the target service. - -### Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - headers: - x-quote-mode: backend - x-random-header: datawire -``` - -will allow requests to /backend/ to succeed only if the x-quote-mode header has the value backend and the x-random-header has the value `datawire`. - - - 1.x versions of the Ambassador Edge Stack could test for the existence of a header using x-sample-header:true. Since 2.0, the same functionality is achieved by using regex_headers. - - -## Regex headers - -You can also set the `value` of a regex header to `".*"` to test for the existence of a header. - -### Conditional example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-mode -spec: - prefix: /backend/ - service: quote-mode - regex_headers: - x-quote-mode: ".*" - ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-regular -spec: - prefix: /backend/ - service: quote-regular -``` - -will send requests that contain the x-quote-mode header to the quote-mode target, while routing all other requests to the quote-regular target. - -The following mapping will route mobile requests from Android and iPhones to a mobile service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - regex_headers: - user-agent: ".*(iPhone|(a|A)ndroid).*" - prefix: /backend/ - service: quote -``` diff --git a/content/en/docs/3.4/topics/using/headers/host.md b/content/en/docs/3.4/topics/using/headers/host.md deleted file mode 100644 index 5a8dd02c..00000000 --- a/content/en/docs/3.4/topics/using/headers/host.md +++ /dev/null @@ -1,76 +0,0 @@ -# Host headers - -$productName$ supports several different methods for managing the HTTP `Host` header. - -## Using `host` and `host_regex` - -A mapping that specifies the `host` attribute will take effect _only_ if the HTTP `Host` header matches the value in the `host` attribute. If `host_regex` is `true`, the `host` value is taken to be a regular expression. Otherwise, an exact string match is required. - -You may have multiple mappings listing the same resource but different `host` attributes to effect `Host`-based routing. An example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote1 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend-2 -spec: - prefix: /backend/ - host: quote.datawire.io - service: quote2 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend-3 -spec: - prefix: /backend/ - host: "^quote[2-9]\\.datawire\\.io$" - host_regex: true - service: quote3 -``` - -will map requests for `/` to - -- the `quote2` service if the `Host` header is `quote.datawire.io`; -- the `quote3` service if the `Host` header matches `^quote[2-9]\\.datawire\\.io$`; and to -- the `quote1` service otherwise. - -Note that enclosing regular expressions in quotes can be important to prevent backslashes from being doubled. - -## Using `host_rewrite` - -By default, the `Host` header is not altered when talking to the service -- whatever `Host` header the client gave to $productName$ will be presented to the service. For many microservices, this will be fine, but if you use $productName$ to route to services that use the `Host` header for routing, it's likely to fail (legacy monoliths are particularly susceptible to this, as well as external services). You can use `host_rewrite` to force the `Host` header to whatever value that such target services need. - -An example: the default $productName$ configuration includes the following mapping for `httpbin.org`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin -spec: - prefix: /httpbin/ - service: httpbin.org:80 - host_rewrite: httpbin.org -``` - -As it happens, `httpbin.org` is virtually hosted, and it simply _will not_ function without a `Host` header of `httpbin.org`, which means that the `host_rewrite` attribute is necessary here. - -## `host` and `method` - -Internally: - -- the `host` attribute becomes a `header` match on the `:authority` header; and -- the `method` attribute becomes a `header` match on the `:method` header. - -You will see these headers in the diagnostic service if you use the `method` or `host` attributes. diff --git a/content/en/docs/3.4/topics/using/headers/remove-request-headers.md b/content/en/docs/3.4/topics/using/headers/remove-request-headers.md deleted file mode 100644 index 62603756..00000000 --- a/content/en/docs/3.4/topics/using/headers/remove-request-headers.md +++ /dev/null @@ -1,57 +0,0 @@ -# Remove request headers - -$productName$ can remove a list of HTTP headers that would be sent to the upstream from the request. - -## The `remove_request_headers` attribute - -The `remove_request_headers` attribute takes a list of keys used to match to the header. - -`remove_request_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -## Mapping example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - remove_request_headers: - - authorization - service: quote -``` - -will drop the header with key `authorization`. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - remove_request_headers: - - authorization ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - prefix: /backend2/ - service: quote -``` - -This is the same as the mapping example, but the headers will be removed for both mappings. diff --git a/content/en/docs/3.4/topics/using/headers/remove-response-headers.md b/content/en/docs/3.4/topics/using/headers/remove-response-headers.md deleted file mode 100644 index 16b18569..00000000 --- a/content/en/docs/3.4/topics/using/headers/remove-response-headers.md +++ /dev/null @@ -1,57 +0,0 @@ -# Remove response headers - -$productName$ can remove a list of HTTP headers that would be sent to the client in the response (e.g. default `x-envoy-upstream-service-time`). - -## The `remove_response_headers` attribute - -The `remove_response_headers` attribute takes a list of keys used to match to the header. - -`remove_request_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -## Mapping example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - remove_response_headers: - - x-envoy-upstream-service-time - service: quote -``` - -will drop the header with key `x-envoy-upstream-service-time`. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - remove_response_headers: - - x-envoy-upstream-service-time ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - prefix: /backend2/ - service: quote -``` - -This is the same as the mapping example, but the headers will be removed for both mappings. diff --git a/content/en/docs/3.4/topics/using/index.md b/content/en/docs/3.4/topics/using/index.md deleted file mode 100644 index d4f09a83..00000000 --- a/content/en/docs/3.4/topics/using/index.md +++ /dev/null @@ -1,32 +0,0 @@ -# Using $productName$ - -Application development teams use $productName$ to manage edge policies associated with a specific service. This section of the documentation covers core $productName$ elements that are typically used by the application development team. - -* [Introduction to Mappings](intro-mappings) The `Mapping` resource is the core resource used by every application development team. -* Mapping Configuration: - * [Automatic Retries](retries) - * [Canary Releases](canary) - * [Circuit Breakers](circuit-breakers) - * [Cross Origin Resource Sharing](cors) - * HTTP Headers - * [Header-based Routing](headers/headers) - * [Host Header](headers/host) - * [Adding Request Headers](headers/add-request-headers) - * [Adding Response Headers](headers/add-response-headers) - * [Removing Request Headers](headers/remove-request-headers) - * [Remove Response Headers](headers/remove-response-headers) - * [Query Parameter Based Routing](query-parameters) - * [Keepalive](keepalive) - * Protocols - * [TCP](tcpmappings) - * gRPC, HTTP/1.0, gRPC-Web, WebSockets - * [RegEx-based Routing](prefix-regex) - * [Redirects](redirects) - * [Rewrites](rewrites) - * [Timeouts](timeouts) - * [Traffic Shadowing](shadowing) -* [Advanced Mapping Configuration](mappings) -* Rate Limiting - * [Introduction to Rate Limits](rate-limits/) -* [Developer Portal](../../tutorials/dev-portal-tutorial) -* [Gateway API](gateway-api) diff --git a/content/en/docs/3.4/topics/using/intro-mappings.md b/content/en/docs/3.4/topics/using/intro-mappings.md deleted file mode 100644 index 51656052..00000000 --- a/content/en/docs/3.4/topics/using/intro-mappings.md +++ /dev/null @@ -1,148 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Introduction to the Mapping resource - -$productName$ is designed around a [declarative, self-service management model](../../concepts/gitops-continuous-delivery). The core resource used to support application development teams who need to manage the edge with $productName$ is the `Mapping` resource. - - - Remember that Listener and Host resources are -  required for a functioning $productName$ installation that can route traffic!
- Learn more about Listener.
- Learn more about Host. - - -## Quick example - -At its core a `Mapping` resource maps a `resource` to a `service`: - -| Required attribute | Description | -| :------------------------ | :------------------------ | -| `name` | is a string identifying the `Mapping` (e.g. in diagnostics) | -| [`prefix`](#resources) | is the URL prefix identifying your [resource](#resources) | -| [`service`](#services) | is the name of the [service](#services) handling the resource; must include the namespace (e.g. `myservice.othernamespace`) if the service is in a different namespace than $productName$ | - -These resources are defined as Kubernetes Custom Resource Definitions. Here's a simple example that maps all requests to `/httpbin/` to the `httpbin.org` web service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin-mapping -spec: - prefix: /httpbin/ - service: http://httpbin.org -``` - -## Applying a Mapping resource - -A `Mapping` resource can be managed using the same workflow as any other Kubernetes resources (e.g., `service`, `deployment`). For example, if the above `Mapping` is saved into a file called `httpbin-mapping.yaml`, the following command will apply the configuration directly to $productName$: - -``` -kubectl apply -f httpbin-mapping.yaml -``` - -For production use, the general recommended best practice is to store the file in a version control system and apply the changes with a continuous deployment pipeline. For more detail, see [the Ambassador Operating Model](../../concepts/gitops-continuous-delivery). - -## Extending Mappings - -`Mapping` resources support a rich set of annotations to customize the specific routing behavior. Here's an example service for implementing the CQRS pattern (using HTTP): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-get -spec: - prefix: /cqrs/ - method: GET - service: getcqrs ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-put -spec: - prefix: /cqrs/ - method: PUT - service: putcqrs -``` - -More detail on each of the available annotations are discussed in subsequent sections. - -## Resources - -To $productName$, a `resource` is a group of one or more URLs that all share a common prefix in the URL path. For example: - -``` -https://ambassador.example.com/resource1/foo -https://ambassador.example.com/resource1/bar -https://ambassador.example.com/resource1/baz/zing -https://ambassador.example.com/resource1/baz/zung -``` - -all share the `/resource1/` path prefix, so it can be considered a single resource. On the other hand: - -``` -https://ambassador.example.com/resource1/foo -https://ambassador.example.com/resource2/bar -https://ambassador.example.com/resource3/baz/zing -https://ambassador.example.com/resource4/baz/zung -``` - -share only the prefix `/` -- you _could_ tell $productName$ to treat them as a single resource, but it's probably not terribly useful. - -Note that the length of the prefix doesn't matter: if you want to use prefixes like `/v1/this/is/my/very/long/resource/name/`, go right ahead, $productName$ can handle it. - -Also note that $productName$ does not actually require the prefix to start and end with `/` -- however, in practice, it's a good idea. Specifying a prefix of - -``` -/man -``` - -would match all of the following: - -``` -https://ambassador.example.com/man/foo -https://ambassador.example.com/mankind -https://ambassador.example.com/man-it-is/really-hot-today -https://ambassador.example.com/manohmanohman -``` - -which is probably not what was intended. - -## Services - -$productName$ routes traffic to a `service`. A `service` is defined as: - -``` -[scheme://]service[.namespace][:port] -``` - -Where everything except for the `service` is optional. - -- `scheme` can be either `http` or `https`; if not present, the default is `http`. -- `service` is the name of a service (typically the service name in Kubernetes or Consul); it is not allowed to contain the `.` character. -- `namespace` is the namespace in which the service is running. Starting with $productName$ 1.0.0, if not supplied, it defaults to the namespace in which the Mapping resource is defined. The default behavior can be configured using the [`ambassador` Module](../../running/ambassador). When using a Consul resolver, `namespace` is not allowed. -- `port` is the port to which a request should be sent. If not specified, it defaults to `80` when the scheme is `http` or `443` when the scheme is `https`. Note that the [resolver](../../running/resolvers) may return a port in which case the `port` setting is ignored. - -Note that while using `service.namespace.svc.cluster.local` may work for Kubernetes resolvers, the preferred syntax is `service.namespace`. - -## Best practices for configuration - -$productName$'s configuration is assembled from multiple YAML blocks which are managed by independent application teams. This implies: - -- $productName$'s configuration should be under version control. - - While you can always read back the $productName$'s configuration from Kubernetes or its diagnostic service, the $productName$ will not do versioning for you. - -- Be aware that the $productName$ tries to not start with a broken configuration, but it's not perfect. - - Gross errors will result in $productName$ refusing to start, in which case `kubectl logs` will be helpful. However, it's always possible to e.g. map a resource to the wrong service, or use the wrong `rewrite` rules. $productName$ can't detect that on its own, although its diagnostic pages can help you figure it out. - -- Be careful of mapping collisions. - - If two different developers try to map `/user/` to something, this can lead to unexpected behavior. $productName$'s canary-deployment logic means that it's more likely that traffic will be split between them than that it will throw an error -- again, the diagnostic service can help you here. - -**Note:** Unless specified, mapping attributes cannot be applied to any other resource type. diff --git a/content/en/docs/3.4/topics/using/keepalive.md b/content/en/docs/3.4/topics/using/keepalive.md deleted file mode 100644 index d75e96ba..00000000 --- a/content/en/docs/3.4/topics/using/keepalive.md +++ /dev/null @@ -1,70 +0,0 @@ -# Keepalive - -Keepalive option indicates whether `SO_KEEPALIVE` on the socket should be enabled. - -## Keepalive configuration - -Keepalive configuration can be set for all $productName$ mappings in the [`ambassador Module`](../../running/ambassador) or set per [`Mapping`](../mappings). - -The `keepalive` attribute configures keepalive. The following fields are supported: - -```yaml -keepalive: - idle_time: - interval: - probes: -``` - -### `idle_time` - -(Default: `7200`) The number of seconds a connection needs to be idle before keep-alive probes start being sent. - -### `interval` - -(Default: `75`) The number of seconds between keep-alive probes. - -### `probes` - -(Default: `9`) is the maximum number of keepalive probes to send without response before deciding the connection is dead. - -## Examples - -Keepalive probes defined on a single mapping: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - keepalive: - idle_time: 100 - interval: 10 - probes: 9 -``` - -A global keepalive configuration: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - keepalive: - idle_time: 100 - interval: 10 - probes: 9 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote -``` diff --git a/content/en/docs/3.4/topics/using/mappings.md b/content/en/docs/3.4/topics/using/mappings.md deleted file mode 100644 index f930fc62..00000000 --- a/content/en/docs/3.4/topics/using/mappings.md +++ /dev/null @@ -1,189 +0,0 @@ -# Advanced Mapping configuration - -$productName$ is designed so that the author of a given Kubernetes service can easily and flexibly configure how traffic gets routed to the service. The core abstraction used to support service authors is a mapping, which maps a target backend service to a given host or prefix. For Layer 7 protocols such as HTTP, gRPC, or WebSockets, the `Mapping` resource is used. For TCP, the `TCPMapping` resource is used. - -$productName$ _must_ have one or more mappings defined to provide access to any services at all. The name of the mapping must be unique. - -## System-wide defaults for Mappings - -Certain aspects of mappings can be set system-wide using the `defaults` element of the `ambassador Module`: -see [using defaults](../../using/defaults) for more information. The `Mapping` element will look first in -the `httpmapping` default class. - -## Mapping evaluation order - -$productName$ sorts mappings such that those that are more highly constrained are evaluated before those less highly constrained. The prefix length, the request method, constraint headers, and query parameters are all taken into account. - -If absolutely necessary, you can manually set a `precedence` on the mapping (see below). In general, you should not need to use this feature unless you're using the `regex_headers` or `host_regex` matching features. If there's any question about how $productName$ is ordering rules, the diagnostic service is a good first place to look: the order in which mappings appear in the diagnostic service is the order in which they are evaluated. - -## Optional fallback Mapping - -$productName$ will respond with a `404 Not Found` to any request for which no mapping exists. If desired, you can define a fallback "catch-all" mapping so all unmatched requests will be sent to an upstream service. - -For example, defining a mapping with only a `/` prefix will catch all requests previously unhandled and forward them to an external service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: catch-all -spec: - prefix: / - service: https://www.getambassador.io -``` - -### Using `precedence` - -$productName$ sorts mappings such that those that are more highly constrained are evaluated before those less highly constrained. The prefix length, the request method, and the constraint headers are all taken into account. These mechanisms, however, may not be sufficient to guarantee the correct ordering when regular expressions or highly complex constraints are in play. - -For those situations, a `Mapping` can explicitly specify the `precedence`. A `Mapping` with no `precedence` is assumed to have a `precedence` of 0; the higher the `precedence` value, the earlier the `Mapping` is attempted. - -If multiple `Mapping`s have the same `precedence`, $productName$'s normal sorting determines the ordering within the `precedence`; however, there is no way that $productName$ can ever sort a `Mapping` with a lower `precedence` ahead of one at a higher `precedence`. - -### Using `tls` - -To originate TLS, use a `service` with an `https://` prefix. By itself, this will cause $productName$ to originate TLS without presenting a client certificate to the upstream service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-no-cert -spec: - prefix: /prefix/ - service: https://upstream/ -``` - -If you do need to supply a client certificate, you will also need to set `tls` to the name of a defined TLS context. The client certificate given in that context will be presented to the upstream service. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-with-cert -spec: - prefix: /prefix/ - service: https://upstream/ - tls: upstream-cert-context -``` - -(If `tls` is present, $productName$ will originate TLS even if the `service` does not have an `https://` prefix.) - -### Using `cluster_tag` - -If the `cluster_tag` attribute is present, its value will be prepended to cluster names generated from -the `Mapping`. This provides a simple mechanism for customizing the `cluster` name when working with metrics. - -## Using `dns_type` - -If the `dns_type` attribute is present, its value will determine how the DNS is used when locating the upstream service. Valid values are: - -- `strict_dns` (the default): The DNS result is assumed to define the exact membership of the cluster. For example, if DNS returns three IP addresses, the cluster is assumed to have three distinct upstream hosts. If a successful DNS query returns no hosts, the cluster is assumed to be empty. `strict_dns` makes sense for situations like a Kubernetes service, where DNS resolution is fast and returns a relatively small number of IP addresses. - -- `logical_dns`: Instead of assuming that the DNS result defines the full membership of the cluster, every new connection simply uses the first IP address returned by DNS. `logical_dns` makes sense for a service with a large number of IP addresses using round-robin DNS for upstream load balancing: typically each DNS query returns a different first result, and it is not necessarily possible to know the full membership of the cluster. With `logical_dns`, no attempt is made to garbage-collect connections: they will stay open until the upstream closes them. - -If `dns_type` is not given, `strict_dns` is the default, as this is the most conservative choice. When interacting with large web services with many IP addresses, switching to `logical_dns` may be a better choice. For more on the different types of DNS, see the [`strict_dns` Envoy documentation] or the [`logical_dns` Envoy documentation]. - -[`strict_dns` Envoy documentation]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/service_discovery#strict-dns -[`logical_dns` Envoy documentation]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/service_discovery#logical-dns - - -## Namespaces and Mappings - -If `AMBASSADOR_NAMESPACE` is correctly set, $productName$ can map to services in other namespaces by taking advantage of Kubernetes DNS: - -- `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. - -### Linkerd interoperability (`add_linkerd_headers`) - -When using Linkerd, requests going to an upstream service need to include the `l5d-dst-override` header to ensure that Linkerd will route them correctly. Setting `add_linkerd_headers` does this automatically, based on the `service` attribute in the `Mapping`. - -If `add_linkerd_headers` is not specified for a given `Mapping`, the default is taken from the `ambassador`[Module](../../running/ambassador). The overall default is `false`: you must explicitly enable `add_linkerd_headers` for $productName$ to add the header for you (although you can always add it yourself with `add_request_headers`, of course). - -### "Upgrading" to non-HTTP protocols (`allow_upgrade`) - -HTTP has [a mechanism][upgrade-mechanism] where the client can say -`Connection: upgrade` / `Upgrade: PROTOCOL` to switch ("upgrade") from -the current HTTP version to a different one, or even a different -protocol entirely. $productName$ itself understands and can handle the -different HTTP versions, but for other protocols you need to tell -$productName$ to get out of the way, and let the client speak that -protocol directly with your upstream service. You can do this by -setting the `allow_upgrade` field to a case-insensitive list of -protocol names $productName$ will allow switching to from HTTP. After -the upgrade, $productName$ does not interpret the traffic, and behaves -similarly to how it does for `TCPMapping`s. - -[upgrade-mechanism]: https://tools.ietf.org/html/rfc7230#section-6.7 - -This "upgrade" mechanism is a useful way of adding HTTP-based -authentication and access control to another protocol that might not -support authentication; for this reason the designers of the WebSocket -protocol made this "upgrade" mechanism the *only* way of initiating a -WebSocket connection. In a Mapping for an upstream service that -supports WebSockets, you would write - -```yaml -allow_upgrade: -- websocket -``` - -The Kubernetes apiserver itself uses this "upgrade" mechanism to -perform HTTP authentication before switching to SPDY for endpoint used -by `kubectl exec`; if you wanted to use $productName$ to expose the -Kubernetes apiserver such that `kubectl exec` functions, you would -write - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: apiserver -spec: - hostname: "*" - service: https://kubernetes.default - prefix: / - allow_upgrade: - - spdy/3.1 -``` - -There is a deprecated setting `use_websocket`; setting `use_websocket: -true` is equivalent to setting `allow_upgrade: ["websocket"]`. - -## DNS configuration for Mappings - -`respect_dns_ttl` can be set to `true` to force the DNS refresh rate for this `Mapping` to be set to the record’s TTL obtained from DNS resolution. -- Allowed values: `true` or `false` -- Default: `false` - - -`dns_type` can be used to configure the service discovery type between Strict DNS and Logical DNS. You can -- Allowed values: - - `strict_dns`: Ambassador will continuously and asynchronously resolve the specified DNS targets. - - `logical_dns`: Similar to `strict_dns`, but only uses the first IP address returned when a new connection needs to be initiated and Connections are never drained. More optimal for large scale web services that must be accessed via DNS. -- Default: `strict_dns` - - -For more information on the differences between dns types, see [the Envoy documentation for service discovery](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/service_discovery.html). - -> **Note:** When the [endpoint resolver](../../running/resolvers/#the-kubernetes-endpoint-resolver) is used in a `Mapping`, `dns_type` will be ignored in favor of the endpoint resolver's service discovery. - - - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: dnsoverwrite -spec: - service: quote - prefix: /backend/ - dns_type: logical_dns - respect_dns_ttl: true -``` diff --git a/content/en/docs/3.4/topics/using/method.md b/content/en/docs/3.4/topics/using/method.md deleted file mode 100644 index 94185dcd..00000000 --- a/content/en/docs/3.4/topics/using/method.md +++ /dev/null @@ -1,26 +0,0 @@ -# Method-based routing - -$productName$ supports routing based on the HTTP method and regular expression. - -## Using `method` - -The `method` annotation specifies the specific HTTP method for a mapping. The value of the `method` annotation must be in all upper case. - -For example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: get -spec: - hostname: "*" - prefix: /backend/get_only/ - method: GET - service: quote -``` - -## Using `method_regex` - -When `method_regex` is set to `true`, the value of the `method` annotation will be interpreted as a regular expression. diff --git a/content/en/docs/3.4/topics/using/prefix-regex.md b/content/en/docs/3.4/topics/using/prefix-regex.md deleted file mode 100644 index 04a6e4b8..00000000 --- a/content/en/docs/3.4/topics/using/prefix-regex.md +++ /dev/null @@ -1,25 +0,0 @@ -# Prefix regex - -## Using `prefix` and `prefix_regex` - -When the `prefix_regex` attribute is set to `true`, $productName$ configures a [regex route](https://www.envoyproxy.io/docs/envoy/v1.5.0/api-v1/route_config/route#route) instead of a prefix route in Envoy. **This means the entire path must match the regex specified, not only the prefix.** - -## Example with a version in the URL - -If the version is a path parameter and the resources are served by different services, then - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: qotm -spec: - prefix: "/(v1|v2)/qotm/.*" - prefix_regex: true - service: qotm -``` - -will map requests to both `/v1` and `/v2` to the `qotm` service. - -Note that enclosing regular expressions in quotes can be important to prevent backslashes from being doubled. diff --git a/content/en/docs/3.4/topics/using/query-parameters.md b/content/en/docs/3.4/topics/using/query-parameters.md deleted file mode 100644 index 0bd5eb13..00000000 --- a/content/en/docs/3.4/topics/using/query-parameters.md +++ /dev/null @@ -1,70 +0,0 @@ -# Query parameter-based routing - -$productName$ can route to target services based on HTTP query parameters with the `query_parameters` and `regex_query_parameters` specifications. Multiple mappings with different annotations can be applied to construct more complex routing rules. - -## The `query_parameters` annotation - -The `query_parameters` attribute is a dictionary of `query_parameter`: `value` pairs. $productName$ will only allow requests that match the specified `query_parameter`: `value` pairs to reach the target service. - -You can also set the `value` of a query parameter to `true` to test for the existence of a query parameter. - -### A basic example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - query_parameters: - quote-mode: backend - random-query-parameter: datawire -``` - -This will allow requests to /backend/ to succeed only if the `quote-mode` query parameter has the value `backend` and the `random-query-parameter` has the value `datawire`. - -### A conditional example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-mode -spec: - prefix: /backend/ - service: quote-mode - query_parameters: - quote-mode: true - ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-regular -spec: - prefix: /backend/ - service: quote-regular -``` - -This will send requests that contain the `quote-mode` query parameter to the `quote-mode` target, while routing all other requests to the `quote-regular` target. - -## `regex_query_parameters` - -The following mapping will route requests with the `quote-mode` header that contain values that match the regex. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - regex_query_parameters: - quote-mode: "^[a-z].*" - prefix: /backend/ - service: quote -``` diff --git a/content/en/docs/3.4/topics/using/rate-limits/index.md b/content/en/docs/3.4/topics/using/rate-limits/index.md deleted file mode 100644 index b65f8c5d..00000000 --- a/content/en/docs/3.4/topics/using/rate-limits/index.md +++ /dev/null @@ -1,199 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Basic rate limiting - -Rate limiting in $productName$ is composed of two parts: - -* The [`RateLimitService`](../../running/services/rate-limit-service) resource tells $productName$ what external service - to use for rate limiting. - - If $productName$ cannot contact the rate limit service, it will allow the request to be processed as if there were no rate limit service configuration. - -* _Labels_ that get attached to requests. A label is basic metadata that - is used by the `RateLimitService` to decide which limits to apply to - the request. - - - These labels require Mapping resources with apiVersion - getambassador.io/v2 or newer — if you're updating an old installation, check the - apiVersion! - - -Labels are grouped according to _domain_ and _group_: - -```yaml -labels: - "domain1": - - "group1": - - "my_label_specifier_1" - - "my_label_specifier_2" - - "group2": - - "my_label_specifier_3" - - "my_label_specifier_4" - "domain2": - - ... -``` - -The names of domains and groups are not interpreted by $productName$ in any way: -they are solely there to help configuration authors remember the different groupings. -Note that **at present, rate limiting supports just one domain**: the name of the -domain must be configured in the [`RateLimitService`](../../running/services/rate-limit-service). - - - -## Attaching labels to requests - -There are two ways of setting labels on a request: - -1. You can set labels on an individual [`Mapping`](../mappings). These labels - will only apply to requests that use that `Mapping`. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Mapping - metadata: - name: foo-mapping - spec: - hostname: "*" - prefix: /foo/ - service: foo - labels: - "domain1": - - "group1": - - "my_label_specifier_1" - - "my_label_specifier_2" - - "group2": - - "my_label_specifier_3" - - "my_label_specifier_4" - "domain2": - - ... - ``` - -2. You can set global labels in the [`ambassador` `Module`](../../running/ambassador). - These labels will apply to _every_ request that goes through $productName$. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - spec: - config: - default_labels: - "domain1": - defaults: - - "my_label_specifier_a" - - "my_label_specifier_b" - "domain2": - defaults: - - "my_label_specifier_c" - - "my_label_specifier_d" - ``` - - If a `Mapping` and the defaults both give label groups for the same domain, the - default labels are prepended to each label group from the `Mapping`. If the `Mapping` - does not give any labels for that domain, the global labels are placed into a new - label group named "default" for that domain. - -Each label group is a list of labels; each label is a key/value pair. Since the label -group is a list rather than a map: -- it is possible to have multiple labels with the same key, and -- the order of labels matters. - -> Note: The terminology used by the Envoy documentation differs from -> the terminology used by $productName$: -> -> | $productName$ | Envoy | -> |-----------------|-------------------| -> | label group | descriptor | -> | label | descriptor entry | -> | label specifier | rate limit action | - -The `Mapping`s' listing of the groups of specifiers have names for the -groups; the group names are useful for humans dealing with the YAML, -but are ignored by $productName$, all $productName$ cares about are the -*contents* of the groupings of label specifiers. - -There are 5 types of label specifiers in $productName$: - - - -1. `source_cluster` - - ```yaml - source_cluster: - key: source_cluster - ``` - - Sets the label `source_cluster=«Envoy source cluster name»"`. The Envoy - source cluster name is the name of the Envoy cluster that the request came - in on. - - The syntax of this label currently _requires_ `source_cluster: {}`. - -2. `destination_cluster` - - ```yaml - destination_cluster: - key: destination_cluster - ``` - - Sets the label `destination_cluster=«Envoy destination cluster name»"`. The Envoy - destination cluster name is the name of the Envoy cluster to which the `Mapping` - routes the request. You can get the name for a cluster from the - [diagnostics service](../../running/diagnostics). - - The syntax of this label currently _requires_ `destination_cluster: {}`. - -3. `remote_address` - - ```yaml - remote_address: - key: remote_address - ``` - - Sets the label `remote_address=«IP address of the client»"`. The IP address of - the client will be taken from the `X-Forwarded-For` header, to correctly manage - situations with L7 proxies. This requires that $productName$ be correctly - [configured to communicate](../../../howtos/configure-communications). - - The syntax of this label currently _requires_ `remote_address: {}`. - -4. `request_headers` - - ```yaml - request_headers: - header_name: "header-name" - key: mykey - ``` - - If a header named `header-name` is present, set the label `mykey=«value of the header»`. - If no header named `header-name` is present, **the entire label group is dropped**. - -5. `generic_key` - - ```yaml - generic_key: - key: mykey - value: myvalue - ``` - - Sets the label `«mykey»=«myval»`. Note that supplying a `key` is supported only - with the Envoy V3 API. - -## Rate limiting requests based on their labels - -This is determined by your `RateLimitService` implementation. See the -[Basic Rate Limiting tutorial](../../../howtos/rate-limiting-tutorial) for an -example `RateLimitService` implementation for $productName$. - -If you'd rather not write your own `RateLimitService` implementation, -$AESproductName$ provides a `RateLimitService` implementation that is -configured by a `RateLimit` custom resource. See the -[$AESproductName$ RateLimit Reference](/docs/edge-stack/latest/topics/using/rate-limits/rate-limits/) -for more information. diff --git a/content/en/docs/3.4/topics/using/redirects.md b/content/en/docs/3.4/topics/using/redirects.md deleted file mode 100644 index f55c467d..00000000 --- a/content/en/docs/3.4/topics/using/redirects.md +++ /dev/null @@ -1,142 +0,0 @@ -# Redirects - -$productName$ can perform 3xx redirects on `Mapping`s to a different host, with various options to redirect the path and to return a different 3xx response code instead of the default 301. - -## Schema - -| Name | Type | Description | -| --- | --- | --- | -| `spec.host_redirect` | Boolean | This is *required* to be set to `true` to use any type of redirect, otherwise the request will be proxied instead of redirected. | -| `spec.path_redirect` | String | Optional, changes the path for the redirect. | -| `spec.prefix_redirect` | String | Optional, matches the `prefix` value and replaces it with the `prefix_redirect` value. | -| `spec.regex_redirect` | String | Optional, uses regex to match and replace the `prefix` value. | -| `spec.redirect_response_code` | Integer | Optional, changes the response code from the default 301, valid values are 301, 302, 303, 307, and 308. | -| `spec.config. x_forwarded_proto_redirect` | Boolean | Redirect only the originating HTTP requests to HTTPS, allowing the originating HTTPS requests to pass through. | -| `spec.config. use_remote_address` | Boolean | Required to be set to `false` to use the `x_forwarded_proto_redirect` feature. | - -## Examples - -### Basic redirect - -To effect any type of HTTP `Redirect`, the `Mapping` *must* set `host_redirect` to `true`, with `service` set to the host to which the client should be redirected: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - prefix: /redirect/ - service: httpbin.org - host_redirect: true - hostname: '*' -``` - -Using this `Mapping`, a request to `http://$AMBASSADOR_URL/redirect/` will be redirected to `http://httpbin.org/redirect/`. - -> As always with $productName$, the trailing `/` on any URL with a -`Mapping` is required! - -### Path redirect - -The `Mapping` may optionally also set additional properties to customize the behavior of the HTTP redirect response. - -To also change the path portion of the URL during the redirect, set `path_redirect`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - hostname: '*' - prefix: /redirect/ - service: httpbin.org - host_redirect: true - path_redirect: /ip -``` - -Here, a request to `http://$AMBASSADOR_URL/redirect/` will be redirected to `http://httpbin.org/ip/`. - -### Prefix redirect - -To change only a prefix of the path portion of the URL, set `prefix_redirect`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - hostname: '*' - prefix: /redirect/path/ - service: httpbin.org - host_redirect: true - prefix_redirect: /ip -``` - -Now, a request to `http://$AMBASSADOR_URL/redirect/path/` will be redirected to `http://httpbin.org/ip/`. The prefix `/redirect/path/` was matched and replaced with `/ip/`. - -### Regex redirect - -`regex_redirect` matches a regular expression to replace instead of a fixed prefix. -[See more information about using regex with $productName$](../rewrites/#regex_rewrite). - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - prefix: /foo/ - service: httpbin.org - host_redirect: true - regex_redirect: - pattern: '/foo/([0-9]*)/list' - substitution: '/bar/\1' -``` -A request to `http://$AMBASSADOR_URL/foo/12345/list` will be redirected to -`http://$AMBASSADOR_URL/bar/12345`. - -### Redirect response code - -To change the HTTP response code return by $productName$, set `redirect_reponse_code`. If this is not set, 301 is returned by default. Valid values include 301, 302, 303, 307, and 308. This -can be used with any type of redirect. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - prefix: /ip/ - service: httpbin.org - host_redirect: true - redirect_response_code: 302 -``` - -A request to `http://$AMBASSADOR_URL/ip/` will result in an HTTP 302 redirect to `http://httpbin.org/ip`. - -### X-FORWARDED-PROTO redirect - -In cases when TLS is being terminated at an external layer 7 load balancer, then you would want to redirect only the originating HTTP requests to HTTPS, and let the originating HTTPS requests pass through. - -This distinction between an originating HTTP request and an originating HTTPS request is done based on the `X-FORWARDED-PROTO` header that the external layer 7 load balancer adds to every request it forwards after TLS termination. - -To enable this `X-FORWARDED-PROTO` based HTTP to HTTPS redirection, add a `x_forwarded_proto_redirect: true` field to `ambassador Module`'s configuration. Note that when this feature is enabled `use_remote_address` MUST be set to false. - -An example configuration is as follows - - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - x_forwarded_proto_redirect: true - use_remote_address: false -``` - -Note: Setting `x_forwarded_proto_redirect: true` will impact all your $productName$ mappings. Every HTTP request to $productName$ will only be allowed to pass if it has an `X-FORWARDED-PROTO: https` header. diff --git a/content/en/docs/3.4/topics/using/retries.md b/content/en/docs/3.4/topics/using/retries.md deleted file mode 100644 index d018ab59..00000000 --- a/content/en/docs/3.4/topics/using/retries.md +++ /dev/null @@ -1,84 +0,0 @@ -# Automatic retries - -Sometimes requests fail. When these requests fail for transient issues, $productName$ can automatically retry the request. - -Retry policy can be set for all $productName$ mappings in the [`ambassador Module`](../../running/ambassador), or set per [`Mapping`](../mappings). Generally speaking, you should set `retry_policy` on a per mapping basis. Global retries can easily result in unexpected cascade failures. - -> Note that when setting `retry_policy`, adjusting `max_retries` in the [circuit breaker](https://www.getambassador.io/docs/edge-stack/pre-release/topics/using/circuit-breakers/) configuration should also be considered in order to account for all desired retries. - -## Configuring retries - -The `retry_policy` attribute configures automatic retries. The following fields are supported: - -```yaml -retry_policy: - retry_on: - num_retries: - per_try_timeout: -``` - -### `retry_on` - -(Required) Specifies the condition under which $productName$ retries a failed request. - -| Value | Description | -| --- | --- | -|`5xx`| Retries if the upstream service responds with any 5xx code or does not respond at all -|`gateway-error`| Similar to a `5xx` but only applies to a 502, 503, or 504 response -|`connect-failure`| Retries on a connection failure to the upstream service (included in `5xx`) -|`retriable-4xx`| Retries on a retriable 4xx response (currently only 409) -|`refused-stream`| Retires if the upstream service sends a REFUSED_STREAM error (included in `5xx`) -|`retriable-status-codes`| Retries based on status codes set in the `x-envoy-retriable-status-codes` header. If that header isn't set, $productName$ will not retry the request. - - For more details on each of these values, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/v1.9.0/configuration/http_filters/router_filter#x-envoy-retry-on). - -### `num_retries` - -(Default: 1) Specifies the number of retries to execute for a failed request. - -### `per_try_timeout` - -(Default: global request timeout) Specify the timeout for each retry. Must be in seconds or nanoseconds, e.g., `1s`, `1500ns`. - -## Examples - -A per mapping retry policy: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - retry_policy: - retry_on: "5xx" - num_retries: 10 -``` - -A global retry policy (not recommended): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - retry_policy: - retry_on: "retriable-4xx" - num_retries: 4 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - hostname: '*' -``` diff --git a/content/en/docs/3.4/topics/using/rewrites.md b/content/en/docs/3.4/topics/using/rewrites.md deleted file mode 100644 index 44d0a961..00000000 --- a/content/en/docs/3.4/topics/using/rewrites.md +++ /dev/null @@ -1,100 +0,0 @@ -# Rewrites - -Once $productName$ uses a prefix to identify the service to which a given request should be passed, it can rewrite the URL before handing it off to the service. - -There are two approaches for rewriting: `rewrite` for simpler scenarios and `regex_rewrite` for more advanced rewriting. - -**Please note that** only one of these two can be configured for a mapping **at the same time**. As a result $productName$ ignores `rewrite` when `regex_rewrite` is provided. - -## `rewrite` - -By default, the `prefix` is rewritten to `/`, so e.g., if we map `/backend-api/` to the service `service1`, then - - -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/content/en/docs/3.4/topics/using/shadowing.md b/content/en/docs/3.4/topics/using/shadowing.md deleted file mode 100644 index dd95fbba..00000000 --- a/content/en/docs/3.4/topics/using/shadowing.md +++ /dev/null @@ -1,78 +0,0 @@ -# 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. - -![Shadowing](../../images/shadowing.png) - -## 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/content/en/docs/3.4/topics/using/tcpmappings.md b/content/en/docs/3.4/topics/using/tcpmappings.md deleted file mode 100644 index f246e799..00000000 --- a/content/en/docs/3.4/topics/using/tcpmappings.md +++ /dev/null @@ -1,300 +0,0 @@ -# `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/content/en/docs/3.4/topics/using/timeouts.md b/content/en/docs/3.4/topics/using/timeouts.md deleted file mode 100644 index ae004102..00000000 --- a/content/en/docs/3.4/topics/using/timeouts.md +++ /dev/null @@ -1,66 +0,0 @@ -# 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/content/en/docs/3.4/tutorials/dev-portal-tutorial.md b/content/en/docs/3.4/tutorials/dev-portal-tutorial.md deleted file mode 100644 index d3c0d0a8..00000000 --- a/content/en/docs/3.4/tutorials/dev-portal-tutorial.md +++ /dev/null @@ -1,29 +0,0 @@ -# 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:///docs/` to see the -publicly visible Developer Portal. Make sure you include the trailing `/`. -This is a fully customizable portal that you can share with third parties who -need information about your APIs. diff --git a/content/en/docs/3.4/tutorials/getting-started.md b/content/en/docs/3.4/tutorials/getting-started.md deleted file mode 100644 index 1fb11cec..00000000 --- a/content/en/docs/3.4/tutorials/getting-started.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: "Getting Started with $productName$" -description: "Learn how to install $productName$ with either Helm or kubectl to get started routing traffic from the edge of your Kubernetes cluster to your services..." ---- - -import Alert from '@material-ui/lab/Alert'; -import GettingStartedEmissary21Tabs from './gs-tabs' - -# $productName$ quick start - -
-

Contents

- -- [1. Installation](#1-installation) - - [Connecting your installation to Ambassador Cloud](#connecting-your-installation-to-ambassador-cloud) -- [2. Routing traffic from the edge](#2-routing-traffic-from-the-edge) -- [What's next?](#img-classos-logo-srcimageslogopng-whats-next) - -
- -## 1. Installation - -We'll start by installing $productName$ into your cluster. - -**We recommend using Helm** but there are other options below to choose from. - - - -### Connecting your installation to Ambassador Cloud - -Now is a great moment to connect your new installation to Ambassador Cloud in order to fully leverage the power of $productName$ and the Developer Control Plane (DCP). - -1. Log in to [Ambassador Cloud](https://app.getambassador.io/cloud/services/) with GitHub, GitLab or Google and select your team account. - -2. At the top, click **Add Services** then click **Connection Instructions** in the "Connect your installation" section. - -3. Follow the prompts to name the cluster and click **Generate a Cloud Token**. - -4. Follow the prompts to install the cloud token into your cluster. - -5. When the token installation completes, your services will be listed in the DCP. - -Success! At this point, you have installed $productName$. Now let's get some traffic flowing to your services. - -## 2. Routing traffic from the edge - -$productName$ uses Kubernetes Custom Resource Definitions (CRDs) to declaratively define its desired state. The workflow you are going to build uses a simple demo app, a **`Listener` CRD**, and a **`Mapping` CRD**. The `Listener` CRD tells $productName$ what port to listen on, and the `Mapping` CRD tells $productName$ how to route incoming requests by host and URL path from the edge of your cluster to Kubernetes services. - -1. Start by creating a `Listener` resource for HTTP on port 8080: - - ``` - kubectl apply -f - < - This 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.
-
- Learn more about Listener.
- Learn more about Host. - - -2. Apply the YAML for the "Quote" service. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/quickstart/qotm.yaml - ``` - - The Service and Deployment are created in your default namespace. You can use 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](#connecting-your-installation-to-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` - - ![](../images/mapping-editor.png) - - 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 - <Victory! You have created your first $productName$ 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/content/en/docs/3.4/tutorials/gs-tabs.js b/content/en/docs/3.4/tutorials/gs-tabs.js deleted file mode 100644 index 4516d731..00000000 --- a/content/en/docs/3.4/tutorials/gs-tabs.js +++ /dev/null @@ -1,132 +0,0 @@ -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 HelmIcon from '../../../../../src/assets/icons/helm.inline.svg'; -import KubernetesIcon from '../../../../../src/assets/icons/kubernetes.inline.svg'; -import CodeBlock from '../../../../../src/components/CodeBlock'; - -function TabPanel(props) { - const { children, value, index, ...other } = props; - - return ( - - ); -} - -TabPanel.propTypes = { - children: PropTypes.node, - index: PropTypes.any.isRequired, - value: PropTypes.any.isRequired, -}; - -function a11yProps(index) { - return { - id: `simple-tab-${index}`, - 'aria-controls': `simple-tabpanel-${index}`, - }; -} - -const useStyles = makeStyles((theme) => ({ - root: { - flexGrow: 1, - backgroundColor: 'transparent', - }, -})); - -export default function GettingStartedEmissary21Tabs(props) { - const version = props.version; - const classes = useStyles(); - const [value, setValue] = React.useState(0); - - const handleChange = (event, newValue) => { - setValue(newValue); - }; - - return ( -
- - - } - label="Helm 3" - {...a11yProps(0)} - style={{ minWidth: '10%', textTransform: 'none' }} - /> - } - label="Kubernetes YAML" - {...a11yProps(1)} - style={{ minWidth: '10%', textTransform: 'none' }} - /> - - - - {/*Helm 3 install instructions*/} - - - {'# Add the Repo:' + - '\n' + - 'helm repo add datawire https://app.getambassador.io' + - '\n' + - 'helm repo update' + - '\n \n' + - '# Create Namespace and Install:' + - '\n' + - 'kubectl create namespace emissary && \\' + - '\n' + - `kubectl apply -f https://app.getambassador.io/yaml/emissary/${version}/emissary-crds.yaml` + - '\n' + - 'kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system' + - '\n' + - 'helm install emissary-ingress --namespace emissary datawire/emissary-ingress && \\' + - '\n' + - 'kubectl -n emissary wait --for condition=available --timeout=90s deploy -lapp.kubernetes.io/instance=emissary-ingress' + - '\n'} - - - - - {/*YAML install instructions*/} - - - {'kubectl create namespace emissary && \\' + - '\n' + - `kubectl apply -f https://app.getambassador.io/yaml/emissary/${version}/emissary-crds.yaml && \\` + - '\n' + - 'kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system' + - '\n' + - `kubectl apply -f https://app.getambassador.io/yaml/emissary/${version}/emissary-emissaryns.yaml && \\` + - '\n' + - 'kubectl -n emissary wait --for condition=available --timeout=90s deploy -lproduct=aes' + - '\n'} - - -
- ); -} diff --git a/content/en/docs/3.4/tutorials/gs-tabs2.js b/content/en/docs/3.4/tutorials/gs-tabs2.js deleted file mode 100644 index bfd95047..00000000 --- a/content/en/docs/3.4/tutorials/gs-tabs2.js +++ /dev/null @@ -1,174 +0,0 @@ -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'; - -function TabPanel(props) { - const { children, value, index, ...other } = props; - - return ( - - ); -} - -TabPanel.propTypes = { - children: PropTypes.node, - index: PropTypes.any.isRequired, - value: PropTypes.any.isRequired, -}; - -function a11yProps(index) { - return { - id: `simple-tab-${index}`, - 'aria-controls': `simple-tabpanel-${index}`, - }; -} - -const useStyles = makeStyles((theme) => ({ - root: { - flexGrow: 1, - backgroundColor: 'transparent', - }, -})); - -export default function SimpleTabs() { - const classes = useStyles(); - const [value, setValue] = React.useState(0); - - const handleChange = (event, newValue) => { - setValue(newValue); - }; - - return ( -
- - - - - - - - - - {/*Helm 3 token install instructions*/} - Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Helm. The slideout contains instructions with a - unique cloud-connect-token that is used to connect your - cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'helm upgrade ambassador --namespace ambassador datawire/ambassador \\' + - '\n' + - ' --set agent.cloudConnectToken=$TOKEN && \\' + - '\n' + - 'kubectl -n ambassador wait --for condition=available --timeout=90s deploy -lproduct=aes'} - - - - - {/*Helm 2 token install instructions*/} - Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Helm. The slideout contains instructions with a - unique cloud-connect-token that is used to connect your - cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'helm upgrade --namespace ambassador ambassador datawire/ambassador \\' + - '\n' + - ' --set crds.create=false --set agent.cloudConnectToken=$TOKEN && \\' + - '\n' + - 'kubectl -n ambassador wait --for condition=available --timeout=90s deploy -lproduct=aes'} - - - - - {/*YAML token install instructions*/} - Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Kubernetes YAML. The slideout contains instructions - with a unique cloud-connect-token that is used to connect - your cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'kubectl create configmap -n ambassador ambassador-agent-cloud-token \\' + - '\n' + - ' --from-literal=CLOUD_CONNECT_TOKEN=$TOKEN'} - - - - - {/*edgectl token install instructions*/} - Connecting $productName$ that was installed via edgectl is - identical to the Kubernetes YAML procedure. -
- Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Kubernetes YAML. The slideout contains instructions - with a unique cloud-connect-token that is used to connect - your cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'kubectl create configmap -n ambassador ambassador-agent-cloud-token \\' + - '\n' + - ' --from-literal=CLOUD_CONNECT_TOKEN=$TOKEN'} - - -
- ); -} diff --git a/content/en/docs/3.4/tutorials/quickstart-demo.md b/content/en/docs/3.4/tutorials/quickstart-demo.md deleted file mode 100644 index 70cbce8b..00000000 --- a/content/en/docs/3.4/tutorials/quickstart-demo.md +++ /dev/null @@ -1,176 +0,0 @@ -# $productName$ Tutorial - -In this article, you will explore some of the key features of $productName$ by walking through an example workflow and exploring the -Edge Policy Console. - -## Prerequisites - -You must have [$productName$ installed](../getting-started/) in your -Kubernetes cluster. - -## Routing Traffic from the Edge - -Like any other Kubernetes object, Custom Resource Definitions (CRDs) are used to -declaratively define $productName$’s desired state. The workflow you are going to -build uses a sample deployment and the `Mapping` CRD, which is the core resource -that you will use with $productName$ to manage your edge. It enables you to route -requests by host and URL path from the edge of your cluster to Kubernetes services. - -1. Copy the configuration below and save it to a file named `quote.yaml` so that -you can deploy these resources to your cluster. This basic configuration creates -the `quote` deployment and a service to expose that deployment on port 80. - - ```yaml - --- - apiVersion: apps/v1 - kind: Deployment - metadata: - name: quote - namespace: ambassador - spec: - replicas: 1 - selector: - matchLabels: - app: quote - strategy: - type: RollingUpdate - template: - metadata: - labels: - app: quote - spec: - containers: - - name: backend - image: docker.io/datawire/quote:$quoteVersion$ - ports: - - name: http - containerPort: 8080 - --- - apiVersion: v1 - kind: Service - metadata: - name: quote - namespace: ambassador - spec: - ports: - - name: http - port: 80 - targetPort: 8080 - selector: - app: quote - ``` - -1. Apply the configuration to the cluster with the command `kubectl apply -f quote.yaml`. - -1. Copy the configuration below and save it to a file called `quote-backend.yaml` -so that you can create a `Mapping` on your cluster. This `Mapping` tells $productName$ to route all traffic inbound to the `/backend/` path, on any host that can be used to reach $productName$, to the `quote` service. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Mapping - metadata: - name: quote-backend - namespace: ambassador - spec: - hostname: "*" - prefix: /backend/ - service: quote - ``` - -1. Apply the configuration to the cluster with the command -`kubectl apply -f quote-backend.yaml` - -1. Store the $productName$ `LoadBalancer` address to a local environment variable. -You will use this variable to test accessing your pod. - - ``` - export AMBASSADOR_LB_ENDPOINT=$(kubectl -n ambassador get svc ambassador -o "go-template={{range .status.loadBalancer.ingress}}{{or .ip .hostname}}{{end}}") - ``` - -1. Test the configuration by accessing the service through the $productName$ load -balancer. - - ``` - $ curl -Lk "https://$AMBASSADOR_LB_ENDPOINT/backend/" - { - "server": "idle-cranberry-8tbb6iks", - "quote": "Non-locality is the driver of truth. By summoning, we vibrate.", - "time": "2019-12-11T20:10:16.525471212Z" - } - ``` - -Success, you have created your first $productName$ `Mapping`, routing a -request from your cluster's edge to a service! - -Since the `Mapping` you just created controls how requests are routed, -changing the `Mapping` will immediately change the routing. To see this -in action, use `kubectl` to edit the `Mapping`: - -1. Run `kubectl edit Mapping quote-backend`. - -1. Change `prefix: /backend/` to `prefix: /quoteme/`. - -1. Save the file and let `kubectl` update your `Mapping`. - -1. Run `kubectl get Mappings --namespace ambassador`. You will see the -`quote-backend` `Mapping` has the updated prefix listed. Try to access the -endpoint again via `curl` with the updated prefix. - - ``` - $ kubectl get Mappings --namespace ambassador - NAME PREFIX SERVICE STATE REASON - quote-backend /quoteme/ quote - - $ curl -Lk "https://${AMBASSADOR_LB_ENDPOINT}/quoteme/" - { - "server": "snippy-apple-ci10n7qe", - "quote": "A principal idea is omnipresent, much like candy.", - "time": "2020-11-18T17:15:42.095153306Z" - } - ``` - -1. Change the prefix back to `/backend/` so that you can later use the `Mapping` -with other tutorials. - -## 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. In the Edge Policy Console, navigate to the **APIs** tab. You'll see the -OpenAPI documentation there for the "Quote Service API." Click **GET** to -expand out the documentation. - -1. Navigate to `https:///docs/` to see the -publicly visible Developer Portal. Make sure you include the trailing `/`. -This is a fully customizable portal that you can share with third parties who -need information about your APIs. - -## Next Steps - -Further explore some of the concepts you learned about in this article: -* [`Mapping` resource](../../topics/using/intro-mappings/): routes traffic from -the edge of your cluster to a Kubernetes service -* [`Host` resource](../../topics/running/host-crd/): sets the hostname by which -$productName$ will be accessed and secured with TLS certificates -* [Developer Portal](../../tutorials/dev-portal-tutorial/): -publishes an API catalog and OpenAPI documentation - -$productName$ has a comprehensive range of [features](/features/) to -support the requirements of any edge microservice. - -Learn more about [how developers use $productName$](../../topics/using/) to manage -edge policies. - -Learn more about [how site reliability engineers and operators run $productName$](../../topics/running/) -in production environments. - -To learn how $productName$ works, use cases, best practices, and more, check out -the [Quick Start](../getting-started) or read the [$productName$ Story](../../about/why-ambassador). - -For a custom configuration, you can install $productName$ -[manually](../../topics/install/yaml-install). diff --git a/content/en/docs/3.4/versions.yml b/content/en/docs/3.4/versions.yml deleted file mode 100644 index 45f6b55f..00000000 --- a/content/en/docs/3.4/versions.yml +++ /dev/null @@ -1,35 +0,0 @@ -# branch info -branch: release/v3.4 - -# self -version: 3.4.1 -productName: "Emissary-ingress" -productNamePlural: "Emissary-ingresses" -productNamespace: emissary -productDeploymentName: emissary-ingress -productHelmName: emissary-ingress - -# OSS (self) -ossVersion: 3.4.1 -ossDocsVersion: "3.4" -ossChartVersion: 8.4.1 -OSSproductName: "Emissary-ingress" -OSSproductNamePlural: "Emissary-ingresses" - -# AES (not self) -aesVersion: 3.4.1 -aesDocsVersion: "3.4" -aesChartVersion: 8.4.1 -AESproductName: "Ambassador Edge Stack" -AESproductNamePlural: "Ambassador Edge Stacks" - -# other products -qotmVersion: 1.7 -quoteVersion: 0.5.0 - -# Most recent version from previous major versions -# This is mostly to ensure that the migration matrix stays up-to-date -versionTwoX: 2.5.1 -chartVersionTwoX: 7.6.1 -versionOneX: 1.14.4 -chartVersionOneX: 6.9.5 diff --git a/content/en/docs/3.5/_index.md b/content/en/docs/3.5/_index.md deleted file mode 100644 index 09c55e9b..00000000 --- a/content/en/docs/3.5/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: v3.5 docs -cascade: - version: v3.5 - versName: &name v3.5 - git_version_tag: v3.5.0 - exclude_search: true -linkTitle: *name -simple_list: true -weight: -350 # Weight for doc version vX.Y should be -XY0 ---- - -These docs cover everything from setting up and running Emissary-ingress to its operation and usage. diff --git a/content/en/docs/3.5/about/aes-emissary-eol.md b/content/en/docs/3.5/about/aes-emissary-eol.md deleted file mode 100644 index 6afc3142..00000000 --- a/content/en/docs/3.5/about/aes-emissary-eol.md +++ /dev/null @@ -1,56 +0,0 @@ -# $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/content/en/docs/3.5/about/alternatives.md b/content/en/docs/3.5/about/alternatives.md deleted file mode 100644 index bafec087..00000000 --- a/content/en/docs/3.5/about/alternatives.md +++ /dev/null @@ -1,19 +0,0 @@ -# $productName$ vs. other software - -Alternatives to $productName$ fall into three basic categories: - -* Hosted API gateways, such as the [Amazon API gateway](https://aws.amazon.com/api-gateway/). -* Traditional API gateways, such as [Kong](https://konghq.org/). -* L7 proxies, such as [Traefik](https://traefik.io/), [NGINX](http://nginx.org/), [HAProxy](http://www.haproxy.org/), or [Envoy](https://www.envoyproxy.io), or Ingress controllers built on these proxies. - -Both hosted API gateways and traditional API gateways are: - -* Not self-service. The management interfaces on traditional API gateways are not designed for developer self-service, and provide limited safety and usability for developers. -* Not Kubernetes-native. They're typically configured using REST APIs, making it challenging to adopt cloud-native patterns such as GitOps and declarative configuration. -* [Designed for API management, rather than designed for microservices](../../topics/concepts/microservices-api-gateways). - -A Layer 7 proxy can be used as an API gateway, but typically requires additional bespoke development to support microservices use cases. In fact, many API gateways package the additional features needed for an API gateway on top of an L7 proxy. $productName$ uses Envoy, while Kong uses NGINX. If you're interested in deploying Envoy directly, we've written an [introductory tutorial](https://www.datawire.io/guide/traffic/getting-started-lyft-envoy-microservices-resilience/). - -## Istio - -[Istio](https://istio.io) is an open-source service mesh, built on Envoy. A service mesh is designed to manage East/West traffic (traffic between servers and your data center), while an API gateway manages North/South traffic (in and out of your data center). Documentation on how to deploy $productName$ with Istio is [here](../../howtos/istio). In general, we've found that North/South traffic is quite different from East/West traffic (i.e., you don't control the client in the North/South use case). diff --git a/content/en/docs/3.5/about/changes-2.x.md b/content/en/docs/3.5/about/changes-2.x.md deleted file mode 100644 index 389cc89b..00000000 --- a/content/en/docs/3.5/about/changes-2.x.md +++ /dev/null @@ -1,238 +0,0 @@ -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. - - - $productName$ 2.X supports only API versions getambassador.io/v2 - and getambassador.io/v3alpha1. If you are using any resources with - older API versions, you will need to upgrade them. - - -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 [structural CRDs](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. - - - Learn more about Listener.
- Learn more about Host. - - -### 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. - - - Learn more about Host. - - -### `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. - - - Learn more about Host.
- Learn more about Mapping. - - -### 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. - - - Learn more about Host. - - -### `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). - - - Learn more about Host.
- Learn more about TLSContext. - - -### `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). - - - Learn more about Mapping. - - -### `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. - - - Learn more about Mapping. - - -## 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). In $productName$ -2.X, you may switch back to Envoy V2 by setting the `AMBASSADOR_ENVOY_API_VERSION` -environment variable to "V2"; in $productName$ 3.X, support for the Envoy V2 API (and -the `AMBASSADOR_ENVOY_API_VERSION` environment variable) will be removed. - -### 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. - - - Learn more about Listener. - - -### `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/content/en/docs/3.5/about/changes-3.y.md b/content/en/docs/3.5/about/changes-3.y.md deleted file mode 100644 index 91105d28..00000000 --- a/content/en/docs/3.5/about/changes-3.y.md +++ /dev/null @@ -1,52 +0,0 @@ -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 AuthServices 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, -``` - - - Learn more about Envoy Proxy changes. - - -## 2. Envoy V2 Protocol Support Removed - -With the upgrade to Envoy **1.22**, the V2 Envoy Transport Protocol is no longer supported. -$productName$ 3.X **only** supports [V3 Envoy API](https://www.envoyproxy.io/docs/envoy/latest/api-v3/api). - - -The environment variable AMBASSADOR_ENVOY_API_VERSION has been removed and will no longer have the affect -of changing the transport protocol. - - - -The setting of 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. - diff --git a/content/en/docs/3.5/about/faq.md b/content/en/docs/3.5/about/faq.md deleted file mode 100644 index 513c75c5..00000000 --- a/content/en/docs/3.5/about/faq.md +++ /dev/null @@ -1,79 +0,0 @@ -# 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. -* 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! The core functionality of the $AESproductName$ is free and has no limits whatsoever. If you wish to use one of our additional, proprietary features such as Single Sign-On, you can get a free community license for up to 5 requests per second by registering your connected $AESproductName$ installation in [Ambassador Cloud](https://app.getambassador.io/cloud/). Please contact [sales](/contact-us/) if you need more than 5 RPS. - -For more details on core unlimited features and premium features, see the [editions page](/editions). - -### 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? - -[//]: # (+FIX+ Check for OSS) - -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$? - -[//]: # (+FIX+ Check for OSS) - -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 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/content/en/docs/3.5/about/features-and-benefits.md b/content/en/docs/3.5/about/features-and-benefits.md deleted file mode 100644 index a25d7752..00000000 --- a/content/en/docs/3.5/about/features-and-benefits.md +++ /dev/null @@ -1,43 +0,0 @@ -# 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 - -[//]: # (+FIX+ Forge is no more) - -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 - -[//]: # (+FIX+ we've come to realize that it's better to scale vertically) - -$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 using a custom authentication service. When configured, the $productName$ will check with your external authentication service prior to routing an incoming request. For more information, see the [authentication guide](../../topics/running/services/auth-service). - -## 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/content/en/docs/3.5/about/known-issues.md b/content/en/docs/3.5/about/known-issues.md deleted file mode 100644 index 6b89c65a..00000000 --- a/content/en/docs/3.5/about/known-issues.md +++ /dev/null @@ -1,9 +0,0 @@ -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. diff --git a/content/en/docs/3.5/about/support.md b/content/en/docs/3.5/about/support.md deleted file mode 100644 index 11927f95..00000000 --- a/content/en/docs/3.5/about/support.md +++ /dev/null @@ -1,27 +0,0 @@ -# Need help? - -If you need help deploying $productName$ at your organization, there are several different options available to you. - -## Support tiers - -### $productName$ community support - -When running $OSSproductName$, or $AESproductName$ with free community licenses, [join our Slack channel](http://a8r.io/slack) to talk with other users in the community and get your questions answered. - -If you can’t find an answer there, [contact us](/contact-us) to learn more about the support options available with $AESproductName$ Enterprise. - -### $AESproductName$ Enterprise - -With $AESproductName$ Enterprise, you have access to deployment and production support. To learn more, [contact sales](/contact-us). - -**Deployment and Update Support**: $AESproductName$ can accelerate your migration to Kubernetes, or your upgrade between versions of $AESproductName$. Deployment support helps you with the $AESproductName$ and Kubernetes migration, before you move to production. - -**Production Support**: We offer two types of production support contracts for users deploying the $AESproductName$ in production. We offer both business hour (8am - 5pm EST, M-F) and 24x7 Sev 1 support for the $AESproductName$. 24x7 Sev 1 support includes custom hotfix support for production outages if necessary. - -## File a Github Issue - -If you see a bug you want to fix, see room for documentation improvements, or have something else you want to change, you can [file an issue on github](https://github.com/datawire/ambassador/issues/new). - -## Pricing - -[Contact us](/contact-us) to learn how we can help, and for detailed pricing information. diff --git a/content/en/docs/3.5/about/why-ambassador.md b/content/en/docs/3.5/about/why-ambassador.md deleted file mode 100644 index 0d343983..00000000 --- a/content/en/docs/3.5/about/why-ambassador.md +++ /dev/null @@ -1,54 +0,0 @@ -# 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 an open-source, Kubernetes-native [microservices API gateway](../../topics/concepts/microservices-api-gateways) built on 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/content/en/docs/3.5/community.md b/content/en/docs/3.5/community.md deleted file mode 100644 index 759e4f0e..00000000 --- a/content/en/docs/3.5/community.md +++ /dev/null @@ -1,12 +0,0 @@ -# Community - -## Contributor's guide -Please review our [contributor's guide](https://github.com/emissary-ingress/emissary/blob/master/DEVELOPING.md) -on GitHub to learn how you can help make Emissary-ingress better. - -## Changelog -Our [changelog](https://github.com/emissary-ingress/emissary/blob/master/CHANGELOG.md) -describes new features, bug fixes, and updates to each version of Emissary-ingress. - -## Meetings -Check out our community [meeting schedule](https://github.com/emissary-ingress/emissary/blob/master/MEETING_SCHEDULE.md) for opportunities to interact with Emissary-ingress developers. diff --git a/content/en/docs/3.5/doc-links.yml b/content/en/docs/3.5/doc-links.yml deleted file mode 100644 index 58b81ad9..00000000 --- a/content/en/docs/3.5/doc-links.yml +++ /dev/null @@ -1,229 +0,0 @@ -- 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: $productName$ 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: 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/basic-auth - - title: Rate limiting - items: - - title: Rate limiting service - link: /topics/running/services/rate-limit-service/ - - title: Basic rate limiting - link: /topics/using/rate-limits/ - - 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: Distrbuted 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: 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: 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: Diagnostics - link: /topics/running/diagnostics -- 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: Licenses - link: licenses diff --git a/content/en/docs/3.5/features-icons/basic-authentication.svg b/content/en/docs/3.5/features-icons/basic-authentication.svg deleted file mode 100644 index 2bd19edf..00000000 --- a/content/en/docs/3.5/features-icons/basic-authentication.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_897228_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.5/features-icons/canary-release.svg b/content/en/docs/3.5/features-icons/canary-release.svg deleted file mode 100644 index f8de57d9..00000000 --- a/content/en/docs/3.5/features-icons/canary-release.svg +++ /dev/null @@ -1,27 +0,0 @@ - - - - Group 25 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.5/features-icons/cors.svg b/content/en/docs/3.5/features-icons/cors.svg deleted file mode 100644 index e559d924..00000000 --- a/content/en/docs/3.5/features-icons/cors.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_111967_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.5/features-icons/datadog.png b/content/en/docs/3.5/features-icons/datadog.png deleted file mode 100644 index eea05f8c..00000000 Binary files a/content/en/docs/3.5/features-icons/datadog.png and /dev/null differ diff --git a/content/en/docs/3.5/features-icons/datadog.svg b/content/en/docs/3.5/features-icons/datadog.svg deleted file mode 100644 index e46e8118..00000000 --- a/content/en/docs/3.5/features-icons/datadog.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Screen Shot 2018-04-05 at 8.22.25 AM - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.5/features-icons/diagnostics.svg b/content/en/docs/3.5/features-icons/diagnostics.svg deleted file mode 100644 index 940e1bc2..00000000 --- a/content/en/docs/3.5/features-icons/diagnostics.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_196445_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.5/features-icons/distributed-tracing.png b/content/en/docs/3.5/features-icons/distributed-tracing.png deleted file mode 100644 index 6b69e28c..00000000 Binary files a/content/en/docs/3.5/features-icons/distributed-tracing.png and /dev/null differ diff --git a/content/en/docs/3.5/features-icons/grpc.png b/content/en/docs/3.5/features-icons/grpc.png deleted file mode 100644 index b2f5a0d9..00000000 Binary files a/content/en/docs/3.5/features-icons/grpc.png and /dev/null differ diff --git a/content/en/docs/3.5/features-icons/prometheus.svg b/content/en/docs/3.5/features-icons/prometheus.svg deleted file mode 100644 index d5252a66..00000000 --- a/content/en/docs/3.5/features-icons/prometheus.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - prometheus_logo_grey - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.5/features-icons/rate-limiting.svg b/content/en/docs/3.5/features-icons/rate-limiting.svg deleted file mode 100644 index f1b6eacb..00000000 --- a/content/en/docs/3.5/features-icons/rate-limiting.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - Group 10 - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.5/features-icons/regex-routing.svg b/content/en/docs/3.5/features-icons/regex-routing.svg deleted file mode 100644 index 113b53b5..00000000 --- a/content/en/docs/3.5/features-icons/regex-routing.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_699774_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.5/features-icons/request-transformers.svg b/content/en/docs/3.5/features-icons/request-transformers.svg deleted file mode 100644 index 0b13e2dc..00000000 --- a/content/en/docs/3.5/features-icons/request-transformers.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_96239_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.5/features-icons/shadowing.svg b/content/en/docs/3.5/features-icons/shadowing.svg deleted file mode 100644 index 9e85eee1..00000000 --- a/content/en/docs/3.5/features-icons/shadowing.svg +++ /dev/null @@ -1,15 +0,0 @@ - - - - shadow - Created with Sketch. - - - - - - - - - - diff --git a/content/en/docs/3.5/features-icons/statsd.png b/content/en/docs/3.5/features-icons/statsd.png deleted file mode 100644 index 28374438..00000000 Binary files a/content/en/docs/3.5/features-icons/statsd.png and /dev/null differ diff --git a/content/en/docs/3.5/features-icons/statsd.svg b/content/en/docs/3.5/features-icons/statsd.svg deleted file mode 100644 index cabc90db..00000000 --- a/content/en/docs/3.5/features-icons/statsd.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - 88eb31f74479e422e4e9abfc6c2b00ee - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.5/features-icons/third-party-auth.svg b/content/en/docs/3.5/features-icons/third-party-auth.svg deleted file mode 100644 index 5359a24a..00000000 --- a/content/en/docs/3.5/features-icons/third-party-auth.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_511233_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.5/features-icons/timeouts.svg b/content/en/docs/3.5/features-icons/timeouts.svg deleted file mode 100644 index 47f63056..00000000 --- a/content/en/docs/3.5/features-icons/timeouts.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_587034_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.5/features-icons/tls-termination.svg b/content/en/docs/3.5/features-icons/tls-termination.svg deleted file mode 100644 index 6a631a96..00000000 --- a/content/en/docs/3.5/features-icons/tls-termination.svg +++ /dev/null @@ -1,17 +0,0 @@ - - - - noun_63544_cc - Created with Sketch. - - - - - - - - - - - - diff --git a/content/en/docs/3.5/features-icons/url-rewrite.svg b/content/en/docs/3.5/features-icons/url-rewrite.svg deleted file mode 100644 index 023e2e05..00000000 --- a/content/en/docs/3.5/features-icons/url-rewrite.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1295942_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.5/features-icons/websockets.svg b/content/en/docs/3.5/features-icons/websockets.svg deleted file mode 100644 index af17b9c0..00000000 --- a/content/en/docs/3.5/features-icons/websockets.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - noun_50814_cc - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.5/howtos/active-health-checking.md b/content/en/docs/3.5/howtos/active-health-checking.md deleted file mode 100644 index fb5decdd..00000000 --- a/content/en/docs/3.5/howtos/active-health-checking.md +++ /dev/null @@ -1,78 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Active Health Checking - -$productName$ provides support for active health checking of upstreams via the `Mapping` resource. Active health checking will configure Envoy to make requests to the upstream at a configurable interval. If the upstream does not respond with an expected status code then the upstream will be marked as unhealthy and Envoy will no longer route requests to that upstream until they respond successfully to the health check. - -This feature can only be used with the [endpoint resolver](../../topics/running/resolvers#the-kubernetes-endpoint-resolver). This is necessary because the endpoint resolver allows Envoy to be aware of each individual pod in a deployment as opposed to the [kubernetes service resolver](../../topics/running/resolvers#the-kubernetes-service-resolver) where Envoy is only aware of the upstream as a single endpoint. When envoy is aware of the multiple pods in a deployment then it will allow the active health checks to mark an individual pod as unhealthy while the remaining pods are able to serve requests. - - -Active health checking configuration wil only function with the endpoint resolver. If configuration for active health checking is provided on a Mapping that does not use the endpoint resolver then the health checking configuration will be ignored. - - -## Active Health Checking Configuration - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: "example-mapping" - namespace: "example-namespace" -spec: - hostname: "*" - prefix: /example/ - service: quote - health_checks: list[object] # optional - - unhealthy_threshold: int # optional (default: 2) - healthy_threshold: int # optional (default: 1) - interval: duration # optional (default: 5s) - timeout: duration # optional (default: 3s) - health_check: object # required - http: - path: string # required - hostname: string # optional - remove_request_headers: list[string] # optional - add_request_headers: list[object] # optional - - example-header-1: - append: bool # optional (default: true) - value: string # required - expected_statuses: list[object] # optional - - max: int (100-599) # required (only when using expected_statuses) - min: int (100-599) # required (only when using expected_statuses) - - - health_check: object # required - grpc: - authority: string # optional - upstream_name: string # required -... -``` - -### `health_checks` configuration - -`health_checks` Configures a list of health checks to be run for the `Mapping` and provides several config options for how the health check requests should be run. - -- `unhealthy_threshold`: The number of unexpected responses for an upstream pod to be marked as unhealthy. Regardless of the configuration of `unhealthy_threshold`, a single `503` response will mark the upstream as unhealthy until it passes the required number of health checks. This field is optional and defaults to `2`. -- `healthy_threshold`: The number of expected responses for an unhealthy upstream pod to be marked as healthy and resume handling traffic. This field is optional and defaults to `1`. -- `interval`: Specifies the interval for how frequently the health check request should be made. It is divided amongst the pods in a deployment. For example, an `interval` of `1s` on a deployment of 5 pods would result in each pod receiving a health check request about every 5 seconds. This field is optional and defaults to `5s` when not configured. -- `timeout`: Configures the timeout for the health check requests to an upstream. If a health check request fails the timeout it will be considred a failed check and count towards the `unhealthy_threshold`. This field is optional and defaults to `3s`. -- `health_check`: This field is required and provides the configuration for how the health check requests should be made. Either `grpc` or `http` may be configured for this field depending on whether an HTTP or gRPC health check is desired. - -### HTTP `health_check` Configuration - -`health_check.http` configures HTTP health checks to the upstream. - -- `path`: This field is required and configures the path on the upstream service that the health checks request should be made to. -- `hostname`: Configures the value of the host header in the health check request. This field is optional and defaults to using the name of the Envoy cluster this health check is associated with. -- `expected_statuses`: Configures a range of response statuses from Min to Max (both inclusive). If the upstream returns any status in this range then it will be considered a passed health check. Thies field is optional and by default only `5xx` responses count as a failed health check and contribute towards the `unhealthy_threshold`. - - `max`: End of the statuses to include. Must be between 100 and 599 (inclusive). - - `min`: Start of the statuses to include. Must be between 100 and 599 (inclusive). -- `remove_request_headers`: Configures a list of HTTP headers that should be removed from each health check request sent to the upstream. -- `request_headers_to_add`: Configures a list of HTTP headers that should be added to each health check request sent to the upstream. - -### gRPC `health_check` Configuration - -`health_check.grpc` configures gRPC health checks to the upstream. Only two fields are configurable for gRPC health checks. - -- `authority`: Configures the value of the :authority header in the gRPC health check request. This field is optional and if left empty the upstream name will be used. -- `upstream_name`: This field is required and configures the UpstreamName name parameter which will be sent to gRPC service in the health check message. diff --git a/content/en/docs/3.5/howtos/basic-auth.md b/content/en/docs/3.5/howtos/basic-auth.md deleted file mode 100644 index 70ce27ce..00000000 --- a/content/en/docs/3.5/howtos/basic-auth.md +++ /dev/null @@ -1,191 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Basic authentication (for $productName$) - -[//]: # (+FIX+ link to "authentication and authorization" concept) - - - This guide applies to $OSSproductName$, use of this guide with $AESproductName$ is not supported. $AESproductName$ does authentication using the Filter resource instead of the AuthService resource as described below. - - -$productName$ can authenticate incoming requests before routing them to a backing -service. In this tutorial, we'll configure $productName$ to use an external third -party authentication service. We're assuming also that you are running the -quote application in your cluster as described in the -[$productName$ tutorial](../../tutorials/quickstart-demo/). - -## Before you get started - -This tutorial assumes you have already followed the $productName$ [Installation](../../topics/install/) guide. If you haven't done that already, you should do so now. - -Once complete, you'll have a Kubernetes cluster running $productName$. Let's walk through adding authentication to this setup. - -## 1. Deploy the authentication service - -$productName$ delegates the actual authentication logic to a third party authentication service. We've written a [simple authentication service](https://github.com/datawire/ambassador-auth-service) that: - -- listens for requests on port 3000; -- expects all URLs to begin with `/extauth/`; -- performs HTTP Basic Auth for all URLs starting with `/backend/get-quote/` (other URLs are always permitted); -- accepts only user `username`, password `password`; and -- makes sure that the `x-qotm-session` header is present, generating a new one if needed. - -$productName$ routes _all_ requests through the authentication service: it relies on the auth service to distinguish between requests that need authentication and those that do not. If $productName$ cannot contact the auth service, it will return a 503 for the request; as such, **it is very important to have the auth service running before configuring $productName$ to use it.** - -Here's the YAML we'll start with: - -```yaml ---- -apiVersion: v1 -kind: Service -metadata: - name: example-auth -spec: - type: ClusterIP - selector: - app: example-auth - ports: - - port: 3000 - name: http-example-auth - targetPort: http-api ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: example-auth -spec: - replicas: 1 - strategy: - type: RollingUpdate - selector: - matchLabels: - app: example-auth - template: - metadata: - labels: - app: example-auth - spec: - containers: - - name: example-auth - image: docker.io/datawire/ambassador-auth-service:2.0.0 - imagePullPolicy: Always - ports: - - name: http-api - containerPort: 3000 - resources: - limits: - cpu: "0.1" - memory: 100Mi -``` - -Note that the cluster does not yet contain any $productName$ AuthService definition. This is intentional: we want the service running before we tell $productName$ about it. - -The YAML above is published at getambassador.io, so if you like, you can just do - -``` -kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/demo/demo-auth.yaml -``` - -to spin everything up. (Of course, you can also use a local file, if you prefer.) - -Wait for the pod to be running before continuing. The output of `kubectl get pods` should look something like - -``` -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -example-auth-6c5855b98d-24clp 1/1 Running 0 4m -``` -Note that the `READY` field says `1/1` which means the pod is up and running. - -## 2. Configure $productName$ authentication - -Once the auth service is running, we need to tell $productName$ about it. The easiest way to do that is point it to the `example-auth` service with the following: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: AuthService -metadata: - name: authentication -spec: - auth_service: "example-auth:3000" - path_prefix: "/extauth" - allowed_request_headers: - - "x-qotm-session" - allowed_authorization_headers: - - "x-qotm-session" -``` - -This configuration tells $productName$ about the auth service, notably that it needs the `/extauth` prefix, and that it's OK for it to pass back the `x-qotm-session` header. Note that `path_prefix` and `allowed_*_headers` are optional. - -If the auth service uses a framework like [Gorilla Toolkit](http://www.gorillatoolkit.org) which enforces strict slashes as HTTP path separators, it is possible to end up with an infinite redirect where the auth service's framework redirects any request with non-conformant slashing. This would arise if the above example had `path_prefix: "/extauth/"`, the auth service would see a request for `/extauth//backend/get-quote/` which would then be redirected to `/extauth/backend/get-quote/` rather than actually be handled by the authentication handler. For this reason, remember that the full path of the incoming request including the leading slash, will be appended to `path_prefix` regardless of non-conformant slashing. - -You can apply this file from getambassador.io with - -``` -kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/demo/demo-auth-enable.yaml -``` - -or, again, apply it from a local file if you prefer. - -Note that the cluster does not yet contain any $productName$ AuthService definition. - -## 3. Test authentication - -If we `curl` to a protected URL: - -``` -$ curl -Lv $AMBASSADORURL/backend/get-quote/ -``` - -We get a 401 since we haven't authenticated. - -``` -* TCP_NODELAY set -* Connected to 54.165.128.189 (54.165.128.189) port 32281 (#0) -> GET /backend/get-quote/ HTTP/1.1 -> Host: 54.165.128.189:32281 -> User-Agent: curl/7.63.0 -> Accept: */* -> -< HTTP/1.1 401 Unauthorized -< www-authenticate: Basic realm="Ambassador Realm" -< content-length: 0 -< date: Thu, 23 May 2019 15:24:55 GMT -< server: envoy -< -* Connection #0 to host 54.165.128.189 left intact -``` - -If we authenticate to the service, we will get a quote successfully: - -``` -$ curl -Lv -u username:password $AMBASSADORURL/backend/get-quote/ - -* TCP_NODELAY set -* Connected to 54.165.128.189 (54.165.128.189) port 32281 (#0) -* Server auth using Basic with user 'username' -> GET /backend/get-quote/ HTTP/1.1 -> Host: 54.165.128.189:32281 -> Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= -> User-Agent: curl/7.63.0 -> Accept: */* -> -< HTTP/1.1 200 OK -< content-type: application/json -< date: Thu, 23 May 2019 15:25:06 GMT -< content-length: 172 -< x-envoy-upstream-service-time: 0 -< server: envoy -< -{ - "server": "humble-blueberry-o2v493st", - "quote": "Nihilism gambles with lives, happiness, and even destiny itself!", - "time": "2019-05-23T15:25:06.544417902Z" -* Connection #0 to host 54.165.128.189 left intact -} -``` - -## More - -For more details about configuring authentication, see the [`External` filter](/docs/edge-stack/latest/topics/using/filters/) documentation. diff --git a/content/en/docs/3.5/howtos/cert-manager.md b/content/en/docs/3.5/howtos/cert-manager.md deleted file mode 100644 index d742decd..00000000 --- a/content/en/docs/3.5/howtos/cert-manager.md +++ /dev/null @@ -1,230 +0,0 @@ -# Using cert-manager - -[//]: # (+FIX+ link to "TLS and certificates" concept) - -$AESproductName$ has simple and easy built-in support for automatically [using ACME] with the -`http-01` challenge to create and renew TLS certificates. However, this support is not available -in $OSSproductName$, and it is limited to the ACME `http-01` challenge type. If you're running -$OSSproductName$, or if you require more flexible certificate management (such as using ACME's -`dns-01` challenge, or using a non-ACME certificate source), external certificate management -tools are also supported. - -[using ACME]: ../../topics/running/host-crd - -One such tool is Jetstack's [cert-manager](https://github.com/jetstack/cert-manager), which is a general-purpose tool -for managing certificates in Kubernetes. Cert-manager will automatically create and renew TLS certificates and store -them as Kubernetes secrets for easy use in a cluster. $productName$ will automatically watch for secret -changes and reload certificates upon renewal. - -> **Note:** This document assumes cert-manager v0.15 or greater. This document has been updated to use CRD standards -> specified in v0.15. [Legacy CRD support](https://cert-manager.io/docs/installation/upgrading/upgrading-0.14-0.15/) -> was removed in cert-manager v0.15, see their [upgrading](https://cert-manager.io/docs/installation/upgrading/) -> document for more info. - -## Install cert-manager - -There are many different ways to [install cert-manager](https://cert-manager.io/docs/installation/). For simplicity, we will use Helm. - -1. Create the cert-manager CRDs. - ``` - kubectl apply -f https://github.com/jetstack/cert-manager/releases/latest/download/cert-manager.crds.yaml - ``` - -2. Add the `jetstack` Helm repository. - ``` - helm repo add jetstack https://charts.jetstack.io && helm repo update - ``` - -3. Install cert-manager. - - ``` - kubectl create ns cert-manager - helm install cert-manager --namespace cert-manager jetstack/cert-manager - ``` - -## Issuing certificates - -cert-manager issues certificates from a CA such as [Let's Encrypt](https://letsencrypt.org/). It does this using the ACME protocol which supports various challenge mechanisms for verifying ownership of the domain. - -### Issuer - -An `Issuer` or `ClusterIssuer` identifies which Certificate Authority cert-manager will use to issue a certificate. `Issuer` is a namespaced resource allowing you to use different CAs in each namespace, a `ClusterIssuer` is used to issue certificates in any namespace. Configuration depends on which ACME [challenge](#challenge) you are using. - -### Certificate - -A [Certificate](https://cert-manager.io/docs/concepts/certificate/) is a namespaced resource that references an `Issuer` or `ClusterIssuer` for issuing certificates. `Certificate`s define the DNS name(s) a key and certificate should be issued for, as well as the secret to store those files (e.g. `ambassador-certs`). Configuration depends on which ACME [challenge](#challenge) you are using. - -By duplicating issuers, certificates, and secrets one can support multiple domains with [SNI](../../topics/running/tls/sni). - -## Challenge - -cert-manager supports two kinds of ACME challenges that verify domain ownership in different ways: HTTP-01 and DNS-01. - -### DNS-01 challenge - -The DNS-01 challenge verifies domain ownership by proving you have control over its DNS records. Issuer configuration will depend on your [DNS provider](https://cert-manager.io/docs/configuration/acme/dns01/#supported-dns01-providers). This example uses [AWS Route53](https://cert-manager.io/docs/configuration/acme/dns01/route53/). - -1. Create the IAM policy specified in the cert-manager [AWS Route53](https://cert-manager.io/docs/configuration/acme/dns01/route53/) documentation. - -2. Note the `accessKeyID` and create a `secret` named `prod-route53-credentials-secret` in the cert-manager namespace that has a key value: `secret-access-key` from your AWS IaM credentials. - -3. Create and apply a `ClusterIssuer`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: ClusterIssuer - metadata: - name: letsencrypt-prod - spec: - acme: - email: email@example.com - server: https://acme-v02.api.letsencrypt.org/directory - privateKeySecretRef: - name: letsencrypt-prod - solvers: - - selector: - dnsZones: - - "myzone.route53.com" - dns01: - route53: - region: us-east-1 - accessKeyID: {accessKeyID} - hostedZoneID: {Hosted Zone ID} # optional, allows you to reduce the scope of permissions in Amazon IAM - secretAccessKeySecretRef: - name: prod-route53-credentials-secret - key: secret-access-key - ``` - -4. Create and apply a `Certificate`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: Certificate - metadata: - name: myzone.route53.com - # cert-manager will put the resulting Secret in the same Kubernetes - # namespace as the Certificate. You should create the certificate in - # whichever namespace you want to configure a Host. - spec: - secretName: ambassador-certs - issuerRef: - name: letsencrypt-prod - kind: ClusterIssuer - commonName: myzone.route53.com - dnsNames: - - myzone.route53.com - ``` - -5. Verify the secret is created. - - ``` - $ kubectl get secrets -n ambassador - NAME TYPE DATA AGE - ambassador-certs kubernetes.io/tls 2 1h - ``` - -### HTTP-01 challenge - -The HTTP-01 challenge verifies ownership of the domain by sending a request for a specific file on that domain. cert-manager accomplishes this by sending a request to a temporary pod with the prefix `/.well-known/acme-challenge/`. To perform this challenge: - -1. Create and apply a `ClusterIssuer`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: ClusterIssuer - metadata: - name: letsencrypt-prod - spec: - acme: - email: email@example.com - server: https://acme-v02.api.letsencrypt.org/directory - privateKeySecretRef: - name: letsencrypt-prod - solvers: - - http01: - ingress: - class: nginx - selector: {} - ``` - -2. Create and apply a `Certificate`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: Certificate - metadata: - name: ambassador-certs - # cert-manager will put the resulting Secret in the same Kubernetes - # namespace as the Certificate. You should create the certificate in - # whichever namespace you want to configure a Host. - namespace: ambassador - spec: - secretName: ambassador-certs - issuerRef: - name: letsencrypt-prod - kind: ClusterIssuer - dnsNames: - - example.com - ``` - -3. Apply both the `ClusterIssuer` and `Certificate` - - After applying both of these YAML manifests, you will notice that cert-manager has spun up a temporary pod named `cm-acme-http-solver-xxxx` but no certificate has been issued. Check the cert-manager logs and you will see a log message that looks like this: - - ``` - $ kubectl logs cert-manager-756d6d885d-v7gmg - ... - Preparing certificate default/ambassador-certs with issuer - Calling GetOrder - Calling GetAuthorization - Calling HTTP01ChallengeResponse - Cleaning up old/expired challenges for Certificate default/ambassador-certs - Calling GetChallenge - wrong status code '404' - Looking up Ingresses for selector certmanager.k8s.io/acme-http-domain=161156668,certmanager.k8s.io/acme-http-token=1100680922 - Error preparing issuer for certificate default/ambassador-certs: http-01 self check failed for domain "example.com - ``` - -4. Create a Mapping for the `/.well-known/acme-challenge/` route. - - cert-manager uses an `Ingress` to issue the challenge to `/.well-known/acme-challenge/` that is incompatible with Ambassador. We will need to create a `Mapping` so the cert-manager can reach the temporary pod. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Mapping - metadata: - name: acme-challenge-mapping - spec: - hostname: "*" - prefix: /.well-known/acme-challenge/ - rewrite: "" - service: acme-challenge-service - - --- - apiVersion: v1 - kind: Service - metadata: - name: acme-challenge-service - spec: - ports: - - port: 80 - targetPort: 8089 - selector: - acme.cert-manager.io/http01-solver: "true" - ``` - - Apply the YAML and wait a couple of minutes. cert-manager will retry the challenge and issue the certificate. - -5. Verify the secret is created: - - ``` - $ kubectl get secrets - NAME TYPE DATA AGE - ambassador-certs kubernetes.io/tls 2 1h - ambassador-token-846d5 kubernetes.io/service-account-token 3 2h - ``` diff --git a/content/en/docs/3.5/howtos/client-cert-validation.md b/content/en/docs/3.5/howtos/client-cert-validation.md deleted file mode 100644 index 10fe639d..00000000 --- a/content/en/docs/3.5/howtos/client-cert-validation.md +++ /dev/null @@ -1,110 +0,0 @@ -# Client certificate validation - -[//]: # (+FIX+ link to "TLS and client certs" concept) - -Sometimes, for additional security or authentication purposes, you will want -the server to validate who the client is before establishing an encrypted -connection. - -To support this, $productName$ can be configured to use a provided CA certificate -to validate certificates sent from your clients. This allows for client-side -mTLS where both $productName$ and the client provide and validate each other's -certificates. - -## Prerequisites - -- [openssl](https://www.openssl.org/source/) For creating client certificates -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [$productName$](../../tutorials/getting-started) -- [cURL](https://curl.haxx.se/download.html) - - -## Configuration - -1. Create a certificate and key. - - This can be done with a single command with `openssl`: - - ``` - openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 - ``` - - Enter a passcode for PEM files and fill in the certificate information. - Since this certificate will only be shared between a client and $productName$, - the Common Name must be set to something. Everything else can be left blank. - - **Note:** If using MacOS, - [you must](https://curl.haxx.se/mail/archive-2014-10/0053.html) - add the certificate and key as a PKCS encoded file to your Keychain. To do - this: - - 1. Encode `cert.pem` and `key.pem` created above in PKCS format - - ``` - openssl pkcs12 -inkey key.pem -in cert.pem -export -out certificate.p12 - ``` - - 2. Open "Keychain Access" on your system and select "File"->"Import Items..." - - 3. Navigate to your working directory and select the `certificate.p12` file - we just created above. - -2. Create a secret to hold the client CA certificate. - - ``` - kubectl create secret generic client-cacert --from-file=tls.crt=cert.pem - ``` - -3. Configure $productName$ to use this certificate for client certificate validation. - - First create a `Host` to manage your domain: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Host - metadata: - name: example-host - spec: - hostname: host.example.com - acmeProvider: - email: julian@example.com - ``` - - Then create a `TLSContext` to configure advanced TLS options like client - certificate validation: - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: TLSContext - metadata: - name: example-host-context - spec: - hosts: - - host.example.com - secret: host.example.com - ca_secret: client-cacert - cert_required: false # Optional: Configures $productName$ to reject the request if the client does not provide a certificate. Default: false - ``` - - **Note**: Client certificate validation requires $productName$ be configured to terminate TLS - - $productName$ is now be configured to validate certificates that the client provides. - -4. Test that $productName$ is validating the client certificates with `curl` - - **Linux**: - ``` - curl -v --cert cert.pem --key key.pem https://host.example.com/ - ``` - - **MacOS**: - ``` - curl -v --cert certificate.p12:[password] https://host.example.com/ - ``` - - Looking through the verbose output, you can see we are sending a client - certificate and $productName$ is validating it. - - If you need further proof, simply create a new set of certificates and - try sending the curl with those. You will see $productName$ deny the request. diff --git a/content/en/docs/3.5/howtos/configure-communications.md b/content/en/docs/3.5/howtos/configure-communications.md deleted file mode 100644 index 1ac09d2c..00000000 --- a/content/en/docs/3.5/howtos/configure-communications.md +++ /dev/null @@ -1,763 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -Configuring $productName$ Communications -======================================== - -For $productName$ to do its job of managing network communications for your services, it first needs to know how its own communications should be set up. This is handled by a combination of resources: the `Listener`, the `Host`, and the `TLSContext`. - -- `Listener`: defines where, and how, $productName$ should listen for requests from the network. -- `Host`: defines which hostnames $productName$ should care about, and how to handle different kinds of requests for those hosts. `Host`s can be associated with one or more `Listener`s. -- `TLSContext`: defines whether, and how, $productName$ will manage TLS certificates and options. `TLSContext`s can be associated with one or more `Host`s. - -Once the basic communications setup is in place, $productName$ `Mapping`s and `TCPMapping`s can be associated with `Host`s to actually do routing. - - - Remember that Listener and Host resources are  - required for a functioning $productName$ installation that can route traffic!
- Learn more about Listener.
- Learn more about Host. - - - - Remember than $productName$ does not make sure that a wildcard Host exists! If the - wildcard behavior is needed, a Host with a hostname of "*" - must be defined by the user. - - - - Several different resources work together to configure communications. A working knowledge of all of them - can be very useful:
- Learn more about Listener.
- Learn more about Host.
- Learn more about Mapping.
- Learn more about TCPMapping.
- Learn more about TLSContext. - - -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]: ../../topics/running/tls -[certificates]: ../../topics/running/tls#certificates-and-secrets -[check the logs]: ../../topics/running/debugging#review-logs - -Examples / Cookbook -------------------- - -### Basic HTTP and HTTPS - -A useful configuration is to support either HTTP or HTTPS, in this case on either port 8080 or port 8443. This -tends to make it as easy as possible to communicate with the services behind the $productName$ instance. It uses -two `Listener`s and at least one `Host`. - - -#### `Listener`s: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: http-listener -spec: - port: 8080 - protocol: HTTPS # NOT A TYPO, see below - securityModel: XFP - hostBinding: - namespace: - from: SELF # See below ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: - namespace: - from: SELF # See below -``` - -- Both `Listener`s use `protocol: HTTPS` to allow Envoy to inspect incoming connections, determine - whether or not TLS is in play, and set `X-Forwarded-Proto` appropriately. The `securityModel` then specifies - that `X-Forwarded-Proto` will determine whether requests will be considered secure or insecure. - -- The `hostBinding` shown here will allow any `Host` in the same namespace as the `Listener`s - to be associated with both `Listener`s; in turn, that will allow access to that `Host`'s - `Mapping`s from either port. For greater control, use a `selector` instead. - -- Note that the `Listener`s do not specify anything about TLS certificates. The `Host` - handles that; see below. - - - Learn more about Listener - - -#### `Host` - -This example will assume that we expect to be reachable as `foo.example.com`, and that the `foo.example.com` -certificate is stored in the Kubernetes `Secret` named `foo-secret`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: "foo.example.com" - tlsSecret: - name: foo-secret - requestPolicy: - insecure: - action: Redirect -``` - -- The `tlsSecret` specifies the certificate in use for TLS termination. -- The `requestPolicy` specifies routing HTTPS and redirecting HTTP to HTTPS. -- Since the `Host` does not specify a `selector`, only `Mapping`s with a `hostname` that matches - `foo.example.com` will be associated with this `Host`. -- **Note well** that simply defining a `TLSContext` is not sufficient to terminate TLS: you must define either - a `Host` or an `Ingress`. -- Note that if no `Host` is present, but a TLS secret named `fallback-secret` is available, the system will - currently define a `Host` using `fallback-secret`. **This behavior is subject to change.** - - - Learn more about Host - - -### HTTP-Only - -Another straightforward configuration is to support only HTTP, in this case on port 8080. This uses a single -`Listener` and a single `Host`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: http-listener -spec: - port: 8080 - protocol: HTTP - securityModel: INSECURE - hostBinding: - namespace: - from: SELF # See below ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: "foo.example.com" - requestPolicy: - insecure: - action: Route -``` - -- Here, we listen only on port 8080, and only for HTTP. HTTPS will be rejected. -- Since requests are only allowed using HTTP, we declare all requests `INSECURE` by definition. -- The `Host` specifies routing HTTP, rather than redirecting it. - - - - Learn more about Listener
- Learn more about Host - - -### TLS using ACME ($AESproductName$ only) - -This scenario uses ACME to get certificates for `foo.example.com` and `bar.example.com`. HTTPS traffic to either -host is routed; HTTP traffic to `foo.example.com` will be redirected to HTTPS, but HTTP traffic to `bar.example.com` -will be rejected outright. - -Since this example uses ACME, **it is only supported in $AESproductName$**. - -For demonstration purposes, we show this example listening for HTTPS on port 9999, using `X-Forwarded-Proto`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener-9999 -spec: - port: 9999 - protocol: HTTPS - securityModel: XFP - hostBinding: # Edit as needed - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - acmeProvider: - email: julian@example.com ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - acmeProvider: - email: julian@example.com - requestPolicy: - insecure: - action: Reject -``` - -(`Mapping`s are not shown.) - -- Our `Listener`s will accept HTTPS and HTTP on port 9999, and the protocol used will dictate whether - the requests are secure (HTTPS) or insecure (HTTP). -- `foo-host` defaults to ACME with Let's Encrypt, since `acmeProvider.authority` is not provided. -- `foo-host` defaults to redirecting insecure requests, since the default for `requestPolicy.insecure.action` is `Redirect`. -- `bar-host` uses Let's Encrypt as well, but it will reject insecure requests. - -**If you use ACME for multiple Hosts, add a wildcard Host too.** -This is required to manage a known issue. This issue will be resolved in a future Ambassador Edge Stack release. - - - Learn more about Listener
- Learn more about Host - - -### Multiple TLS Certificates - -This scenario uses TLS without ACME. Each of our two `Host`s uses a distinct TLS certificate. HTTPS -traffic to either`foo.example.com` or `bar.example.com` is routed, but this time `foo.example.com` will redirect -HTTP requests, while `bar.example.com` will route them. - -Since this example does not use ACME, it is supported in $productName$ as well as $AESproductName$. - -For demonstration purposes, we show this example listening for HTTPS on port 4848, using `X-Forwarded-Proto`. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: foo-example-secret -data: - tls.crt: -certificate PEM- - tls.key: -secret key PEM- ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: bar-example-secret -data: - tls.crt: -certificate PEM- - tls.key: -secret key PEM- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener-4848 -spec: - port: 4848 - protocol: HTTPS - securityModel: XFP - hostBinding: # Edit as needed - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - tlsSecret: - name: foo-example-secret ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - tlsSecret: - name: bar-example-secret - requestPolicy: - insecure: - action: Route -``` - -- `foo-host` and `bar-host` simply reference the `tlsSecret` to use for termination. - - If the secret involved contains a wildcard cert, or a cert with multiple SAN, both `Host`s could - reference the same `tlsSecret`. -- `foo-host` relies on the default insecure routing action of `Redirect`. -- `bar-host` must explicitly specify routing HTTP. - - - - Learn more about Listener
- Learn more about Host - - -### Using a `TLSContext` - -If you need to share other TLS settings between two `Host`s, you can reference a `TLSContext` as well as -the `tlsSecret`. This is the same as the previous example, but we use a `TLSContext` to set `ALPN` information, -and we assume that the `Secret` contains a wildcard cert. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: wildcard-example-secret -data: - tls.crt: -wildcard here- - tls.key: -wildcard here- ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-context -spec: - secret: wildcard-example-secret - alpn_protocols: [h2, istio] ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener-4848 -spec: - port: 4848 - protocol: HTTPS - securityModel: XFP - hostBinding: # Edit as needed - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - tlsContext: - name: example-context - tlsSecret: - name: wildcard-example-secret ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - tlsContext: - name: example-context - tlsSecret: - name: wildcard-example-secret - requestPolicy: - insecure: - action: Route -``` - -- Note that specifying the `tlsSecret` is still necessary, even when `tlsContext` is specified. - - - - Learn more about Listener
- Learn more about Host - - -### ACME With a TLSContext ($AESproductName$ Only) - -In $AESproductName$, you can use a `TLSContext` with ACME as well. This example is the same as "TLS using ACME", -but we use a `TLSContext` to set `ALPN` information. Again, ACME is only supported in $AESproductName$. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-context -spec: - secret: example-acme-secret - alpn_protocols: [h2, istio] ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - acmeProvider: - email: julian@example.com - tlsContext: - name: example-context - tlsSecret: - name: example-acme-secret -``` - -- Note that we don't provide the `Secret`: the ACME client will create it for us. - - - - Learn more about Listener
- Learn more about Host - - -### Using an L7 Load Balancer to Terminate TLS - -In this scenario, a layer 7 load balancer ahead of $productName$ will terminate TLS, so $productName$ will always see HTTP with a known good `X-Forwarded-Protocol`. We'll use that to route HTTPS and redirect HTTP. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: lb-listener -spec: - port: 8443 - protocol: HTTP - securityModel: XFP - l7Depth: 1 - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: "foo.example.com" - requestPolicy: - insecure: - action: Redirect -``` - -- We set `l7Depth` to 1 to indicate that there's a single trusted L7 load balancer ahead of us. -- We specifically set this Listener to HTTP-only, but we stick with port 8443 just because we expect people setting up TLS at all to expect to use port 8443. (There's nothing special about the port number, pick whatever you like.) -- Our `Host` does not specify a `tlsSecret`, so $productName$ will not try to terminate TLS. -- Since the `Listener` still pays attention to `X-Forwarded-Proto`, both secure and insecure requests - are possible, and we use the `Host` to route HTTPS and redirect HTTP. - - - - Learn more about Listener
- Learn more about Host - - -### Using a Split L4 Load Balancer to Terminate TLS - -Here, we assume that $productName$ is behind a load balancer setup that handles TLS at layer 4: - -- Incoming cleartext traffic is forwarded to $productName$ on port 8080. -- Incoming TLS traffic is terminated at the load balancer, then forwarded to $productName$ _as cleartext_ on port 8443. -- This might involve multiple L4 load balancers, but the actual number doesn't matter. -- The actual port numbers we use don't matter either, as long as $productName$ and the load balancer(s) agree on which port is for which traffic. - -We're going to route HTTPS for both `foo.example.com` and `bar.example.com`, redirect HTTP for `foo.example.com`, and reject HTTP for `bar.example.com`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: split-lb-one-listener -spec: - protocol: HTTP - port: 8080 - securityModel: INSECURE - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: split-lb-two-listener -spec: - protocol: HTTP - port: 8443 - securityModel: SECURE - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - requestPolicy: - insecure: - action: Reject -``` - -- Since L4 load balancers cannot set `X-Forwarded-Protocol`, we don't use it at all here: instead, we dictate that 8080 and 8443 both speak cleartext HTTP, but everything arriving at port 8080 is insecure and everything at port 8443 is secure. - - - - Learn more about Listener
- Learn more about Host - - -### Listening on Multiple Ports - -There's no reason you need to use ports 8080 and 8443, or that you're limited to two ports. Here we'll use ports 9001 and 9002 for HTTP, and port 4001 for HTTPS. We'll route traffic irrespective of protocol. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-9001 -spec: - protocol: HTTP - port: 9001 - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-9002 -spec: - protocol: HTTP - port: 9002 - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-4001 -spec: - protocol: HTTPS - port: 4001 - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: route-host -spec: - requestPolicy: - insecure: - action: Route -``` - -- We can use `X-Forwarded-Proto` for all our `Listener`s: the HTTP-only `Listener`s will set it correctly. -- Each `Listener` can specify only one port, but there's no hardcoded limit on the number of `Listener`s you can have. - - - - Learn more about Listener
- Learn more about Host - - -### Using Labels to Associate `Host`s and `Listener`s - -In the examples above, the `Listener`s all associate with any `Host` in their namespace. In this -example, we will use Kubernetes labels to control the association instead. - -Here, we'll listen for HTTP to `foo.example.com` on port 8888, and for either HTTP or HTTPS to `bar.example.com` on -port 9999 (where we'll redirect HTTP to HTTPS). Traffic to `baz.example.com` will work on both ports, and we'll route -HTTP for it rather than redirecting. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-8888 -spec: - protocol: HTTP - port: 8888 - securityModel: XFP - hostBinding: - selector: - matchLabels: - tenant: foo ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-9999 -spec: - protocol: HTTPS - port: 9999 - securityModel: XFP - hostBinding: - selector: - matchLabels: - tenant: bar ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: bar-secret -data: - tls.crt: -wildcard here- - tls.key: -wildcard here- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host - labels: - tenant: foo -spec: - hostname: foo.example.com - requestPolicy: - insecure: - action: Route ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host - labels: - tenant: bar -spec: - hostname: bar.example.com - tlsSecret: - name: bar-secret ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: baz-host - labels: - tenant: foo - tenant: bar -spec: - hostname: baz.example.com - tlsSecret: - name: bar-secret - requestPolicy: - insecure: - action: Route -``` - -- Note the `labels` on each `Host`, which the `hostBinding` on the `Listener` can reference. - - Note also that only label selectors are supported at the moment. - - - - Learn more about Listener
- Learn more about Host - - -### Wildcard `Host`s and `Mapping`s - -In a `Mapping`, the `host` is now treated as a glob rather than an exact match, with the goal of vastly reducing the need for `host_regex`. (The `hostname` in a `Host` has always been treated as a glob). - -- **Note that only prefix and suffix matches are supported**, so `*.example.com` and `foo.*` are both fine, but `foo.*.com` will not work -- you'll need to use `host_regex` if you really need that. (This is an Envoy limitation.) - -In this example, we'll accept both HTTP and HTTPS, but: - -- Cleartext traffic to any host in `lowsec.example.com` will be routed. -- Cleartext traffic to any host in `normal.example.com` will be redirected. -- Any other cleartext traffic will be rejected. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: example-secret -data: - tls.crt: -wildcard for *.example.com here- - tls.key: -wildcard for *.example.com here- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-8443 -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: lowsec-host -spec: - hostname: "*.lowsec.example.com" - tlsSecret: - name: example-secret - requestPolicy: - insecure: - action: Route ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: normal-host -spec: - hostname: "*.normal.example.com" - tlsSecret: - name: example-secret - requestPolicy: # We could leave this out since - insecure: # redirecting is the default, but - action: Redirect # it's spelled out for clarity. ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: catchall-host -spec: - hostname: "*.example.com" - tlsSecret: - name: example-secret - requestPolicy: - insecure: - action: Reject -``` - -- We'll listen for HTTP or HTTPS on port 8443. -- The three `Host`s apply different insecure routing actions depending on the hostname. -- You could also do this with `host_regex`, but using `host` with globs will give better performance. - - Being able to _not_ associate a given `Mapping` with a given `Host` when the `Mapping`'s - `host` doesn't match helps a lot when you have many `Host`s. - - Reliably determining if a regex (for the `Mapping`) matches a glob (for the `Host`) isn't really possible, so we can't prune `host_regex` `Mapping`s at all. - - - Learn more about Listener
- Learn more about Host - diff --git a/content/en/docs/3.5/howtos/consul.md b/content/en/docs/3.5/howtos/consul.md deleted file mode 100644 index d75e35ce..00000000 --- a/content/en/docs/3.5/howtos/consul.md +++ /dev/null @@ -1,564 +0,0 @@ - -import Alert from '@material-ui/lab/Alert'; - -# Consul integration - -
-

Contents

- -- [Consul integration](#consul-integration) - - [Architecture overview](#architecture-overview) - - [Installing Consul](#installing-consul) - - [Installing $productName$](#installing-consul) - - [Using Consul for service discovery](#using-consul-for-service-discovery) - - [Using Consul for authorization and encryption](#using-consul-for-authorization-and-encryption) - - [Environment variables](#environment-variables) - - [More information](#more-information) - -
- -[Consul](https://www.consul.io) is a widely used service mesh. -$productName$ natively supports service discovery and unauthenticated -communication to services in Consul. Additionally, the *Ambassador -Consul Connector* enables $productName$ to encrypt and authenticate -its communication via mTLS with services in Consul that make use of -[Consul's *Connect* feature](https://www.consul.io/docs/connect). - -## Architecture overview - -Using Consul with $productName$ is particularly useful when deploying -$productName$ in hybrid cloud environments where you deploy -applications on VMs and Kubernetes. In this environment, Consul -enables $productName$ to securely route over TLS to any application -regardless of where it is deployed. - -In this architecture, Consul serves as the source of truth for your -entire data center, tracking available endpoints, service -configuration, and secrets for TLS encryption. New applications and -services automatically register themselves with Consul using the -Consul agent or API. When you send a request through $productName$, -$productName$ sends the request to an endpoint based on the data in -Consul. - -![ambassador-consul](../images/consul-ambassador.png) - -This guide first instructs you on registering a service with Consul -and using $productName$ to dynamically route requests to that service -based on Consul's service discovery data, and subsequently instructs -you on using using the Ambassador Consul Connector to use Consul for -authorizing and encrypting requests. - -## Installing Consul - -If you already have Consul installed in your cluster, then go ahead -and skip to the next section. - -1. Before you install Consul, make sure to check the Consul - documentation for any setup steps specific to your platform. Below - you can find setup guides for some of the more popular Kubernetes - platforms. This step is primarily to ensure you have the proper - permissions to set up Consul. You can skip these guides if your - cluster is already configured to grant you the necessary - permissions. - - - [Microsoft Azure Kubernetes Service (AKS)](https://learn.hashicorp.com/tutorials/consul/kubernetes-aks-azure?utm_source=consul.io&utm_medium=docs) - - [Amazon Elastic Kubernetes Service (EKS)](https://learn.hashicorp.com/tutorials/consul/kubernetes-eks-aws?utm_source=consul.io&utm_medium=docs) - - [Google Kubernetes Engine (GKE)](https://learn.hashicorp.com/tutorials/consul/kubernetes-gke-google?utm_source=consul.io&utm_medium=docs) - - - - If you did not find your Kubernetes platform above, check the - [Consul documentation here](https://www.consul.io/docs/k8s) to see - if there are specific setup instructions for your platform. - - - -2. Add the Hashicorp repository for installing Consul with Helm. If - you do not have Helm installed, you can find an [installation guide - here](https://helm.sh/docs/intro/install/). - - ```shell - helm repo add hashicorp https://helm.releases.hashicorp.com - ``` - -3. Create a new `consul-values.yaml` YAML file for the Consul - installation values and copy the values below into that file. - - ```yaml - global: - datacenter: dc1 - - ui: - service: - type: 'LoadBalancer' - - syncCatalog: - enabled: true - - server: - replicas: 1 - bootstrapExpect: 1 - - connectInject: - enabled: true - ``` - - - - Note: you are free to change the value of the `datacenter` field in - the install values. This is the the name of your Consul - Datacenter. - - - -4. Install Consul with Helm using the `consul-values.yaml` values file - you just created. - - ```shell - helm install -f consul-values.yaml hashicorp hashicorp/consul - ``` - -## Installing $productName$ - -If you have not already installed $productName$ in to your cluster, -then go to the [quick start guide](../../tutorials/getting-started) -before continuing any further in this guide. - -## Using Consul for service discovery - -This section of the guide instructs you on configuring $productName$ -to look for services registered to Consul, registering a demo -application with Consul, and configuring $productName$ to route to -this application using endpoint data from Consul. - -In this tutorial, you deploy the application in Kubernetes. However, -this application can be deployed anywhere in your data center, such as -on a VM. - -1. Configure $productName$ to look for services registered to Consul - by creating the `ConsulResolver`. Use `kubectl` to apply the - following manifest: - - ```shell - kubectl apply -f < - - **Note:** If you changed the name of your `datacenter` in the - Consul install values, make sure to change it in the resolver above - to match the name of your datacenter. - - If you changed the name of the helm install from `hashicorp` to - another value, make sure to update the value of the `address` field - in your resolver to match it. - - If you are having trouble figuring out what your `address` field - should be, it follow this format: - `http://{consul_server_pod}.{consul_server_service}.{namespace}.svc.cluster.local:{consul_port}`. - The default Consul port should be `8500` unless you changed it. - - - - This tells $productName$ that Consul is a service discovery endpoint. - - You must set the resolver to your `ConsulResolver` on a - per-`Mapping` basis, otherwise for that `Mapping` $productName$ - uses the default resolver. That is, in order for a `Mapping` to - make use of a service registered in Consul, you need to add - `resolver: consul-dc1` to that `Mapping`. - - For more information about resolver configuration, see the - [resolver reference documentation](../../topics/running/resolvers). - (If you're using Consul deployed elsewhere in your data center, - make sure the `address` points to your Consul FQDN or IP address). - -2. Deploy the Quote demo application. Use `kubectl` to - apply the following manifest: - - ```shell - kubectl apply -f < - - The `SERVICE_NAME` environment variable in the `quote-consul` - `Deployment` specifies the service name for Consul. The default - value is set to "quote-consul", so you only need to include it if - you want to change the service name. - - - - The Quote application contains code to automatically - register itself with Consul, using the `CONSUL_IP` and `POD_IP` - environment variables specified within the `quote-consul` container - spec. - - When you apply this manifest, it registers the `Pod` in the - `quote-consul` `Deployment` as a Consul service with the name - `quote-consul` and the IP address of the `Pod`. - - - - The `"consul.hashicorp.com/connect-inject": "false"` annotation - tells Consul that for this `Deployment` you do not want to use the - sidecar proxy that is part of Consul's Connect feature. Without - Consul's sidecar, the service needs to include code to make a - request to Consul to register the service. The manifest includes - the environment variables `CONSUL_IP`, `POD_IP`, and `SERVICE_NAME` - to provide the Quote service with enough information - to build that request and send it to Consul. To see how this code - works, see our [our Git repo for the Quote - service](https://github.com/datawire/quote). - - - -3. Verify the `quote-consul` `Deployment`'s `Pod` has been registered - with Consul. You can verify this by accessing the Consul UI. - - First use `kubectl port-forward` to make the UI available on your - local workstation: - - ```shell - kubectl port-forward service/hashicorp-consul-ui 8500:80 - ``` - - Then, while the port-forward is running, go to - http://localhost:8500/ in a web browser. You should see a service - named `quote-consul`. - - After you have verified that you see the `quote-consul` service in - your web browser, you may kill the port-forward. - - - - Port forwarding not working for you? Make sure the service name - matches your Consul UI service by checking `kubectl get svc -A` - - - -4. Configure $productName$ to make use of this `quote-consul` service. - Use `kubectl` to apply the following manifest: - - ```shell - kubectl apply -f < - -**Congratulations!** You're successfully routing traffic to the Quote -application, the location of which is registered in -Consul. - - - -## Using Consul for authorization and encryption - -In this part of the guide, you'll install a different version of the -demo application that now uses Consul's *Connect* feature to authorize -its incoming connections using mTLS, and install *Ambassador Consul -Connector* to enable $productName$ to authenticate to such services. - -The following steps assume you've already set up Consul for service -discovery, as detailed above. - -1. The Ambassador Consul Connector retrieves the TLS certificate - issued by the Consul CA and stores it in a Kubernetes `Secret` for - $productName$ to use. Deploy the Ambassador Consul Connector with - `kubectl`: - - ```shell - kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/consul/ambassador-consul-connector.yaml - ``` - - This installs in to your cluster: - - - RBAC resources. - - The Ambassador Consul Connector service. - - A `TLSContext` named `ambassador-consul` to load the - `ambassador-consul-connect` `Secret` into $productName$. - -2. Deploy a new version of the demo application, and configure it to - inject the Consul Connect sidecar by setting - `"consul.hashicorp.com/connect-inject"` to `true`. Note that in - this version of the configuration, you do not have to configure - environment variables for the location of the Consul server. Use - `kubectl` to apply the following manifest: - - ```yaml - kubectl apply -f - < - - Note: Annotations are used to attach metadata to Kubernetes - objects. You can use annotations to link external information to - objects, working in a similar, yet different, fashion to labels. - For more information on annotations, refer to the [Annotating - Kubernetes Services for - Humans](https://kubernetes.io/blog/2021/04/20/annotating-k8s-for-humans/) - article, or get started with annotations in your own cluster with - the [Ambassador Cloud Quick start - guide](https://www.getambassador.io/docs/cloud/latest/service-catalog/quick-start/). - - - - This deploys a demo application `Deployment` called `quote-connect` - (different than the `quote-consul` `Deployment` in the previous - section) with the Consul Connect sidecar proxy. The Connect - sidecar registers the application with Consul, requires TLS to - access the application, and exposes other [Consul Service - Segmentation](https://www.consul.io/docs/connect) features. - - The annotation `consul.hashicorp.com/connect-inject` being set to - `true` in this `Deployment` tells Consul that you want this - `Deployment` to use the Consul Connect sidecar. The sidecar - proxies requests to the service that it is attached to. Keep this - in mind mind when debug requests to the service. - -4. Verify the `quote-connect` `Deployment`'s `Pod` has been registered - with Consul. You can verify this by accessing the Consul UI. - - First use `kubectl port-forward` to make the UI available on your - local workstation: - - ```shell - kubectl port-forward service/hashicorp-consul-ui 8500:80 - ``` - - Then, while the port-forward is running, open - http://localhost:8500/ in a web browser. You should see a service - named `quote-connect`. - - After you have verified that you see the `quote-connect` service in - your web browser, you may kill the port-forward. - -5. Create a `Mapping` to configure $productName$ route to the - `quote-connect` service in Consul. Use `kubectl` to apply the - following manifest: - - ```shell - kubectl apply -f < - -**Congratulations!** You successfully configured the service to work -with the Consul Connect sidecar. - - - -### Environment variables - -The Ambassador Consul Connector can be configured with the following -environment variables. The defaults are best for most use-cases. - -| Environment Variable | Description | Default | -|------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------| -| `_AMBASSADOR_ID` | Set 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`) | `""` | -| `_CONSUL_HOST` | Set the IP or DNS name of the target Consul HTTP API server | `127.0.0.1` | -| `_CONSUL_PORT` | Set the port number of the target Consul HTTP API server | `8500` | -| `_AMBASSADOR_TLS_SECRET_NAME` | Set the name of the Kubernetes `v1.Secret` created by this program that contains the Consul-generated TLS certificate. | `$AMBASSADOR_ID-consul-connect` | -| `_AMBASSADOR_TLS_SECRET_NAMESPACE` | Set the namespace of the Kubernetes `v1.Secret` created by this program. | (same Namespace as the Pod running this integration) | - -## More information - -For more about $productName$'s integration with Consul, read the -[service discovery configuration](../../topics/running/resolvers) -documentation. diff --git a/content/en/docs/3.5/howtos/dist-tracing.md b/content/en/docs/3.5/howtos/dist-tracing.md deleted file mode 100644 index bc40df8f..00000000 --- a/content/en/docs/3.5/howtos/dist-tracing.md +++ /dev/null @@ -1,49 +0,0 @@ -# Explore distributed tracing and Kubernetes monitoring - -The Kubernetes monitoring and distributed tracing landscape is hard to grasp. Although this conceptual approach to [observability is nothing new](https://blog.getambassador.io/distributed-tracing-with-java-microdonuts-kubernetes-and-the-ambassador-api-gateway-ace15b62a89e) — companies like New Relic revolutionized single-application performance monitoring (APM) over a decade ago — it took a few years and the [Dapper publication](https://research.google/pubs/pub36356/) for this idea to migrate to distributed applications. The importance of this technology is only increasing, as more and more of us are building [“deep systems”](https://lightstep.com/deep-systems/). - -As the industry is slowly but surely maturing, standardization is underway. Standardization means proprietary vendor solutions and open source projects are able to collaborate, making our lives easier. For newcomers, understanding the plethora of options, concepts, specifications, and implementations available is still a daunting task: - -* How are Zipkin and Jaeger related? -* What is header propagation? -* Which headers format should I use? -* Who owns the initialization of a trace context? -* How are the data points collected? - -The [K8s Initializer](https://app.getambassador.io/initializer/) can make it easy to enable distributed tracing in any microservices-based system by offering an opinionated and preconfigured application stack that will get you up and running in no time. This way, you can focus on understanding your service topology and interactions rather than waste days on attempting to understand competing standard integrations and tuning configuration switches. - -## One-Click Tracing Configuration with the K8s Initializer - -The K8s Initializer is a tool we built for you to quickly bootstrap any Kubernetes cluster with your own application-ready playground. It will generate YAML manifests for ingress, observability, and more in just a few clicks. Once installed on a local or remote Kubernetes cluster, the generated Kubernetes manifest resources will give you a perfect sandbox environment to deploy your own applications and explore standard integrations. - -Specifically for observability and distributed tracing, the K8s Initializer bundles a Jaeger installation to collect and visualize traces along with a pre-configured Ambassador Edge Stack acting as the ingress controller that will create a trace context on every request. A single selection is required. - -As per the option we selected, we’ll be generating Zipkin-format traces and use B3 headers for propagation between our services. There you have it! Instrument your Java, Python, Golang or Node.js applications with Zipkin and B3 header propagation libraries, then configure your code to send the trace data to the `jaeger-collector.monitoring:9411` service endpoint. - -All that is left to do is making a few requests and visualizing the trace data in the Jaeger UI. - -## Visualizing Trace Data - -As we installed the Ambassador Edge Stack as our ingress controller for Kubernetes via the K8s Initializer, it will instrument parent trace spans for each request coming into our Kubernetes cluster from the internet. The K8s Initializer also pre-configured Ambassador to exposes the Jaeger UI on a subpath: `https://$AMBASSADOR_IP/jaeger/` - -Simply by visiting this URL on our installation, we are able to visualize the generated and collected trace information emitted by our Ambassador installation: - -![Jaeger screenshot](../images/jaeger.png) - -## Tracing the Future: OpenTelemetry - -The [OpenTelemetry project](https://opentelemetry.io/) was created with the intent of stopping the proliferation of API standards and libraries one might need to support for all their observability needs, effectively replacing the Zipkin-API, OpenCensus, OpenTracing and more competing implementations. - -> OpenTelemetry provides a single set of APIs, libraries, agents, and collector services to capture distributed traces and metrics from your application. You can analyze them using Prometheus, Jaeger, and other observability tools.
--[https://opentelemetry.io/](https://opentelemetry.io/) - -It’s at this point in the conversation that someone inevitably mentions that XKCD... - -![XKCD #927](../images/xkcd.png) - -OpenTelemetry ultimately supports multiple formats in its [OpenTelemetry-Collector](https://github.com/open-telemetry/opentelemetry-collector), easing the transition from one technology to another when installed as a middleware and translator to relay trace data to other collectors. Along with many of its long-awaited features, it supports multiple trace exporters for Jaeger, Zipkin and proprietary APIs. - -## Learn More -In this tutorial, we’ve shown you how to monitor your Kubernetes application with distributed tracing in just a few clicks with the K8s Initializer. To learn more about these tools and distributed tracing, we also recommend [A Complete Guide to Distributed Tracing by the Lightstep Team](https://lightstep.com/distributed-tracing/). - -We also have guides to setup Edge Stack with [Datadog](../tracing-datadog/), [Zipkin](../tracing-zipkin/), and [Prometheus and Grafana](../prometheus). diff --git a/content/en/docs/3.5/howtos/external-dns.md b/content/en/docs/3.5/howtos/external-dns.md deleted file mode 100644 index f0f51dbb..00000000 --- a/content/en/docs/3.5/howtos/external-dns.md +++ /dev/null @@ -1,130 +0,0 @@ -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 - -Start by checking the [ExternalDNS repo's deployment instructions](https://github.com/kubernetes-sigs/external-dns#deploying-to-a-cluster) to get information about the supported DNS providers and steps to setup ExternalDNS for your provider. Each DNS provider will have its own required steps as well as annotations, arguments, and permissions needed for the following configuration. - - -### Installation - -Configuration for a `ServiceAccount`, `ClusterRole`, and `ClusterRoleBinding` are necessary for the ExternalDNS deployment to support compatability 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 above for annotations and arguments for your DNS Provider. - - -1. Create a YAML file named `externaldns-config.yaml`, and copy the following configuration into it. - - - Ensure that the apiGroups include "getambassador.io" following "networking.k8s.io" and the resources include "hosts" after "ingresses". - - - ```yaml - --- - apiVersion: v1 - kind: ServiceAccount - metadata: - name: external-dns - annotations: - eks.amazonaws.com/role-arn: {ARN} # AWS ARN role - --- - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRole - metadata: - name: external-dns - rules: - - apiGroups: [""] - resources: ["services","endpoints","pods"] - verbs: ["get","watch","list"] - - apiGroups: ["extensions","networking.k8s.io", "getambassador.io"] - resources: ["ingresses", "hosts"] - verbs: ["get","watch","list"] - - apiGroups: [""] - resources: ["nodes"] - verbs: ["list","watch"] - --- - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRoleBinding - metadata: - name: external-dns-viewer - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: external-dns - subjects: - - kind: ServiceAccount - name: external-dns - namespace: default - --- - apiVersion: apps/v1 - kind: Deployment - metadata: - name: external-dns - spec: - strategy: - type: Recreate - selector: - matchLabels: - app: external-dns - template: - metadata: - labels: - app: external-dns - annotations: - iam.amazonaws.com/role: {ARN} # AWS ARN role - spec: - serviceAccountName: external-dns - containers: - - name: external-dns - image: registry.opensource.zalan.do/teapot/external-dns:latest - args: - - --source=ambassador-host - - --domain-filter=example.net # will make ExternalDNS see only the hosted zones matching provided domain, omit to process all available hosted zones - - --provider=aws - - --policy=upsert-only # would prevent ExternalDNS from deleting any records, omit to enable full synchronization - - --aws-zone-type=public # only look at public hosted zones (valid values are public, private or no value for both) - - --registry=txt - - --txt-owner-id= {Hosted Zone ID} # Insert Route53 Hosted Zone ID here - ``` - -2. Review the arguments section from the ExternalDNS deployment - - Configure or remove arguments to fit your needs. Additional arguments required for your DNS provider can be found by checking the [ExternalDNS repo's deployment instructions](https://github.com/kubernetes-sigs/external-dns#deploying-to-a-cluster). - - * `--source=ambassador-host` - required across all DNS providers to tell ExternalDNS to look for hostnames in the $productName$ `Host` configurations. - -3. Apply the above config with the following command to deploy ExternalDNS to your cluster and configure support for $productName$ - - ```shell - kubectl apply -f externaldns-ambassador.yaml - ``` - - - For the above example, ensure that you are using an EKS cluster, or register your cluster with AWS so that ExternalDNS can view and edit your AWS Hosted Zones. If you are using a cluster outside EKS and not registered with AWS you will see permissions errors from the ExternalDNS pod when attempting to list the Hosted Zones. - - -## Usage - -After applying the above configuration, ExternalDNS is ready to use. Configure a `Host` with the following annotation to allow ExternalDNS to get the IP address of your $productName$'s LoadBalancer and register it with your DNS provider. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: your-hostname - annotations: - external-dns.ambassador-service: $productDeploymentName$.$productNamespace$ -spec: - acmeProvider: - authority: none - hostname: your-hostname.example.com -``` - - -Victory! ExternalDNS is now running and configured to report $productName$'s IP and hostname with your DNS provider. diff --git a/content/en/docs/3.5/howtos/filter-dev-guide.md b/content/en/docs/3.5/howtos/filter-dev-guide.md deleted file mode 100644 index eefe8b6b..00000000 --- a/content/en/docs/3.5/howtos/filter-dev-guide.md +++ /dev/null @@ -1,97 +0,0 @@ -# Developing custom filters for routing - -Sometimes you may want $AESproductName$ to manipulate an incoming request. Some example use cases: - -* Inspect an incoming request, and add a custom header that can then be used for routing -* Add custom Authorization headers -* Validate an incoming request fits an OpenAPI specification before passing the request to a target service - -$AESproductName$ supports these use cases by allowing you to execute custom logic in `Filters`. Filters are written in Golang, and managed by $AESproductName$. If you want to write a filter in a language other than Golang, $AESproductName$ also has an HTTP/gRPC interface for Filters called `External`. - -## Prerequisites - -`Plugin` `Filter`s are built as [Go plugins](https://golang.org/pkg/plugin/) and loaded directly into the $AESproductName$ container so they can run in-process with the rest of $AESproductName$. - -To build a `Plugin` `Filter` into the $AESproductName$ container you will need -- Linux or MacOS host (Windows Subsystem for Linux is ok) -- [Docker](https://docs.docker.com/install/) -- [rsync](https://rsync.samba.org/) - -The `Plugin` `Filter` is built by `make` which uses Docker to create a stable build environment in a container and `rsync` to copy files between the container and your host machine. - -See the [README](https://github.com/datawire/apro-example-plugin) for more information on how the `Plugin` works. - -## Creating and deploying filters - -We've created an example filter that you can customize for your particular use case. - -1. Start with the example filter: `git clone - https://github.com/datawire/apro-example-plugin/`. - -2. Make code changes to `param-plugin.go`. Note: If you're developing a non-trivial filter, see the rapid development section below for a faster way to develop and test your filter. - -3. Run `make DOCKER_REGISTRY=...`, setting `DOCKER_REGISTRY` to point - to a registry you have access to. This will generate a Docker image - named `$DOCKER_REGISTRY/amb-sidecar-plugin:VERSION`. - -4. Push the image to your Docker registry: `docker push $DOCKER_REGISTRY/amb-sidecar-plugin:VERSION`. - -5. Configure $AESproductName$ to use the plugin by creating a `Filter` - and `FilterPolicy` CRD, as per the [filter reference](/docs/edge-stack/latest/topics/using/filters/). - -6. Update the standard $AESproductName$ manifest to use your Docker - image instead of the standard sidecar. - - ```patch - value: '60' - - name: AMBASSADOR_INTERNAL_URL - value: https://127.0.0.1:8443 - - image: docker.io/datawire/aes:$version$ - + image: DOCKER_REGISTRY/aes-plugin:VERSION - imagePullPolicy: Always - livenessProbe: - httpGet: - ``` - -## Rapid development of a custom filter - -During development, you may want to sidestep the deployment process for a faster development loop. The `aes-plugin-runner` helps you rapidly develop $AESproductName$ filters locally. - -To install the runner, download the latest version: - -Mac 64-bit | -Linux 64-bit - -Note that the plugin runner must match the version of $AESproductName$ that you are running. Place the binary somewhere in your `$PATH`. - -Information about open-source code used in `aes-plugin-runner` can be found by running `aes-plugin-runner --version`. - -Now, you can quickly test and develop your filter. - -1. In your filter directory, type: `aes-plugin-runner :8080 ./param-plugin.so`. -2. Test the filter by running `curl`: - - ``` - $ curl -Lv localhost:8080?db=2 - * Rebuilt URL to: localhost:8080/?db=2 - * Trying ::1... - * TCP_NODELAY set - * Connected to localhost (::1) port 8080 (#0) - > GET /?db=2 HTTP/1.1 - > Host: localhost:8080 - > User-Agent: curl/7.54.0 - > Accept: */* - > - < HTTP/1.1 200 OK - < X-Dc: Even - < Date: Mon, 25 Feb 2019 19:58:38 GMT - < Content-Length: 0 - < - * Connection #0 to host localhost left intact - ``` - -Note in the example above the `X-Dc` header is added. This lets you inspect the changes the filter is making to your HTTP header. - -## Further reading - -For more details about configuring filters and the `plugin` interface, see the [filter reference](/docs/edge-stack/latest/topics/using/filters/). diff --git a/content/en/docs/3.5/howtos/grpc.md b/content/en/docs/3.5/howtos/grpc.md deleted file mode 100644 index 3967ddf7..00000000 --- a/content/en/docs/3.5/howtos/grpc.md +++ /dev/null @@ -1,403 +0,0 @@ -# gRPC Connections - -$productName$ makes it easy to access your services from outside your application. This includes gRPC services, although a little bit of additional configuration is required: by default, Envoy connects to upstream services using HTTP/1.x and then upgrades to HTTP/2 whenever possible. However, gRPC is built on HTTP/2 and most gRPC servers do not speak HTTP/1.x at all. $productName$ must tell its underlying Envoy that your gRPC service only wants to speak to that HTTP/2, using the `grpc` attribute of a `Mapping`. - -## Writing a gRPC service for $productName$ - -There are many examples and walkthroughs on how to write gRPC applications so that is not what this article will aim to accomplish. If you do not yet have a service written you can find examples of gRPC services in all supported languages here: [gRPC Quickstart](https://grpc.io/docs/quickstart/) - -This document will use the [gRPC python helloworld example](https://github.com/grpc/grpc/tree/master/examples/python/helloworld) to demonstrate how to configure a gRPC service with $productName$. - -Follow the example up through [Run a gRPC application](https://grpc.io/docs/languages/python/quickstart/#run-a-grpc-application) to get started. - -### Dockerize - -After building our gRPC application and testing it locally, we need to package it as a Docker container and deploy it to Kubernetes. - -To run a gRPC application, we need to include the client/server and the protocol buffer definitions. - -For gRPC with python, we need to install `grpcio` and the common protos. - -```Dockerfile -FROM python:2.7 - -WORKDIR /grpc - -ENV PATH "$PATH:/grpc" - -COPY greeter_server.py /grpc -COPY helloworld_pb2.py /grpc -COPY helloworld_pb2_grpc.py /grpc - -RUN python -m pip install grpcio -RUN python -m pip install grpcio-tools googleapis-common-protos - -CMD ["python", "./greeter_server.py"] - -EXPOSE 50051 -``` - -Create the container and test it: - -``` -$ docker build -t /grpc_example -$ docker run -p 50051:50051 /grpc_example -``` - -Where `` is your Docker user or registry. - -Switch to another terminal and from the same directory, run the `greeter_client`. The output should be the same as running it outside of the container. - -``` -$ docker run -p 50051:50051 /grpc_example -Greeter client received: Hello, you! -``` - -Once you verify the container works, push it to your Docker registry: - -``` -$ docker push /grpc_example -``` - -### Mapping gRPC services - -$productName$ `Mapping`s are based on URL prefixes; for gRPC, the URL prefix is the full-service name, including the package path (`package.service`). These are defined in the `.proto` definition file. In the example [proto definition file](https://github.com/grpc/grpc/blob/master/examples/protos/helloworld.proto) we see: - -``` -package helloworld; - -// The greeting service definition. -service Greeter { ... } -``` - -so the URL `prefix` is `helloworld.Greeter` and the mapping would be: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py -spec: - hostname: "*" - grpc: True - prefix: /helloworld.Greeter/ - rewrite: /helloworld.Greeter/ - service: grpc-example -``` - -Note the `grpc: true` line - this is what tells Envoy to use HTTP/2 so the request can communicate with your backend service. Also note that you'll need `prefix` and `rewrite` the same here, since the gRPC service needs the package and service to be in the request to do the right thing. - -### Deploying to Kubernetes - -`grpc_example.yaml` - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - acmeProvider: - authority: none - requestPolicy: - insecure: - action: Route ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py -spec: - hostname: "*" - grpc: True - prefix: /helloworld.Greeter/ - rewrite: /helloworld.Greeter/ - service: grpc-example - ---- -apiVersion: v1 -kind: Service -metadata: - labels: - service: grpc-example - name: grpc-example -spec: - type: ClusterIP - ports: - - name: grpc-greet - port: 80 - targetPort: grpc-api - selector: - service: grpc-example ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: grpc-example -spec: - replicas: 1 - selector: - matchLabels: - service: grpc-example - template: - metadata: - labels: - service: grpc-example - spec: - containers: - - name: grpc-example - image: /grpc_example - ports: - - name: grpc-api - containerPort: 50051 - restartPolicy: Always -``` - -The Host is declared here because we are using gRPC without TLS. Since $productName$ terminates TLS by default, in the Host we add a `requestPolicy` which allows insecure connections. After adding the $productName$ mapping to the service, the rest of the Kubernetes deployment YAML file is pretty straightforward. We need to identify the container image to use, expose the `containerPort` to listen on the same port the Docker container is listening on, and map the service port (80) to the container port (50051). - -> For more information on insecure routing, please refer to the [`Host` documentation](../../topics/running/host-crd#secure-and-insecure-requests). - - -Once you have the YAML file and the correct Docker registry, deploy it to your cluster with `kubectl`. - -``` -$ kubectl apply -f grpc_example.yaml -``` - -### Testing the Deployment - -Make sure to test your Kubernetes deployment before making more advanced changes (like adding TLS). To test any service with $productName$, we will need the hostname of the running $productName$ service which you can get with: - -``` -$ kubectl get service ambassador -o wide -``` -Which should return something similar to: - -``` -NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE -ambassador 10.11.12.13 35.36.37.38 80:31656/TCP 1m -``` -where `EXTERNAL-IP` is the `$AMBASSADORHOST` and 80 is the `$PORT`. - -You will need to open the `greeter_client.py` and change `localhost:50051` to `$AMBASSADORHOST:$PORT` - -```diff -- with grpc.insecure_channel('localhost:50051') as channel: -+ with grpc.insecure_channel(‘$AMBASSADORHOST:$PORT’) as channel: - stub = helloworld_pb2_grpc.GreeterStub(channel) - response = stub.SayHello(helloworld_pb2.HelloRequest(name='you')) - print("Greeter client received: " + response.message) -``` - -After making that change, simply run the client again and you will see the gRPC service in your cluster respond: - -``` -$ python greeter_client.py -Greeter client received: Hello, you! -``` - -### gRPC and TLS - -There is some extra configuration required to connect to a gRPC service through $productName$ over an encrypted channel. Currently, the gRPC call is being sent over cleartext to $productName$ which proxies it to the gRPC application. - -![](../images/grpc-tls.png) - -If you want to add TLS encryption to your gRPC calls, first you need to tell $productName$ to add [ALPN protocols](../../topics/running/tls) which are required by HTTP/2 to do TLS. - -For example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls -spec: - hosts: - - "*" - secret: ambassador-cert - alpn_protocols: h2 -``` - -Next, you need to change the client code slightly and tell it to open a secure RPC channel with $productName$. - -```diff -- with grpc.insecure_channel(‘$AMBASSADORHOST:$PORT’) as channel: -+ with grpc.secure_channel(‘$AMBASSADORHOST:$PORT’, grpc.ssl_channel_credentials()) as channel: - stub = helloworld_pb2_grpc.GreeterStub(channel) - response = stub.SayHello(helloworld_pb2.HelloRequest(name='you')) - print("Greeter client received: " + response.message) -``` - -`grpc.ssl_channel_credentials(root_certificates=None, private_key=None, certificate_chain=None)`returns the root certificate that will be used to validate the certificate and public key sent by $productName$. The default values of `None` tells the gRPC runtime to grab the root certificate from the default location packaged with gRPC and ignore the private key and certificate chain fields. Generally, passing no arguments to the method that requests credentials gives the same behavior. Refer to the languages [API Reference](https://grpc.io/docs/) if this is not the case. - -$productName$ is now terminating TLS from the gRPC client and proxying the call to the application over cleartext. - -![](../images/gRPC-TLS-Ambassador.png) - -If you want to configure authentication in another language, [gRPC provides examples](https://grpc.io/docs/guides/auth.html) with proper syntax for other languages. - -#### Working with Host headers that include the port - -Some gRPC clients automatically include the port in the Host header. This is a problem when using TLS because the certificate will match `myurl.com` but the Host header will be `myurl.com:443`, resulting in the error `rpc error: code = Unimplemented desc =`. If you run into this issue, there are two ways to solve it depending on your use case, both using the Module resource. - -The first is to set the `strip_matching_host_port` [property](../../topics/running/ambassador#strip-matching-host-port) to `true`. However, this only works if the port in the header matches the port that Envoy listens on (8443 by default). In the default installation of $productName$, the public port is 443, which then maps internally to 8443, so this only works for custom installations where the public service port matches the port in the Listener resource. - -The second solution is to use the following [Lua script](../../topics/running/ambassador#lua-scripts), which always strips the port: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador - namespace: ambassador -spec: - config: - lua_scripts: | - function envoy_on_request(request_handle) - local authority = request_handle:headers():get(":authority") - if(string.find(authority, ":") ~= nil) - then - local authority_index = string.find(authority, ":") - local stripped_authority = string.sub(authority, 1, authority_index - 1) - request_handle:headers():replace(":authority", stripped_authority) - end - end -``` - -#### Originating TLS with gRPC service - -![](../images/gRPC-TLS-Originate.png) - -$productName$ can originate TLS with your gRPC service so the entire RPC channel is encrypted. To configure this, first get some TLS certificates and configure the server to open a secure channel with them. Using self-signed certs this can be done with OpenSSL and adding a couple of lines to the server code. - -```diff -def serve(): - server = grpc.server(futures.ThreadPoolExecutor(max_workers=10)) -+ with open('certs/server.key', 'rb') as f: -+ private_key = f.read() -+ with open('certs/server.crt', 'rb') as f: -+ cert_chain = f.read() -+ server_creds = grpc.ssl_server_credentials( ( (private_key, cert_chain), ) ) - helloworld_pb2_grpc.add_GreeterServicer_to_server(Greeter(), server) -- server.add_insecure_port('[::]:50052') -+ server.add_secure_port('[::]:50052', server_creds) - server.start() -``` - -Rebuild your docker container **making sure the certificates are included** and follow the same steps of testing and deploying to Kubernetes. You will need to make a small change to the client code to test locally. - -```diff -- with grpc.insecure_channel(‘localhost:$PORT’) as channel: -+ with grpc.secure_channel(‘localhost:$PORT’, grpc.ssl_channel_credentials(open('certs/server.crt', 'rb').read())) as channel: - stub = helloworld_pb2_grpc.GreeterStub(channel) - response = stub.SayHello(helloworld_pb2.HelloRequest(name='you')) - print("Greeter client received: " + response.message) -``` - -Once deployed we will need to tell $productName$ to originate TLS to the application. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py-tls -spec: - hostname: "*" - grpc: True - tls: upstream - prefix: /hello.Greeter/ - rewrite: /hello.Greeter/ - service: https://grpc-py - ---- -apiVersion: v1 -kind: Service -metadata: - labels: - service: grpc-py - name: grpc-py -spec: - type: ClusterIP - ports: - - name: grpc-greet - port: 443 - targetPort: grpc-api - selector: - service: grpc-py -``` - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: upstream -spec: - alpn_protocols: h2 - secret: ambassador-cert -``` - -We need to tell $productName$ to route to the `service:` over https and have the service listen on `443`. We also need to tell $productName$ to use ALPN protocols when originating TLS with the application, the same way we did with TLS termination. This is done by setting `alpn_protocols: ["h2"]` in a `TLSContext` telling the service to use that tls-context in the mapping by setting `tls: upstream`. - -Refer to the [TLS document](../../topics/running/tls/origination#advanced-configuration-using-a-tlscontext) for more information on TLS origination. - -### gRPC headers - -gRPC services use [HTTP/2 headers](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md). This means that some header-based routing rules will need to be rewritten to support HTTP/2 headers. For example, `host: subdomain.host.com` needs to be rewritten using the `headers: ` attribute with the `:authority` header: - -``` -headers: - :authority: subdomain.host.com -``` - -## Note - -### Ingress controllers - -Some [Kubernetes ingress controllers](https://kubernetes.io/docs/concepts/services-networking/ingress/) do not support HTTP/2 fully. As a result, if you are running $productName$ with an ingress controller in front, you may find that gRPC requests fail even with correct $productName$ configuration. - -A simple way around this is to use $productName$ with a `LoadBalancer` service, rather than an Ingress controller. You can also consider using [$productName$ as your Ingress Controller](../../topics/running/ingress-controller). - -### Mappings with hosts - -As with any `Mapping`, your gRPC service's `Mapping` may include a `host`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py -spec: - hostname: "*" - grpc: true - prefix: /helloworld.Greeter/ - rewrite: /helloworld.Greeter/ - service: grpc-example - host: api.example.com -``` - -Some gRPC client libraries produce requests where the `host` or `:authority` header includes the port number. For example, a request to the above service might include `host: api.example.com:443` instead of just `host: api.example.com`. To avoid having $productName$ return a 404 (not found) response to these requests due to the mismatched host, you may want to set `strip_matching_host_port` in the [Ambassador module](../../topics/running/ambassador#strip-matching-host-port). - -Alternately, you may find it cleaner to make sure your gRPC client does not include the port in the `host` header. Here is an example using gRPC/Go. - -```go -hostname := "api.example.com" -port := "443" -config := &tls.Config{ServerName: hostname} -creds := credentials.NewTLS(config) -opts := []grpc.DialOption{ - grpc.WithTransportCredentials(creds), -// ... -} -conn, err := grpc.Dial(hostname+":"+port, opts...) -// ... -``` - -## gRPC-Web - -$productName$ also supports the [gRPC-Web](../../topics/running/ambassador#grpc) protocol for browser-based gRPC applications. diff --git a/content/en/docs/3.5/howtos/http3-aks.md b/content/en/docs/3.5/howtos/http3-aks.md deleted file mode 100644 index 2f9be012..00000000 --- a/content/en/docs/3.5/howtos/http3-aks.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "$productName$ - HTTP/3 support for Azure Kubernetes Service (AKS)" -description: "How to configure HTTP/3 support for Azure Kubernetes Service (AKS). This guide shows how to setup the LoadBalancer service for AKS to support both TCP and UDP communications." ---- - -# Azure Kubernetes Service Engine HTTP/3 configuration - -This guide shows how to setup HTTP/3 support for Azure Kubernetes Service (AKS). The instructions provided in this page are a continuation of the [HTTP/3 in $productName$](../../topics/running/http3) documentation. - -## Configuring an external load balancer for AKS - -To configure an external load balancer for AKS, you need to: - -1. Reserve a public static IP address. -2. Create two `LoadBalancer` services, one for TCP and one for UDP. -3. Assign the public static IP address to the `loadBalancerIP` field. - -An example of the two load balancer services described above looks as follows: - -```yaml -# selectors and labels removed for clarity -apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$ - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - --- - apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$-udp - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http3 - port: 443 # Default support for HTTP/3 requires you to use 443 for the external client-facing port. - targetPort: 8443 - protocol: UDP - -``` - -In the above example, AKS generates two `LoadBalancer` services, one for UDP and the other for TCP. - - -You should verify that the Managed Identity or Serivce Principal has permissions to assign the IP address to the newly created LoadBalancer services. Refer to the Azure Docs - Managed Identity for more information. - diff --git a/content/en/docs/3.5/howtos/http3-eks.md b/content/en/docs/3.5/howtos/http3-eks.md deleted file mode 100644 index d09a1af5..00000000 --- a/content/en/docs/3.5/howtos/http3-eks.md +++ /dev/null @@ -1,252 +0,0 @@ ---- -title: "HTTP/3 with Amazon Elastic Kubernetes Service (EKS) | $productName$" -description: "How to configure HTTP/3 support for Amazon Elastic Kubernetes Service (EKS). This guide shows how to setup the LoadBalancer service for EKS to support both TCP and UDP communications." ---- - -# Amazon Elastic Kubernetes Service HTTP/3 configuration - -This guide shows how to setup HTTP/3 support for Amazon Elastic Kubernetes Service (EKS) The instructions provided in this page are a continuation of the [HTTP/3 in $productName$](../../topics/running/http3) documentation. - -## Create a network load balancer (NLB) - - The virtual private cloud (VPC) for your load balancer needs one public subnet in each availability zone where you have targets. - - ```shell - SUBNET_IDS=( ) - - aws elbv2 create-load-balancer \ - --name ${CLUSTER_NAME}-nlb \ - --type network \ - --subnets ${SUBNET_IDS} - ``` - -## Create a NodePort service - -Now create a `NodePort` service for $productName$ installation with two entries. Use `port: 443` to include support for both TCP and UDP traffic. - ```yaml - # Selectors and labels removed for clarity. - apiVersion: v1 - kind: Service - metadata: - name: $productDeploymentName$-http3 - namespace: $productNamespace$ - spec: - type: NodePort - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - nodePort: 30080 - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - nodePort: 30443 - - name: http3 - port: 443 - targetPort: 8443 - protocol: UDP - nodePort: 30443 - ``` - -## Create target groups - -Run the following command with the variables for your VPC ID and cluster name: - - ```shell - VPC_ID= - CLUSTER_NAME= - - aws elbv2 create-target-group --name ${CLUSTER_NAME}-tcp-tg \ - --protocol TCP --port 30080 --vpc-id ${VPC_ID} \ - --health-check-protocol TCP \ - --health-check-port 30080 \ - --target-type instance - - aws elbv2 create-target-group --name ${CLUSTER_NAME}-tcp-udp-tg \ - --protocol TCP_UDP --port 30443 --vpc-id ${VPC_ID} \ - --health-check-protocol TCP \ - --health-check-port 30443 \ - --target-type instance - ``` - -## Register your instances - -Next, register your cluster's instance with the the instance IDs and Amazon Resource Names (ARN). - -To get your cluster's instance IDs, enter the following command: - ```shell - aws ec2 describe-instances \ - --filters Name=tag:eks:cluster-name,Values=${CLUSTER_NAME} \ - --output text - --query 'Reservations[*].Instances[*].InstanceId' \ - ``` - -To get your ARNs, enter the following command: - ```shell - TCP_TG_NAME=${CLUSTER_NAME}-tcp-tg-name - TCP_UDP_TG_NAME=${CLUSTER_NAME}-tcp-udp-tg-name - - aws elbv2 describe-target-groups \ - --query 'TargetGroups[?TargetGroupName==`'${TCP_TG_NAME}'`].TargetGroupArn' \ - --output text - aws elbv2 describe-target-groups \ - --query 'TargetGroups[?TargetGroupName==`'${TCP_UDP_TG_NAME}'`]. TargetGroupArn' \ - --output text - ``` - -Register the instances with the target groups and load balancer using the instance IDs and ARNs you retrieved. - ```shell - INSTANCE_IDS=( ) - REGION= - TG_NAME= - TCP_TG_ARN=arn:aws:elasticloadbalancing:${REGION}:079.....:targetgroup/${TG_NAME}/... - TCP_UDP_TG_ARN=arn:aws:elasticloadbalancing:${REGION}:079.....:targetgroup/${TG_NAME}/... - - aws elbv2 register-targets --target-group-arn ${TCP_TG_ARN} --targets ${INSTANCE_IDS} - aws elbv2 register-targets --target-group-arn ${TCP_UDP_TG_ARN} --targets ${INSTANCE_IDS} - ``` - -## Create listeners in AWS. - -Register your cluster's instance with the instance IDs and ARNs. - -To get the load balancer's ARN, enter the following command: - ```shell - aws elbv2 describe-load-balancers --name ${CLUSTER_NAME}-nlb \ - --query 'LoadBalancers[0].LoadBalancerArn' \ - --output text - ``` - -Create a TCP listener on port 80 that that forwards to the TargetGroup {TCP_TG_ARN}. - ```shell - aws elbv2 create-listener --load-balancer-arn ${LB_ARN} \ - --protocol TCP --port 80 \ - --default-actions Type=forward,TargetGroupArn=${TCP_TG_ARN} - ``` - - Create a TCP_UDP listener on port 443 that forwards to the TargetGroup {TCP_UDP_TG_ARN}. - ```shell - aws elbv2 create-listener --load-balancer-arn ${LB_ARN} \ - --protocol TCP_UDP --port 443 \ - --default-actions Type=forward,TargetGroupArn=${TCP_UDP_TG_ARN} - ``` - -## Update the security groups - -Now you need to update your security groups to receive traffic. This security group covers all node groups attached to the EKS cluster: - ```shell - aws eks describe-cluster --name ${CLUSTER_NAME} | grep clusterSecurityGroupId - ``` - -Now authorize the cluster security group to allow internet traffic: - ```shell - for x in ${CLUSTER_SG}; do \ - aws ec2 authorize-security-group-ingress --group-id $$x --protocol tcp --port 30080 --cidr 0.0.0.0/0; \ - aws ec2 authorize-security-group-ingress --group-id $$x --protocol tcp --port 30443 --cidr 0.0.0.0/0; \ - aws ec2 authorize-security-group-ingress --group-id $$x --protocol udp --port 30443 --cidr 0.0.0.0/0; \ - done - ``` - -## Get the DNS name for the load balancers - -Enter the following command to get the DNS name for your load balancers and create a CNAME record at your domain provider: - ```shell - aws elbv2 describe-load-balancers --name ${CLUSTER_NAME}-nlb \ - --query 'LoadBalancers[0].DNSName' \ - --output text - ``` - -## Create Listener resources - -Now you need to create the `Listener` resources for $productName$. The first `Listener` in the example below handles traffic for HTTP/1.1 and HTTP/2, while the second `Listener` handles all HTTP/3 traffic. - - ```yaml - kubectl apply -f - < - acmeProvider: - authority: none - tlsSecret: - name: tls-cert # The QUIC network protocol requires TLS with a valid certificate - tls: - min_tls_version: v1.3 - max_tls_version: v1.3 - alpn_protocols: h2,http/1.1 - EOF - ``` - -## Apply the quote service and a Mapping to test the HTTP/3 configuration. - -Finally, apply the quote service to a $productName$ `Mapping`. - - ```shell - kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$version$/quickstart/qotm.yaml - kubectl apply -f - </backend/ - ``` -Your domain now shows that it is being served with HTTP/3. diff --git a/content/en/docs/3.5/howtos/http3-gke.md b/content/en/docs/3.5/howtos/http3-gke.md deleted file mode 100644 index 677e89e3..00000000 --- a/content/en/docs/3.5/howtos/http3-gke.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: "$productName$ - HTTP/3 support for Google Kubernetes Engine (GKE)" -description: "How to configure HTTP/3 support for Google Kubernetes Engine (GKE). This guide shows how to setup the LoadBalancer service for GKE to support both TCP and UDP communications." ---- - -# Google Kubernetes Service Engine HTTP/3 configuration - -This guide shows how to setup HTTP/3 support for Google Kubernetes Engine (GKE). The instructions provided in this page are a continuation of the [HTTP/3 in $productName$](../../topics/running/http3) documentation. - -## Configuring an external load balancer for GKE - -Currently, GKE only supports adding feature flags to `alpha` clusters, and doesn't support the creation of mixed protocol services of type `LoadBalancer`. To configure an external load balancer for GKE, you need to: - -1. Reserve a public static IP address. -2. Create two `LoadBalancer` services, one for TCP and one for UDP. -3. Assign the public static IP address to the `loadBalancerIP` field. - -An example of the two load balancer services described above looks as follows: - -```yaml -# selectors and labels removed for clarity -apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$ - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - --- - apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$-udp - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http3 - port: 443 # Default support for HTTP/3 requires you to use 443 for the external client-facing port. - targetPort: 8443 - protocol: UDP - -``` - -In the above example, GKE generates two `LoadBalancer` services, one for UDP and the other for TCP. diff --git a/content/en/docs/3.5/howtos/index.md b/content/en/docs/3.5/howtos/index.md deleted file mode 100644 index f16cdd46..00000000 --- a/content/en/docs/3.5/howtos/index.md +++ /dev/null @@ -1,25 +0,0 @@ -# "How-to" guides - -These guides are designed to help users quickly accomplish common tasks. The guides assume a certain level of understanding of $productName$. Many of these guides are contributed by third parties; we welcome contributions via Pull Request at https://github.com/emissary-ingress/emissary. - -* Integrating with Service Mesh. $productName$ natively integrates with many service meshes. - * [HashiCorp Consul](consul) - * [Istio](istio) - * [Linkerd](linkerd2) -* Distributed tracing. $productName$ natively supports a number of distributed tracing systems to enable developers to visualize request flow in microservice and service-oriented architectures. - * [Datadog](tracing-datadog) - * [Zipkin](tracing-zipkin) -* Monitoring. $productName$ integrates with a number of different monitoring/metrics providers. - * [Prometheus](prometheus) -* [Developing Custom Filters](filter-dev-guide) -* Frameworks and Protocols. $productName$ supports a wide range of protocols and cloud-native frameworks. - * [gRPC](grpc) - * [Knative Serverless Framework](knative) - * [WebSockets](websockets) -* Security. $productName$ supports a number of strategies for securing Kubernetes services. - * [Protecting the Diagnostics Interface](protecting-diag-access) - * [HTTPS and TLS termination](tls-termination) - * [Certificate Manager](cert-manager) can be used to automatically obtain and renew TLS certificates; $AESproductName$ natively integrates this functionality. - * [Client Certificate Validation](client-cert-validation) - * [Basic Authentication](basic-auth) is a tutorial on how to use the external authentication API to code your own authentication service. - * [Basic Rate Limiting](rate-limiting-tutorial) diff --git a/content/en/docs/3.5/howtos/istio.md b/content/en/docs/3.5/howtos/istio.md deleted file mode 100644 index e26571b7..00000000 --- a/content/en/docs/3.5/howtos/istio.md +++ /dev/null @@ -1,445 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Istio integration - -$productName$ and Istio: Edge Proxy and Service Mesh together in one. $productName$ is deployed at the edge of your network and routes incoming traffic to your internal services (aka "north-south" traffic). [Istio](https://istio.io/) is a service mesh for microservices, and is designed to add application-level Layer (L7) observability, routing, and resilience to service-to-service traffic (aka "east-west" traffic). Both Istio and $productName$ are built using [Envoy](https://www.envoyproxy.io). - -$productName$ and Istio can be deployed together on Kubernetes. In this configuration, $productName$ manages -traditional edge functions such as authentication, TLS termination, and edge routing. Istio mediates communication -from $productName$ to services, and communication between services. - -This allows the operator to have the best of both worlds: a high performance, modern edge service ($productName$) combined with a state-of-the-art service mesh (Istio). While Istio has introduced a [Gateway](https://istio.io/latest/docs/tasks/traffic-management/ingress/ingress-control/) abstraction, $productName$ still has a much broader feature set for edge routing than Istio. For more on this topic, see our blog post on [API Gateway vs Service Mesh](https://blog.getambassador.io/api-gateway-vs-service-mesh-104c01fa4784). - -This guide explains how to take advantage of both $productName$ and Istio to have complete control and observability over how requests are made in your cluster: - -- [Install Istio](#install-istio) and configure auto-injection -- [Install $productName$ with Istio integration](#install-edge) -- [Configure an mTLS `TLSContext`](#configure-an-mtls-tlscontext) -- [Route to services using mTLS](#route-to-services-using-mtls) - -If desired, you may also - -- [Enable strict mTLS](#enable-strict-mtls) -- [Configure Prometheus metrics collection](#configure-prometheus-metrics-collection) -- [Configure Istio distributed tracing](#configure-istio-distributed-tracing) - -To follow this guide, you need: - -- A Kubernetes cluster version 1.15 and above -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- Istio version 1.10 or higher - -## Install Istio - -Start by [installing Istio](https://istio.io/docs/setup/getting-started/). Any supported installation method for -Istio will work for use with $productName$. - -### Configure Istio Auto-Injection - -Istio functions by supplying a sidecar container running Envoy with every service in the mesh (including -$productName$). The sidecar is what enforces Istio policies for traffic to and from the service, notably -including mTLS encryption and certificate handling. As such, it is very important that the sidecar be -correctly supplied for every service in the mesh! - -While it is possible to manage sidecars by hand, it is far easier to allow Istio to automatically inject -the sidecar as necessary. To do this, set the `istio-injection` label on each Kubernetes Namespace for -which you want auto-injection: - -```yaml -kubectl label namespace $namespace istio-injection=enabled --overwrite -``` - - - The following example uses the `istio-injection` label to arrange for auto-injection in the - `$productNamespace$` Namespace below. You can manage sidecar injection by hand if you wish; what - is critical is that every service that participates in the Istio mesh have the Istio - sidecar. - - -## Install $productName$ with Istio Integration - -Properly integrating $productName$ with Istio provides support for: - -* [Mutual TLS (mTLS)](../../topics/running/tls/mtls/), with certificates managed by Istio, to allow end-to-end encryption -for east-west traffic; -* Automatic generation of Prometheus metrics for services; and -* Istio distributed tracing for end-to-end observability. - -The simplest way to enable everything is to install $productName$ using [Helm](https://helm.sh), though -you can use manual installation with YAML if you wish. - -### Installation with Helm (Recommended) - -To install with Helm, write the following YAML to a file called `istio-integration.yaml`: - -```yaml -# Listeners are required in $productName$ 2.0. -# This will create the two default Listeners for HTTP on port 8080 and HTTPS on port 8443. -createDefaultListeners: true - -# These are annotations that will be added to the $productName$ pods. -podAnnotations: - # These first two annotations tell Istio not to try to do port management for the - # $productName$ pod itself. Though these annotations are placed on the $productName$ - # pods, they are interpreted by Istio. - traffic.sidecar.istio.io/includeInboundPorts: "" # do not intercept any inbound ports - traffic.sidecar.istio.io/includeOutboundIPRanges: "" # do not intercept any outbound traffic - - # We use proxy.istio.io/config to tell the Istio proxy to write newly-generated mTLS certificates - # into /etc/istio-certs, which will be mounted below. Though this annotation is placed on the - # $productName$ pods, it is interpreted by Istio. - proxy.istio.io/config: | - proxyMetadata: - OUTPUT_CERTS: /etc/istio-certs - - # We use sidecar.istio.io/userVolumeMount to tell the Istio sidecars to mount the istio-certs - # volume at /etc/istio-certs, allowing the sidecars to see the generated certificates. Though - # this annotation is placed on the $productName$ pods, it is interpreted by Istio. - sidecar.istio.io/userVolumeMount: '[{"name": "istio-certs", "mountPath": "/etc/istio-certs"}]' - -# We define a single storage volume called "istio-certs". It starts out empty, and Istio -# uses it to communicate mTLS certs between the Istio proxy and the Istio sidecars (see the -# annotations above). -volumes: - - emptyDir: - medium: Memory - name: istio-certs - -# We also tell $productName$ to mount the "istio-certs" volume at /etc/istio-certs in the -# $productName$ pod. This gives $productName$ access to the mTLS certificates, too. -volumeMounts: - - name: istio-certs - mountPath: /etc/istio-certs/ - readOnly: true - -# Finally, we need to set some environment variables for $productName$. -env: - # AMBASSADOR_ISTIO_SECRET_DIR tells $productName$ to look for Istio mTLS certs, and to - # make them available as a secret named "istio-certs". - AMBASSADOR_ISTIO_SECRET_DIR: "/etc/istio-certs" - - # AMBASSADOR_ENVOY_BASE_ID is set to prevent collisions with the Istio sidecar's Envoy, - # which runs with base-id 0. - AMBASSADOR_ENVOY_BASE_ID: "1" -``` - -To install $productName$ with Helm, use these values to configure Istio integration: - -1. Create the `$productNamespace$` Namespace: - - ```yaml - kubectl create namespace $productNamespace$ - ``` - -2. Enable Istio auto-injection for it: - - ```yaml - kubectl label namespace $productNamespace$ istio-injection=enabled --overwrite - ``` - -3. Make sure the Helm repo is configured: - - ```bash - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - -4. Use Helm to install $productName$ in $productNamespace$: - - ```bash - helm install $productHelmName$ --namespace $productNamespace$ -f istio-integration.yaml datawire/$productHelmName$ && \ - kubectl -n $productNamespace$ wait --for condition=available --timeout=90s deploy -lapp.kubernetes.io/instance=$productDeploymentName$ - ``` - -### Installation Using YAML - -To install using YAML files, you need to manually incorporate the contents of the `istio-integration.yaml` -file shown above into your deployment YAML: - -* `pod-annotations` should be configured as Kubernetes `annotations` on the $productName$ Pods; -* `volumes`, `volumeMounts`, and `env` contents should be included in the $productDeploymentName$ Deployment; and -* you must also label the $productNamespace$ Namespace for auto-injection as described above. - -### Configuring an Existing Installation - -If you have already installed $productName$ and want to enable Istio: - -1. Install Istio. -2. Label the $productNamespace$ namespace for Istio auto-injection, as above. -2. Edit the $productName$ Deployments to contain the `annotations`, `volumes`, `volumeMounts`, and `env` elements - shown above. - * If you installed with Helm, you can use `helm upgrade` with `-f istio-integration.yaml` to modify the - installation for you. -3. Restart the $productName$ pods. - -## Configure an mTLS `TLSContext` - -After configuring $productName$ for Istio integration, the Istio mTLS certificates are available within -$productName$: - -- Both the `istio-proxy` sidecar and $productName$ mount the `istio-certs` volume at `/etc/istio-certs`. -- The `istio-proxy` sidecar saves the mTLS certificates into `/etc/istio-certs` (per the `OUTPUT_CERTS` - environment variable). -- $productName$ reads the mTLS certificates from `/etc/istio-certs` (per the `AMBASSADOR_ISTIO_SECRET_DIR` - environment variable) and creates a Secret named `istio-certs`. - - - At present, the Secret name istio-certs cannot be changed. - - -To make use of the `istio-certs` Secret, create a `TLSContext` referencing it: - - ```shell - $ kubectl apply -f - < - You must either explicitly specify port 80 in your 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 - <This guide applies to $OSSproductName$. It will not work correctly -on $AESproductName$. - -$productName$ can validate incoming requests before routing them to a backing service. In this tutorial, we'll configure $productName$ to use a simple third party rate limit service. (If you don't want to implement your own rate limiting service, $AESproductName$ integrates a [powerful, flexible rate limiting service](/docs/edge-stack/latest/topics/using/rate-limits/rate-limits/).) - -## Before you get started - -This tutorial assumes you have already followed the $productName$ [Installation](../../topics/install/) and [Quickstart Tutorial](../../tutorials/quickstart-demo) guides. If you haven't done that already, you should do so now. - -Once completed, you'll have a Kubernetes cluster running $productName$ and the Quote service. Let's walk through adding rate limiting to this setup. - -## 1. Deploy the rate limit service - -$productName$ delegates the actual rate limit logic to a third party service. We've written a [simple rate limit service](https://github.com/emissary-ingress/ratelimit-example) that: - -- listens for requests on port 5000; -- handles gRPC `shouldRateLimit` requests; -- allows requests with the `x-emissary-test-allow: "true"` header; and -- marks all other requests as `OVER_LIMIT`; - -Here's the YAML we'll start with: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: RateLimitService -metadata: - name: ratelimit - namespace: default -spec: - service: "ratelimit-example.default:5000" - protocol_version: v3 - domain: emissary - failure_mode_deny: true ---- -apiVersion: v1 -kind: Service -metadata: - name: ratelimit-example -spec: - selector: - app: ratelimit-example - ports: - - name: http - port: 5000 - targetPort: http ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: ratelimit-example -spec: - replicas: 1 - selector: - matchLabels: - app: ratelimit-example - template: - metadata: - labels: - app: ratelimit-example - spec: - containers: - - name: ratelimit-example - image: docker.io/emissaryingress/ratelimit-example:v3 - imagePullPolicy: Always - ports: - - name: http - containerPort: 5000 - resources: - limits: - memory: "64Mi" - cpu: "100m" -``` - -Once this configuration is applied Kubernetes will startup the example ratelimit service and $productName$ will be configured to use the rate limit service. The `RateLimitService` configuration tells $productName$ to: - -- Send `ShouldRateLimit` check request to `ratelimit-example.default:5000` -- Configure Envoy to talk with the example ratelimit service using transport protocol `v3` (*only supported version*) -- Set the labels `domain` to `emissary` (*labels discussed below*) - -If $productName$ cannot contact the rate limit service, it can either fail open or closed. The default is to fail open but in the example `RateLimitService` above we toggled it via the `failure_mode_deny: true` setting. - -## 2. Configure $productName$ Mappings - -$productName$ only validates requests on `Mapping`s which set labels to use for rate limiting, so you'll need to apply `labels` to your `Mapping`s to enable rate limiting. For more information -on the labelling process, see the [Rate Limits configuration documentation](../../topics/using/rate-limits/). - - - These labels require Mapping resources with apiVersion getambassador.io/v2 or newer — if you're updating an old installation, check the - apiVersion! - - -Labels are added to a `Mapping` using the `labels` field and `domain` configured in the `RateLimitService`. For example: - -```yaml -labels: - emissary: - - request_label_group: - - x-emissary-test-allow: - request_headers: - key: "x-emissary-test-allow" - header_name: "x-emissary-test-allow" -``` - -If we were to apply it the `Mapping` definition for the `quote-backend` service outlined in the quick-start then it would look like this: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: "*" - prefix: /backend/ - service: quote - labels: - emissary: - - request_label_group: - - x-emissary-test-allow: - request_headers: - key: "x-emissary-test-allow" - header_name: "x-emissary-test-allow" -``` - -Note that the `key` could be anything you like, but our example rate limiting service expects it to match the name of the header. Also note that since our `RateLimitService` expects to use labels in the -`emissary` domain, our `Mapping` must match. - -## 2. Test rate limiting - -If we `curl` to a rate-limited URL: - -```shell -curl -i -H "x-emissary-test-allow: probably" http://$LB_ENDPOINT/backend/ -``` - -We get a `429` status code, since we are being rate limited. - -```shell -HTTP/1.1 429 Too Many Requests -content-type: text/html; charset=utf-8 -content-length: 0 -``` - -If we set the correct header value to the service request, we will get a quote successfully: - -```shell -$ curl -i -H "x-emissary-test-allow: true" http://$LB_ENDPOINT/backend/ - -TCP_NODELAY set -* Connected to 35.196.173.175 (35.196.173.175) port 80 (#0) -> GET /backed HTTP/1.1 -> Host: 35.196.173.175 -> User-Agent: curl/7.54.0 -> Accept: */* -> -< HTTP/1.1 200 OK -< content-type: application/json -< date: Thu, 23 May 2019 15:25:06 GMT -< content-length: 172 -< x-envoy-upstream-service-time: 0 -< server: envoy -< -{ - "server": "humble-blueberry-o2v493st", - "quote": "Nihilism gambles with lives, happiness, and even destiny itself!", - "time": "2019-05-23T15:25:06.544417902Z" -* Connection #0 to host 54.165.128.189 left intact -} -``` - -## More - -For more details about configuring the external rate limit service, read the [rate limit documentation](../../topics/using/rate-limits/). diff --git a/content/en/docs/3.5/howtos/route.md b/content/en/docs/3.5/howtos/route.md deleted file mode 100644 index 6a399ec5..00000000 --- a/content/en/docs/3.5/howtos/route.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -description: "$productName$ uses the Mapping resource to map a resource, like a URL prefix, to a Kubernetes service or web service." ---- - -import Alert from '@material-ui/lab/Alert'; - -# Get traffic from the edge - -
-

Contents

- -* [Examples](#examples) -* [Applying a Mapping Resource](#applying-a-mapping-resource) -* [Resources](#resources) -* [Services](#services) -* [Extending Mappings](#extending-mappings) -* [Best Practices](#best-practices) -* [What's next?](#img-classos-logo-srcimageslogopng-whats-next) - -
- -The core $productName$ resource used to manage cluster ingress is the `Mapping` resource. - -**A `Mapping` resource routes a URL path (or prefix) to a service (either a Kubernetes service or other web service).** - - - Remember that Listener and Host resources are  - required for a functioning $productName$ installation that can route traffic!
- Learn more about Listener.
- Learn more about Host. - - -## Examples - -This `Mapping` would route requests to `https:///webapp/` to the `webapp-svc` Service. **This is not a -complete example on its own; see below.** - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: webapp-mapping -spec: - prefix: /webapp/ - service: webapp-svc -``` - -| Name | Type | Description | -| :--- | :--- | :--- | -| `metadata.name` | String | Identifies the Mapping. | -| `spec.prefix` | String | The URL prefix identifying your resource. [See below](#resources) on how $productName$ handles resources. | -| `spec.service` | String | The service handling the resource. If a Kubernetes service, it must include the namespace (in the format `service.namespace`) if the service is in a different namespace than $productName$. [See below](#services) on service name formatting.| - -Here's another example using a web service that maps requests to `/httpbin/` to `http://httpbin.org` (again, **this is not a -complete example on its own; see below**): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin-mapping -spec: - prefix: /httpbin/ - service: http://httpbin.org - hostname: '*' -``` - -### Complete example configuration - -For demonstration purposes, here's a possible way of combining a `Listener`, a `Host`, and both `Mapping`s above that is complete and functional: - -- it will accept HTTP or HTTPS on port 8443; -- $productName$ is terminating TLS; -- HTTPS to `foo.example.com` will be routed as above; -- HTTP to `foo.example.com` will be redirected to HTTPS; -- HTTP or HTTPS to other hostnames will be rejected; and -- the associations between the `Listener`, the `Host`, and the `Mappings` use Kubernetes `label`s. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: foo-example-secret -data: - tls.crt: -certificate PEM- - tls.key: -secret key PEM- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-8443 -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: - selector: - matchLabels: - exampleName: basic-https ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host - labels: - exampleName: basic-https -spec: - hostname: "foo.example.com" - tlsSecret: - name: foo-example-secret - selector: - matchLabels: - exampleName: basic-https ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: webapp-mapping - labels: - exampleName: basic-https -spec: - prefix: /webapp/ - service: webapp-svc - hostname: 'foo.example.com' ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin-mapping - labels: - exampleName: basic-https -spec: - prefix: /httpbin/ - service: http://httpbin.org - hostname: 'foo.example.com' - -``` - -Note the addition of `label`s and `selector`s to explicitly specify which resources should associate in this example. - - - Learn more about Listener.
- Learn more about Host. - - -## Applying a Mapping resource - -A Mapping resource can be managed using the same workflow as any other Kubernetes resources (like a Service or Deployment). For example, if the above Mapping is saved into a file called `httpbin-mapping.yaml`, the following command will apply the configuration directly to $productName$: - -``` -kubectl apply -f httpbin-mapping.yaml -``` - -For production use, best practice is to store the file in a version control system and apply the changes with a continuous deployment pipeline. The Ambassador Operating Model provides more detail. - -## Resources - -To $productName$, a resource is a group of one or more URLs that all share a common prefix in the URL path. For example, these URLs all share the `/resource1/` path prefix, so `/resource1/` can be considered a single resource: - -* `https://ambassador.example.com/resource1/foo` -* `https://ambassador.example.com/resource1/bar` -* `https://ambassador.example.com/resource1/baz/zing` - -On the other hand, these URLs share only the prefix `/` -- you _could_ tell $productName$ to treat them as a single resource, but it's probably not terribly useful. - -* `https://ambassador.example.com/resource1/foo` -* `https://ambassador.example.com/resource2/bar` -* `https://ambassador.example.com/resource3/baz/zing` - -Note that the length of the prefix doesn't matter; a prefix like `/v1/this/is/my/very/long/resource/name/` is valid. - -Also note that $productName$ does not actually require the prefix to start and end with `/` -- however, in practice, it's a good idea. Specifying a prefix of `/man` would match all of the following, which probably is not what was intended: - -* `https://ambassador.example.com/man/foo` -* `https://ambassador.example.com/mankind` -* `https://ambassador.example.com/man-it-is/really-hot-today` - -## Services - -$productName$ routes traffic to a service. A service is defined as `[scheme://]service[.namespace][:port]`. Everything except for the service is optional. - -- `scheme` can be either `http` or `https`; if not present, the default is `http`. -- `service` is the name of a service (typically the service name in Kubernetes or Consul); it is not allowed to contain the `.` character. -- `namespace` is the namespace in which the service is running. Starting with $productName$ 1.0.0, if not supplied, it defaults to the namespace in which the Mapping resource is defined. The default behavior can be configured using the [Module resource](../../topics/running/ambassador). When using a Consul resolver, `namespace` is not allowed. -- `port` is the port to which a request should be sent. If not specified, it defaults to `80` when the scheme is `http` or `443` when the scheme is `https`. Note that the [resolver](../../topics/running/resolvers) may return a port in which case the `port` setting is ignored. - -While using service.namespace.svc.cluster.local may work for Kubernetes resolvers, the preferred syntax is service.namespace. - - -## Extending Mappings - -Mapping resources support a rich set of annotations to customize the specific routing behavior. Here's an example service for implementing the [CQRS pattern](https://docs.microsoft.com/en-us/azure/architecture/patterns/cqrs) (using HTTP): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-get -spec: - prefix: /cqrs/ - method: GET - service: getcqrs - hostname: '*' ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-put -spec: - prefix: /cqrs/ - method: PUT - service: putcqrs - hostname: '*' -``` - -## Best Practices - -$productName$'s configuration is assembled from multiple YAML blocks which are managed by independent application teams. This implies that certain best practices should be followed. - -#### $productName$'s configuration should be under version control. - -While you can always read back the $productName$'s configuration from Kubernetes or its diagnostic service, the $productName$ will not do versioning for you. - -#### $productName$ tries to not start with a broken configuration, but it's not perfect. - -Gross errors will result in the $productName$ refusing to start, in which case `kubectl logs` will be helpful. However, it's always possible to map a resource to the wrong service, or use the wrong `rewrite` rules. $productName$ can't detect that on its own, although its [diagnostic service](../../topics/running/diagnostics/) can help you figure it out. - -#### Be careful of mapping collisions. - -If two different developers try to map `/myservice/` to something, this can lead to unexpected behavior. $productName$'s [canary deployment](../../topics/using/canary/) logic means that it's more likely that traffic will be split between them than that it will throw an error -- again, the diagnostic service can help you here. - -#### Unless specified, mapping attributes cannot be applied to any other resource type. - -## 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/content/en/docs/3.5/howtos/tls-termination.md b/content/en/docs/3.5/howtos/tls-termination.md deleted file mode 100644 index 2bbdf4c4..00000000 --- a/content/en/docs/3.5/howtos/tls-termination.md +++ /dev/null @@ -1,192 +0,0 @@ -# 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/content/en/docs/3.5/howtos/tracing-datadog.md b/content/en/docs/3.5/howtos/tracing-datadog.md deleted file mode 100644 index d627e29f..00000000 --- a/content/en/docs/3.5/howtos/tracing-datadog.md +++ /dev/null @@ -1,63 +0,0 @@ -# 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/content/en/docs/3.5/howtos/tracing-lightstep.md b/content/en/docs/3.5/howtos/tracing-lightstep.md deleted file mode 100644 index 30353e71..00000000 --- a/content/en/docs/3.5/howtos/tracing-lightstep.md +++ /dev/null @@ -1,230 +0,0 @@ -# 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. - - - Please note that the 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. - - -## Before you get started - -This tutorial assumes you have already followed the $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. Setup Lightstep - -If you don't already have a Lightstep account be sure to create one [here](https://lightstep.com/). Then create a Project and be sure to create and save the Access Token information. You can find your Access Token information under the Project settings. - -## 2. Deploy the OpenTelemetry Collector - -The next step is to deploy the OpenTelemetry Collector. The purpose of the OpenTelemetry Collector is to receive the requested trace data and then export it to Lightstep. - -For the purposes of this tutorial, we are going to create and use the `monitoring` namespace. This can be done with the following command. - -```bash - kubectl create namespace monitoring -``` - -Next we are going to setup our configuration for the OpenTelemetry Collector. First, we use a Kubernetes secret to store our Lightstep Access Token that we saved in step one. It is important for us to encode the secret in Base64. How you want to do this securely is up to you, for the purposes of this tutorial we will use the online tool [Base64Encode.org](https://www.base64encode.org/). Once the secret is encoded, please apply the following YAML and be sure to update the value of the `lightstep_access_token` with your encoded token. - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: otel - namespace: monitoring -type: Opaque -data: - lightstep_access_token: YOUR_BASE64_ENCODED_TOKEN_HERE -``` - -Next, please add the following YAML to a file named `opentelemetry.yaml`. This configuration will create 3 resources. A ConfigMap that will store our configuration options, an OpenTelemetry Deployment that uses the [OpenTelemetry Collector Contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib) container image, and an associated Service for our Distributed Tracing. - -```yaml ---- ---- -apiVersion: v1 -kind: ConfigMap -metadata: - name: otel-collector-conf - namespace: monitoring - labels: - app: opentelemetry - component: otel-collector-conf -data: - otel-collector-config: | - receivers: - zipkin: {} - processors: - batch: - memory_limiter: - # Same as --mem-ballast-size-mib CLI argument - ballast_size_mib: 683 - # 80% of maximum memory up to 2G - limit_mib: 1500 - # 25% of limit up to 2G - spike_limit_mib: 512 - check_interval: 5s - queued_retry: - extensions: - health_check: {} - zpages: {} - exporters: - otlp: - endpoint: ingest.lightstep.com:443 - headers: {"lightstep-access-token":"${LIGHTSTEP_ACCESS_TOKEN}"} - service: - extensions: [health_check, zpages] - pipelines: - traces: - receivers: [zipkin] - processors: [memory_limiter, batch, queued_retry] - exporters: - - otlp ---- -apiVersion: v1 -kind: Service -metadata: - name: otel-collector - namespace: monitoring - labels: - app: opentelemetry - component: otel-collector -spec: - ports: - - name: otlp # Default endpoint for OpenTelemetry receiver. - port: 55680 - - name: zipkin # Default endpoint for Zipkin trace receiver. - port: 9411 - selector: - component: otel-collector ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: otel-collector - namespace: monitoring - labels: - app: opentelemetry - component: otel-collector -spec: - selector: - matchLabels: - app: opentelemetry - component: otel-collector - minReadySeconds: 5 - progressDeadlineSeconds: 120 - replicas: 1 - template: - metadata: - labels: - app: opentelemetry - component: otel-collector - spec: - containers: - - command: - - "/otelcontribcol" - - "--config=/conf/otel-collector-config.yaml" - - "--mem-ballast-size-mib=683" # Memory Ballast size should be max 1/3 to 1/2 of memory. - image: otel/opentelemetry-collector-contrib:0.11.0 - name: otel-collector - resources: - limits: - cpu: 1000m - memory: 2Gi - requests: - cpu: 200m - memory: 400Mi - ports: - - containerPort: 55680 # Default endpoint for OpenTelemetry receiver. - - containerPort: 9411 # Default endpoint for Zipkin receiver. - env: - - name: LIGHTSTEP_ACCESS_TOKEN - valueFrom: - secretKeyRef: - name: otel - key: lightstep_access_token - volumeMounts: - - name: otel-collector-config-vol - mountPath: /conf - livenessProbe: - httpGet: - path: / - port: 13133 - readinessProbe: - httpGet: - path: / - port: 13133 - volumes: - - configMap: - name: otel-collector-conf - items: - - key: otel-collector-config - path: otel-collector-config.yaml - name: otel-collector-config-vol -``` - -Be sure to apply this configuration with the following command: - -```bash - kubectl apply -f opentelemetry.yaml -``` - -At this point, the OpenTelemetry Collector should be setup properly and ready to send data to Lightstep. - -## 3. Configure the TracingService - -Now that the OpenTelemetry Collector is setup for collecting data, the next step will be for us to setup our [TracingService](../../topics/running/services/tracing-service). We will be using the Zipkin driver to send our request trace data to the OpenTelemetry Collector for Distributed Tracing. Please apply the following YAML. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TracingService -metadata: - name: tracing-zipkin - namespace: ambassador -spec: - service: otel-collector.monitoring:9411 - driver: zipkin -``` - -As a final step we want to restart $productName$ as this is necessary to add the distributed tracing headers. This command will restart all the Pods (assuming $productName$ is installed in the ambassador namespace): - -```bash - kubectl -n ambassador rollout restart deploy -``` - - - Restarting $productName$ is required after deploying a Tracing Service for changes to take effect. - - -## 4. Testing our Distributed Tracing - -Finally, we are going to test our Distributed Tracing. 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. - -```bash - curl -Li http://$LB_ENDPOINT/backend/ -``` - -At this point, we should be able to view and check our traces on the [Lightstep app](https://app.lightstep.com/). You can do so by clicking on the Explorer tab and searching for a trace. - -## Migrating from the Lightstep Tracing Driver - - - Please be sure to follow these steps prior to upgrading to $productName$ version 3.4.0. - - -As of $productName$ version 3.4.0, the Lightstep tracing driver will no longer be supported. This is due to the upgrade to Envoy version 1.24, where the team at LightStep has completely removed support for the LightStep Tracing driver in favor of using the OpenTelemetry Collector. In order to continue to use Lightstep to visualize our traces, we can follow similar steps to the above tutorial. - -First, make sure that the OpenTelemetry Collector is installed. This can be done by following the same commands as step 2 of this page. Please be sure to create/update the Kubernetes secret to include your Lightstep Access Token. - -Then, we simply need to edit our TracingService to point to the OpenTelemetry Collector (instead of the ingest endpoint of Lightstep) and to use the Zipkin driver. Please note that $productName$ can only support 1 TracingService per instance. Because of this, we must edit our previous TracingService rather than applying a second one. - -If you were using the Lightstep tracing driver, you may have your Lightstep Access Token information set in your TracingService config. Using a Kubernetes Secret, we no longer need to reference the token here. - -Once our TracingService configuration has been updated, a restart of $productName$ is necessary for Lightstep to recieve our Distributed Tracing information. This can be done with the following command: - -```bash - kubectl -n ambassador rollout restart deploy -``` diff --git a/content/en/docs/3.5/howtos/tracing-zipkin.md b/content/en/docs/3.5/howtos/tracing-zipkin.md deleted file mode 100644 index 37ddc902..00000000 --- a/content/en/docs/3.5/howtos/tracing-zipkin.md +++ /dev/null @@ -1,129 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Distributed tracing with Zipkin - -In this tutorial, we'll configure $productName$ to initiate a trace on some sample requests, and use Zipkin 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. Deploy Zipkin - -In this tutorial, you will use a simple deployment of the open-source [Zipkin](https://github.com/openzipkin/zipkin/wiki) distributed tracing system to store and visualize $productName$-generated traces. The trace data will be stored in memory within the Zipkin container, and you will be able to explore the traces via the Zipkin web UI. - -First, add the following YAML to a file named `zipkin.yaml`. This configuration will create a Zipkin Deployment that uses the [openzipkin/zipkin](https://hub.docker.com/r/openzipkin/zipkin/) container image and also an associated Service. We will also include a `TracingService` that configures $productName$ to use the Zipkin service (running on the default port of 9411) to provide tracing support. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TracingService -metadata: - name: tracing -spec: - service: "zipkin:9411" - driver: zipkin - config: {} ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: zipkin -spec: - replicas: 1 - selector: - matchLabels: - app: zipkin - template: - metadata: - labels: - app: zipkin - spec: - containers: - - name: zipkin - image: openzipkin/zipkin - env: - # note: in-memory storage holds all data in memory, purging older data upon a span limit. - # you should use a proper storage in production environments - - name: STORAGE_TYPE - value: mem ---- -apiVersion: v1 -kind: Service -metadata: - labels: - name: zipkin - name: zipkin -spec: - ports: - - port: 9411 - targetPort: 9411 - selector: - app: zipkin -``` - -Next, deploy this configuration into your cluster: - -``` -$ kubectl apply -f zipkin.yaml -``` - -As a final step we want to restart $productName$ as this is necessary to add the tracing header. This command will restart all the Pods (assuming $productName$ is installed in the ambassador namespace): - -``` -$ kubectl -n ambassador rollout restart deploy -``` - - Restarting $productName$ is required after deploying a Tracing Service for changes to take effect. - - -## 2. 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/backend/ -``` - -## 3. Test traces - -To test things out, we'll need to access the Zipkin UI. If you're on Kubernetes, get the name of the Zipkin pod: - -``` -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -ambassador-5ffcfc798-c25dc 2/2 Running 0 1d -prometheus-prometheus-0 2/2 Running 0 113d -zipkin-868b97667c-58v4r 1/1 Running 0 2h -``` - -And then use `kubectl port-forward` to access the pod: - -``` -$ kubectl port-forward zipkin-868b97667c-58v4r 9411 -``` - -Open your web browser to `http://localhost:9411` for the Zipkin UI. - -If you're on `minikube` you can access the `NodePort` directly, and this ports number can be obtained via the `minikube services list` command. If you are using `Docker for Mac/Windows`, you can use the `kubectl get svc` command to get the same information. - -``` -$ minikube service list -|-------------|----------------------|-----------------------------| -| NAMESPACE | NAME | URL | -|-------------|----------------------|-----------------------------| -| default | ambassador-admin | http://192.168.99.107:30319 | -| default | ambassador | http://192.168.99.107:31893 | -| default | zipkin | http://192.168.99.107:31043 | -|-------------|----------------------|-----------------------------| -``` - -Open your web browser to the Zipkin dashboard `http://192.168.99.107:31043/zipkin/`. - -In the Zipkin UI, click on the "Find Traces" button to get a listing instrumented traces. Each of the traces that are displayed can be clicked on, which provides further information about each span and associated metadata. - -## Learn more - -For more details about configuring the external tracing service, read the documentation on [external tracing](../../topics/running/services/tracing-service). diff --git a/content/en/docs/3.5/howtos/websockets.md b/content/en/docs/3.5/howtos/websockets.md deleted file mode 100644 index 25cac7da..00000000 --- a/content/en/docs/3.5/howtos/websockets.md +++ /dev/null @@ -1,43 +0,0 @@ -# WebSocket connections - -$productName$ makes it easy to access your services from outside your -application, and this includes services that use WebSockets. Only a -small amount of additional configuration is required, which is as -simple as telling the Mapping to allow "upgrading" from the HTTP protocol to -the "websocket" protocol: - -```yaml -allow_upgrade: -- websocket -``` - -## Example WebSocket service - -The example configuration below demonstrates the addition of the `allow_upgrade:` attribute to support websockets. The use of `use_websocket` is now deprecated. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: my-service-mapping -spec: - hostname: "*" - prefix: /my-service/ - service: my-service - allow_upgrade: - - websocket - ---- -kind: Service -apiVersion: v1 -metadata: - name: my-service -spec: - selector: - app: MyApp - ports: - - protocol: TCP - port: 80 - targetPort: 9376 -``` diff --git a/content/en/docs/3.5/images/Auth0_JWT.png b/content/en/docs/3.5/images/Auth0_JWT.png deleted file mode 100644 index e18155f5..00000000 Binary files a/content/en/docs/3.5/images/Auth0_JWT.png and /dev/null differ diff --git a/content/en/docs/3.5/images/Auth0_domain_clientID.png b/content/en/docs/3.5/images/Auth0_domain_clientID.png deleted file mode 100644 index a7f8edf6..00000000 Binary files a/content/en/docs/3.5/images/Auth0_domain_clientID.png and /dev/null differ diff --git a/content/en/docs/3.5/images/Auth0_method_callback_origins.png b/content/en/docs/3.5/images/Auth0_method_callback_origins.png deleted file mode 100644 index 8d31138e..00000000 Binary files a/content/en/docs/3.5/images/Auth0_method_callback_origins.png and /dev/null differ diff --git a/content/en/docs/3.5/images/aes-success.png b/content/en/docs/3.5/images/aes-success.png deleted file mode 100644 index 66f28d3f..00000000 Binary files a/content/en/docs/3.5/images/aes-success.png and /dev/null differ diff --git a/content/en/docs/3.5/images/ambassador-arch.png b/content/en/docs/3.5/images/ambassador-arch.png deleted file mode 100644 index 5a5cb652..00000000 Binary files a/content/en/docs/3.5/images/ambassador-arch.png and /dev/null differ diff --git a/content/en/docs/3.5/images/ambassador-logo.svg b/content/en/docs/3.5/images/ambassador-logo.svg deleted file mode 100644 index 1f0e06a8..00000000 --- a/content/en/docs/3.5/images/ambassador-logo.svg +++ /dev/null @@ -1,49 +0,0 @@ - - - - ambassador logo@1x - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.5/images/ambassador_oidc_flow.jpg b/content/en/docs/3.5/images/ambassador_oidc_flow.jpg deleted file mode 100644 index 4f1c0c7e..00000000 Binary files a/content/en/docs/3.5/images/ambassador_oidc_flow.jpg and /dev/null differ diff --git a/content/en/docs/3.5/images/apple.png b/content/en/docs/3.5/images/apple.png deleted file mode 100644 index 8b8277f1..00000000 Binary files a/content/en/docs/3.5/images/apple.png and /dev/null differ diff --git a/content/en/docs/3.5/images/auth-flow.png b/content/en/docs/3.5/images/auth-flow.png deleted file mode 100644 index e1ba4387..00000000 Binary files a/content/en/docs/3.5/images/auth-flow.png and /dev/null differ diff --git a/content/en/docs/3.5/images/authentication-icon.svg b/content/en/docs/3.5/images/authentication-icon.svg deleted file mode 100644 index 342e8a3d..00000000 --- a/content/en/docs/3.5/images/authentication-icon.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_897228_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.5/images/blackbird.png b/content/en/docs/3.5/images/blackbird.png deleted file mode 100644 index 1f10e5cc..00000000 Binary files a/content/en/docs/3.5/images/blackbird.png and /dev/null differ diff --git a/content/en/docs/3.5/images/canary-release-overview.png b/content/en/docs/3.5/images/canary-release-overview.png deleted file mode 100644 index c683a23d..00000000 Binary files a/content/en/docs/3.5/images/canary-release-overview.png and /dev/null differ diff --git a/content/en/docs/3.5/images/configure-icon.svg b/content/en/docs/3.5/images/configure-icon.svg deleted file mode 100644 index 0f556840..00000000 --- a/content/en/docs/3.5/images/configure-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_858572_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.5/images/consul-ambassador.png b/content/en/docs/3.5/images/consul-ambassador.png deleted file mode 100644 index c4911624..00000000 Binary files a/content/en/docs/3.5/images/consul-ambassador.png and /dev/null differ diff --git a/content/en/docs/3.5/images/container-inner-dev-loop.png b/content/en/docs/3.5/images/container-inner-dev-loop.png deleted file mode 100644 index 06586cd6..00000000 Binary files a/content/en/docs/3.5/images/container-inner-dev-loop.png and /dev/null differ diff --git a/content/en/docs/3.5/images/datawire-logo.svg b/content/en/docs/3.5/images/datawire-logo.svg deleted file mode 100644 index fb45872c..00000000 --- a/content/en/docs/3.5/images/datawire-logo.svg +++ /dev/null @@ -1,27 +0,0 @@ - - - - Group 3 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.5/images/diagnostics-example.png b/content/en/docs/3.5/images/diagnostics-example.png deleted file mode 100644 index 6c825b0c..00000000 Binary files a/content/en/docs/3.5/images/diagnostics-example.png and /dev/null differ diff --git a/content/en/docs/3.5/images/diagnostics.png b/content/en/docs/3.5/images/diagnostics.png deleted file mode 100644 index 29248703..00000000 Binary files a/content/en/docs/3.5/images/diagnostics.png and /dev/null differ diff --git a/content/en/docs/3.5/images/docker-compose.png b/content/en/docs/3.5/images/docker-compose.png deleted file mode 100644 index b8829521..00000000 Binary files a/content/en/docs/3.5/images/docker-compose.png and /dev/null differ diff --git a/content/en/docs/3.5/images/docker.png b/content/en/docs/3.5/images/docker.png deleted file mode 100644 index 1f35e5ea..00000000 Binary files a/content/en/docs/3.5/images/docker.png and /dev/null differ diff --git a/content/en/docs/3.5/images/edge-stack-1.13.4.png b/content/en/docs/3.5/images/edge-stack-1.13.4.png deleted file mode 100644 index 954ac1a9..00000000 Binary files a/content/en/docs/3.5/images/edge-stack-1.13.4.png and /dev/null differ diff --git a/content/en/docs/3.5/images/edge-stack-1.13.7-json-logging.png b/content/en/docs/3.5/images/edge-stack-1.13.7-json-logging.png deleted file mode 100644 index 4a47cbdf..00000000 Binary files a/content/en/docs/3.5/images/edge-stack-1.13.7-json-logging.png and /dev/null differ diff --git a/content/en/docs/3.5/images/edge-stack-1.13.7-memory.png b/content/en/docs/3.5/images/edge-stack-1.13.7-memory.png deleted file mode 100644 index 9c415ba3..00000000 Binary files a/content/en/docs/3.5/images/edge-stack-1.13.7-memory.png and /dev/null differ diff --git a/content/en/docs/3.5/images/edge-stack-1.13.7-tcpmapping-consul.png b/content/en/docs/3.5/images/edge-stack-1.13.7-tcpmapping-consul.png deleted file mode 100644 index c455a47f..00000000 Binary files a/content/en/docs/3.5/images/edge-stack-1.13.7-tcpmapping-consul.png and /dev/null differ diff --git a/content/en/docs/3.5/images/edge-stack-1.13.8-cloud-bugfix.png b/content/en/docs/3.5/images/edge-stack-1.13.8-cloud-bugfix.png deleted file mode 100644 index 6beaf653..00000000 Binary files a/content/en/docs/3.5/images/edge-stack-1.13.8-cloud-bugfix.png and /dev/null differ diff --git a/content/en/docs/3.5/images/emissary-1.13.10-cors-origin.png b/content/en/docs/3.5/images/emissary-1.13.10-cors-origin.png deleted file mode 100644 index b7538e5f..00000000 Binary files a/content/en/docs/3.5/images/emissary-1.13.10-cors-origin.png and /dev/null differ diff --git a/content/en/docs/3.5/images/fast-icon.svg b/content/en/docs/3.5/images/fast-icon.svg deleted file mode 100644 index 354542ee..00000000 --- a/content/en/docs/3.5/images/fast-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1187990_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.5/images/features-icons/basic-authentication.svg b/content/en/docs/3.5/images/features-icons/basic-authentication.svg deleted file mode 100644 index 2bd19edf..00000000 --- a/content/en/docs/3.5/images/features-icons/basic-authentication.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_897228_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.5/images/features-icons/canary-release.svg b/content/en/docs/3.5/images/features-icons/canary-release.svg deleted file mode 100644 index f8de57d9..00000000 --- a/content/en/docs/3.5/images/features-icons/canary-release.svg +++ /dev/null @@ -1,27 +0,0 @@ - - - - Group 25 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.5/images/features-icons/cors.svg b/content/en/docs/3.5/images/features-icons/cors.svg deleted file mode 100644 index e559d924..00000000 --- a/content/en/docs/3.5/images/features-icons/cors.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_111967_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.5/images/features-icons/datadog.png b/content/en/docs/3.5/images/features-icons/datadog.png deleted file mode 100644 index eea05f8c..00000000 Binary files a/content/en/docs/3.5/images/features-icons/datadog.png and /dev/null differ diff --git a/content/en/docs/3.5/images/features-icons/datadog.svg b/content/en/docs/3.5/images/features-icons/datadog.svg deleted file mode 100644 index e46e8118..00000000 --- a/content/en/docs/3.5/images/features-icons/datadog.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Screen Shot 2018-04-05 at 8.22.25 AM - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.5/images/features-icons/diagnostics.svg b/content/en/docs/3.5/images/features-icons/diagnostics.svg deleted file mode 100644 index 940e1bc2..00000000 --- a/content/en/docs/3.5/images/features-icons/diagnostics.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_196445_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.5/images/features-icons/distributed-tracing.png b/content/en/docs/3.5/images/features-icons/distributed-tracing.png deleted file mode 100644 index 6b69e28c..00000000 Binary files a/content/en/docs/3.5/images/features-icons/distributed-tracing.png and /dev/null differ diff --git a/content/en/docs/3.5/images/features-icons/grpc.png b/content/en/docs/3.5/images/features-icons/grpc.png deleted file mode 100644 index b2f5a0d9..00000000 Binary files a/content/en/docs/3.5/images/features-icons/grpc.png and /dev/null differ diff --git a/content/en/docs/3.5/images/features-icons/prometheus.svg b/content/en/docs/3.5/images/features-icons/prometheus.svg deleted file mode 100644 index d5252a66..00000000 --- a/content/en/docs/3.5/images/features-icons/prometheus.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - prometheus_logo_grey - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.5/images/features-icons/rate-limiting.svg b/content/en/docs/3.5/images/features-icons/rate-limiting.svg deleted file mode 100644 index f1b6eacb..00000000 --- a/content/en/docs/3.5/images/features-icons/rate-limiting.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - Group 10 - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.5/images/features-icons/regex-routing.svg b/content/en/docs/3.5/images/features-icons/regex-routing.svg deleted file mode 100644 index 113b53b5..00000000 --- a/content/en/docs/3.5/images/features-icons/regex-routing.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_699774_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.5/images/features-icons/request-transformers.svg b/content/en/docs/3.5/images/features-icons/request-transformers.svg deleted file mode 100644 index 0b13e2dc..00000000 --- a/content/en/docs/3.5/images/features-icons/request-transformers.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_96239_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.5/images/features-icons/shadowing.svg b/content/en/docs/3.5/images/features-icons/shadowing.svg deleted file mode 100644 index 9e85eee1..00000000 --- a/content/en/docs/3.5/images/features-icons/shadowing.svg +++ /dev/null @@ -1,15 +0,0 @@ - - - - shadow - Created with Sketch. - - - - - - - - - - diff --git a/content/en/docs/3.5/images/features-icons/statsd.png b/content/en/docs/3.5/images/features-icons/statsd.png deleted file mode 100644 index 28374438..00000000 Binary files a/content/en/docs/3.5/images/features-icons/statsd.png and /dev/null differ diff --git a/content/en/docs/3.5/images/features-icons/statsd.svg b/content/en/docs/3.5/images/features-icons/statsd.svg deleted file mode 100644 index cabc90db..00000000 --- a/content/en/docs/3.5/images/features-icons/statsd.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - 88eb31f74479e422e4e9abfc6c2b00ee - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/3.5/images/features-icons/third-party-auth.svg b/content/en/docs/3.5/images/features-icons/third-party-auth.svg deleted file mode 100644 index 5359a24a..00000000 --- a/content/en/docs/3.5/images/features-icons/third-party-auth.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_511233_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.5/images/features-icons/timeouts.svg b/content/en/docs/3.5/images/features-icons/timeouts.svg deleted file mode 100644 index 47f63056..00000000 --- a/content/en/docs/3.5/images/features-icons/timeouts.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_587034_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.5/images/features-icons/tls-termination.svg b/content/en/docs/3.5/images/features-icons/tls-termination.svg deleted file mode 100644 index 6a631a96..00000000 --- a/content/en/docs/3.5/images/features-icons/tls-termination.svg +++ /dev/null @@ -1,17 +0,0 @@ - - - - noun_63544_cc - Created with Sketch. - - - - - - - - - - - - diff --git a/content/en/docs/3.5/images/features-icons/url-rewrite.svg b/content/en/docs/3.5/images/features-icons/url-rewrite.svg deleted file mode 100644 index 023e2e05..00000000 --- a/content/en/docs/3.5/images/features-icons/url-rewrite.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1295942_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.5/images/features-icons/websockets.svg b/content/en/docs/3.5/images/features-icons/websockets.svg deleted file mode 100644 index af17b9c0..00000000 --- a/content/en/docs/3.5/images/features-icons/websockets.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - noun_50814_cc - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.5/images/features-table.jpg b/content/en/docs/3.5/images/features-table.jpg deleted file mode 100644 index 3de2eb4f..00000000 Binary files a/content/en/docs/3.5/images/features-table.jpg and /dev/null differ diff --git a/content/en/docs/3.5/images/gRPC-TLS-Ambassador.png b/content/en/docs/3.5/images/gRPC-TLS-Ambassador.png deleted file mode 100644 index 0189253e..00000000 Binary files a/content/en/docs/3.5/images/gRPC-TLS-Ambassador.png and /dev/null differ diff --git a/content/en/docs/3.5/images/gRPC-TLS-Originate.png b/content/en/docs/3.5/images/gRPC-TLS-Originate.png deleted file mode 100644 index 1b62010d..00000000 Binary files a/content/en/docs/3.5/images/gRPC-TLS-Originate.png and /dev/null differ diff --git a/content/en/docs/3.5/images/github-login.png b/content/en/docs/3.5/images/github-login.png deleted file mode 100644 index cfd4d4bf..00000000 Binary files a/content/en/docs/3.5/images/github-login.png and /dev/null differ diff --git a/content/en/docs/3.5/images/global-features-bg.svg b/content/en/docs/3.5/images/global-features-bg.svg deleted file mode 100644 index a39c5232..00000000 --- a/content/en/docs/3.5/images/global-features-bg.svg +++ /dev/null @@ -1,34 +0,0 @@ - - - - ambassador_logo@2x - Created with Sketch. - - - - - - - - diff --git a/content/en/docs/3.5/images/grafana.png b/content/en/docs/3.5/images/grafana.png deleted file mode 100644 index 03912506..00000000 Binary files a/content/en/docs/3.5/images/grafana.png and /dev/null differ diff --git a/content/en/docs/3.5/images/grpc-tls.png b/content/en/docs/3.5/images/grpc-tls.png deleted file mode 100644 index 4d705ff0..00000000 Binary files a/content/en/docs/3.5/images/grpc-tls.png and /dev/null differ diff --git a/content/en/docs/3.5/images/helm-navy.png b/content/en/docs/3.5/images/helm-navy.png deleted file mode 100644 index a9710143..00000000 Binary files a/content/en/docs/3.5/images/helm-navy.png and /dev/null differ diff --git a/content/en/docs/3.5/images/helm.png b/content/en/docs/3.5/images/helm.png deleted file mode 100644 index 1c5af71b..00000000 Binary files a/content/en/docs/3.5/images/helm.png and /dev/null differ diff --git a/content/en/docs/3.5/images/highly-available-icon.svg b/content/en/docs/3.5/images/highly-available-icon.svg deleted file mode 100644 index 9cb3eff9..00000000 --- a/content/en/docs/3.5/images/highly-available-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1205522_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.5/images/jaeger.png b/content/en/docs/3.5/images/jaeger.png deleted file mode 100644 index 3b821c09..00000000 Binary files a/content/en/docs/3.5/images/jaeger.png and /dev/null differ diff --git a/content/en/docs/3.5/images/kubernetes.png b/content/en/docs/3.5/images/kubernetes.png deleted file mode 100644 index a392a886..00000000 Binary files a/content/en/docs/3.5/images/kubernetes.png and /dev/null differ diff --git a/content/en/docs/3.5/images/left-arrow.svg b/content/en/docs/3.5/images/left-arrow.svg deleted file mode 100644 index 75cdc7f1..00000000 --- a/content/en/docs/3.5/images/left-arrow.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Path 2 - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.5/images/linux.png b/content/en/docs/3.5/images/linux.png deleted file mode 100644 index 1832c594..00000000 Binary files a/content/en/docs/3.5/images/linux.png and /dev/null differ diff --git a/content/en/docs/3.5/images/logo.png b/content/en/docs/3.5/images/logo.png deleted file mode 100644 index 701f63ba..00000000 Binary files a/content/en/docs/3.5/images/logo.png and /dev/null differ diff --git a/content/en/docs/3.5/images/mapping-editor.png b/content/en/docs/3.5/images/mapping-editor.png deleted file mode 100644 index f8b751a1..00000000 Binary files a/content/en/docs/3.5/images/mapping-editor.png and /dev/null differ diff --git a/content/en/docs/3.5/images/network-architecture.png b/content/en/docs/3.5/images/network-architecture.png deleted file mode 100644 index 3217b3e1..00000000 Binary files a/content/en/docs/3.5/images/network-architecture.png and /dev/null differ diff --git a/content/en/docs/3.5/images/penguin-background.svg b/content/en/docs/3.5/images/penguin-background.svg deleted file mode 100644 index 7affc0d5..00000000 --- a/content/en/docs/3.5/images/penguin-background.svg +++ /dev/null @@ -1,102 +0,0 @@ - - - - @2xambassador_logo - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/3.5/images/pro-iap.png b/content/en/docs/3.5/images/pro-iap.png deleted file mode 100644 index 787265d8..00000000 Binary files a/content/en/docs/3.5/images/pro-iap.png and /dev/null differ diff --git a/content/en/docs/3.5/images/quote.svg b/content/en/docs/3.5/images/quote.svg deleted file mode 100644 index bab6e871..00000000 --- a/content/en/docs/3.5/images/quote.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - “ - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/3.5/images/right-arrow.svg b/content/en/docs/3.5/images/right-arrow.svg deleted file mode 100644 index 627144c6..00000000 --- a/content/en/docs/3.5/images/right-arrow.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Path 2 Copy - Created with Sketch. - - - - - - - diff --git a/content/en/docs/3.5/images/routing-icon.svg b/content/en/docs/3.5/images/routing-icon.svg deleted file mode 100644 index bd860b13..00000000 --- a/content/en/docs/3.5/images/routing-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1062254_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/3.5/images/self-service-features-bg.svg b/content/en/docs/3.5/images/self-service-features-bg.svg deleted file mode 100644 index 40bc400a..00000000 --- a/content/en/docs/3.5/images/self-service-features-bg.svg +++ /dev/null @@ -1,93 +0,0 @@ - - - - Group 8 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - SELF-SERVICE FEATURES - - - - diff --git a/content/en/docs/3.5/images/shadowing.png b/content/en/docs/3.5/images/shadowing.png deleted file mode 100644 index 097ecbd5..00000000 Binary files a/content/en/docs/3.5/images/shadowing.png and /dev/null differ diff --git a/content/en/docs/3.5/images/speedometers.png b/content/en/docs/3.5/images/speedometers.png deleted file mode 100644 index 7ce2c2a2..00000000 Binary files a/content/en/docs/3.5/images/speedometers.png and /dev/null differ diff --git a/content/en/docs/3.5/images/tp-architecture.png b/content/en/docs/3.5/images/tp-architecture.png deleted file mode 100644 index 20ae3589..00000000 Binary files a/content/en/docs/3.5/images/tp-architecture.png and /dev/null differ diff --git a/content/en/docs/3.5/images/tp-tutorial-1.png b/content/en/docs/3.5/images/tp-tutorial-1.png deleted file mode 100644 index ee68dc7d..00000000 Binary files a/content/en/docs/3.5/images/tp-tutorial-1.png and /dev/null differ diff --git a/content/en/docs/3.5/images/tp-tutorial-2.png b/content/en/docs/3.5/images/tp-tutorial-2.png deleted file mode 100644 index 129dc6ee..00000000 Binary files a/content/en/docs/3.5/images/tp-tutorial-2.png and /dev/null differ diff --git a/content/en/docs/3.5/images/tp-tutorial-3.png b/content/en/docs/3.5/images/tp-tutorial-3.png deleted file mode 100644 index 946629fc..00000000 Binary files a/content/en/docs/3.5/images/tp-tutorial-3.png and /dev/null differ diff --git a/content/en/docs/3.5/images/tp-tutorial-4.png b/content/en/docs/3.5/images/tp-tutorial-4.png deleted file mode 100644 index cb6e7a9d..00000000 Binary files a/content/en/docs/3.5/images/tp-tutorial-4.png and /dev/null differ diff --git a/content/en/docs/3.5/images/trad-inner-dev-loop.png b/content/en/docs/3.5/images/trad-inner-dev-loop.png deleted file mode 100644 index 618b674f..00000000 Binary files a/content/en/docs/3.5/images/trad-inner-dev-loop.png and /dev/null differ diff --git a/content/en/docs/3.5/images/windows.png b/content/en/docs/3.5/images/windows.png deleted file mode 100644 index a065dc17..00000000 Binary files a/content/en/docs/3.5/images/windows.png and /dev/null differ diff --git a/content/en/docs/3.5/images/xkcd.png b/content/en/docs/3.5/images/xkcd.png deleted file mode 100644 index ed0d5c33..00000000 Binary files a/content/en/docs/3.5/images/xkcd.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/edge-stack-1.13.4.png b/content/en/docs/3.5/release-notes/edge-stack-1.13.4.png deleted file mode 100644 index 954ac1a9..00000000 Binary files a/content/en/docs/3.5/release-notes/edge-stack-1.13.4.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/edge-stack-1.13.7-json-logging.png b/content/en/docs/3.5/release-notes/edge-stack-1.13.7-json-logging.png deleted file mode 100644 index 4a47cbdf..00000000 Binary files a/content/en/docs/3.5/release-notes/edge-stack-1.13.7-json-logging.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/edge-stack-1.13.7-memory.png b/content/en/docs/3.5/release-notes/edge-stack-1.13.7-memory.png deleted file mode 100644 index 9c415ba3..00000000 Binary files a/content/en/docs/3.5/release-notes/edge-stack-1.13.7-memory.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/edge-stack-1.13.7-tcpmapping-consul.png b/content/en/docs/3.5/release-notes/edge-stack-1.13.7-tcpmapping-consul.png deleted file mode 100644 index c455a47f..00000000 Binary files a/content/en/docs/3.5/release-notes/edge-stack-1.13.7-tcpmapping-consul.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/edge-stack-1.13.8-cloud-bugfix.png b/content/en/docs/3.5/release-notes/edge-stack-1.13.8-cloud-bugfix.png deleted file mode 100644 index 6beaf653..00000000 Binary files a/content/en/docs/3.5/release-notes/edge-stack-1.13.8-cloud-bugfix.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/edge-stack-2.0.0-host_crd.png b/content/en/docs/3.5/release-notes/edge-stack-2.0.0-host_crd.png deleted file mode 100644 index c77ef528..00000000 Binary files a/content/en/docs/3.5/release-notes/edge-stack-2.0.0-host_crd.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/edge-stack-2.0.0-ingressstatus.png b/content/en/docs/3.5/release-notes/edge-stack-2.0.0-ingressstatus.png deleted file mode 100644 index 6856d308..00000000 Binary files a/content/en/docs/3.5/release-notes/edge-stack-2.0.0-ingressstatus.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/edge-stack-2.0.0-insecure_action_hosts.png b/content/en/docs/3.5/release-notes/edge-stack-2.0.0-insecure_action_hosts.png deleted file mode 100644 index 79c20bad..00000000 Binary files a/content/en/docs/3.5/release-notes/edge-stack-2.0.0-insecure_action_hosts.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/edge-stack-2.0.0-listener.png b/content/en/docs/3.5/release-notes/edge-stack-2.0.0-listener.png deleted file mode 100644 index ea45a02b..00000000 Binary files a/content/en/docs/3.5/release-notes/edge-stack-2.0.0-listener.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/edge-stack-2.0.0-prune_routes.png b/content/en/docs/3.5/release-notes/edge-stack-2.0.0-prune_routes.png deleted file mode 100644 index bc43229f..00000000 Binary files a/content/en/docs/3.5/release-notes/edge-stack-2.0.0-prune_routes.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/edge-stack-2.0.0-tlscontext.png b/content/en/docs/3.5/release-notes/edge-stack-2.0.0-tlscontext.png deleted file mode 100644 index 68dbad80..00000000 Binary files a/content/en/docs/3.5/release-notes/edge-stack-2.0.0-tlscontext.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/edge-stack-2.0.0-v3alpha1.png b/content/en/docs/3.5/release-notes/edge-stack-2.0.0-v3alpha1.png deleted file mode 100644 index c0ac3596..00000000 Binary files a/content/en/docs/3.5/release-notes/edge-stack-2.0.0-v3alpha1.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/emissary-1.13.10-cors-origin.png b/content/en/docs/3.5/release-notes/emissary-1.13.10-cors-origin.png deleted file mode 100644 index b7538e5f..00000000 Binary files a/content/en/docs/3.5/release-notes/emissary-1.13.10-cors-origin.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/emissary-ga.png b/content/en/docs/3.5/release-notes/emissary-ga.png deleted file mode 100644 index 062f043a..00000000 Binary files a/content/en/docs/3.5/release-notes/emissary-ga.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/tada.png b/content/en/docs/3.5/release-notes/tada.png deleted file mode 100644 index c8832e8e..00000000 Binary files a/content/en/docs/3.5/release-notes/tada.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/v2.0.4-k8s-1.22.png b/content/en/docs/3.5/release-notes/v2.0.4-k8s-1.22.png deleted file mode 100644 index ed9b0415..00000000 Binary files a/content/en/docs/3.5/release-notes/v2.0.4-k8s-1.22.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/v2.0.4-l7depth.png b/content/en/docs/3.5/release-notes/v2.0.4-l7depth.png deleted file mode 100644 index 9314324c..00000000 Binary files a/content/en/docs/3.5/release-notes/v2.0.4-l7depth.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/v2.0.4-mapping-dns-type.png b/content/en/docs/3.5/release-notes/v2.0.4-mapping-dns-type.png deleted file mode 100644 index 7770c77d..00000000 Binary files a/content/en/docs/3.5/release-notes/v2.0.4-mapping-dns-type.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/v2.0.4-v3alpha1.png b/content/en/docs/3.5/release-notes/v2.0.4-v3alpha1.png deleted file mode 100644 index 9c50b8fb..00000000 Binary files a/content/en/docs/3.5/release-notes/v2.0.4-v3alpha1.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/v2.0.4-version.png b/content/en/docs/3.5/release-notes/v2.0.4-version.png deleted file mode 100644 index 9481b7db..00000000 Binary files a/content/en/docs/3.5/release-notes/v2.0.4-version.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/v2.0.5-auth-circuit-breaker.png b/content/en/docs/3.5/release-notes/v2.0.5-auth-circuit-breaker.png deleted file mode 100644 index cac8cf7b..00000000 Binary files a/content/en/docs/3.5/release-notes/v2.0.5-auth-circuit-breaker.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/v2.0.5-mappingselector.png b/content/en/docs/3.5/release-notes/v2.0.5-mappingselector.png deleted file mode 100644 index 31942ede..00000000 Binary files a/content/en/docs/3.5/release-notes/v2.0.5-mappingselector.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/v2.1.0-canary.png b/content/en/docs/3.5/release-notes/v2.1.0-canary.png deleted file mode 100644 index 39d3bbbf..00000000 Binary files a/content/en/docs/3.5/release-notes/v2.1.0-canary.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/v2.1.0-gzip-enabled.png b/content/en/docs/3.5/release-notes/v2.1.0-gzip-enabled.png deleted file mode 100644 index 061fcbc9..00000000 Binary files a/content/en/docs/3.5/release-notes/v2.1.0-gzip-enabled.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/v2.1.0-smoother-migration.png b/content/en/docs/3.5/release-notes/v2.1.0-smoother-migration.png deleted file mode 100644 index ebd77497..00000000 Binary files a/content/en/docs/3.5/release-notes/v2.1.0-smoother-migration.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/v2.1.2-annotations.png b/content/en/docs/3.5/release-notes/v2.1.2-annotations.png deleted file mode 100644 index b5498c3c..00000000 Binary files a/content/en/docs/3.5/release-notes/v2.1.2-annotations.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/v2.1.2-host-mapping-matching.png b/content/en/docs/3.5/release-notes/v2.1.2-host-mapping-matching.png deleted file mode 100644 index 1cfba5ed..00000000 Binary files a/content/en/docs/3.5/release-notes/v2.1.2-host-mapping-matching.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/v2.1.2-mapping-cors.png b/content/en/docs/3.5/release-notes/v2.1.2-mapping-cors.png deleted file mode 100644 index f76ea01c..00000000 Binary files a/content/en/docs/3.5/release-notes/v2.1.2-mapping-cors.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/v2.1.2-mapping-less-weighted.png b/content/en/docs/3.5/release-notes/v2.1.2-mapping-less-weighted.png deleted file mode 100644 index 7e299062..00000000 Binary files a/content/en/docs/3.5/release-notes/v2.1.2-mapping-less-weighted.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/v2.1.2-mapping-no-rewrite.png b/content/en/docs/3.5/release-notes/v2.1.2-mapping-no-rewrite.png deleted file mode 100644 index 5d3d5a29..00000000 Binary files a/content/en/docs/3.5/release-notes/v2.1.2-mapping-no-rewrite.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/v2.2.0-cloud.png b/content/en/docs/3.5/release-notes/v2.2.0-cloud.png deleted file mode 100644 index 5923fcb4..00000000 Binary files a/content/en/docs/3.5/release-notes/v2.2.0-cloud.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/v2.2.0-percent-escape.png b/content/en/docs/3.5/release-notes/v2.2.0-percent-escape.png deleted file mode 100644 index df4d81b9..00000000 Binary files a/content/en/docs/3.5/release-notes/v2.2.0-percent-escape.png and /dev/null differ diff --git a/content/en/docs/3.5/release-notes/v2.2.0-tls-cert-validation.png b/content/en/docs/3.5/release-notes/v2.2.0-tls-cert-validation.png deleted file mode 100644 index f8635b5a..00000000 Binary files a/content/en/docs/3.5/release-notes/v2.2.0-tls-cert-validation.png and /dev/null differ diff --git a/content/en/docs/3.5/releaseNotes.yml b/content/en/docs/3.5/releaseNotes.yml deleted file mode 100644 index 61011d5e..00000000 --- a/content/en/docs/3.5/releaseNotes.yml +++ /dev/null @@ -1,1547 +0,0 @@ -# -*- fill-column: 100 -*- - -# This file should be placed in the folder for the version of the -# product that's meant to be documented. A `/release-notes` page will -# be automatically generated and populated at build time. -# -# Note that an entry needs to be added to the `doc-links.yml` file in -# order to surface the release notes in the table of contents. -# -# The YAML in this file should contain: -# -# changelog: An (optional) URL to the CHANGELOG for the product. -# items: An array of releases with the following attributes: -# - version: The (optional) version number of the release, if applicable. -# - date: The date of the release in the format YYYY-MM-DD. -# - notes: An array of noteworthy changes included in the release, each having the following attributes: -# - type: The type of change, one of `bugfix`, `feature`, `security` or `change`. -# - title: A short title of the noteworthy change. -# - body: >- -# Two or three sentences describing the change and why it -# is noteworthy. This is HTML, not plain text or -# markdown. It is handy to use YAML's ">-" feature to -# allow line-wrapping. -# - image: >- -# The URL of an image that visually represents the -# noteworthy change. This path is relative to the -# `release-notes` directory; if this file is -# `FOO/releaseNotes.yml`, then the image paths are -# relative to `FOO/release-notes/`. -# - docs: The path to the documentation page where additional information can be found. -# - href: A path from the root to a resource on the getambassador website, takes precedence over a docs link. - -changelog: https://github.com/emissary-ingress/emissary/blob/$branch$/CHANGELOG.md -items: - - 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.

- - Thanks to Pier. - - docs: https://github.com/emissary-ingress/emissary/blob/master/charts/emissary-ingress/CHANGELOG.md - - - version: 3.5.0 - date: '2023-02-15' - notes: - - title: Upgraded to golang 1.20.1 - type: security - body: >- - Upgraded to the latest release of Golang as part of our general dependency upgrade process. This includes - security fixes for CVE-2022-41725, CVE-2022-41723. - - title: TracingService support for native OpenTelemetry driver - type: feature - body: >- - In Envoy 1.24, experimental support for a native OpenTelemetry tracing driver was introduced that allows exporting spans in the otlp format. Many observability platforms accept that format and is the recommended replacement for the LightStep driver. $productName$ now supports setting the TracingService.spec.driver=opentelemetry to export traces in the otlp format.

- - Thanks to Paul for helping us get this tested and over the finish line! - - - title: Switch to a non-blocking readiness check - type: feature - body: >- - The /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).

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

- - Configure the listener port using 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.

- - In v2.Y/v3.Y+, the way $productName$ generates Envoy configuration changed to address memory pressure and improve route lookup speed in Envoy. However, when including a port in the hostname, an incorrect configuration was generated with an sni match including the port. This caused incoming request to never match causing a 404 Not Found.This has been fixed and the correct envoy configuration is - being generated which restores existing behavior. - - - title: Add support for resolving port names in Ingress resource - type: change - body: >- - Previously, specifying backend ports by name in Ingress was not supported and would result in defaulting to port 80. This allows $productName$ to now resolve port names for backend services. If the port number cannot be resolved by the name (e.g named port in the Service doesn't exist) then it will continue to default back - to port 80.

- - Thanks to Anton Ustyuzhanin!. - github: - - title: "#4809" - link: https://github.com/emissary-ingress/emissary/pull/4809 - - - title: Add starupProbe to emissary-apiext server - type: change - body: >- - The 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:

- - - Update default image to $productName$ v3.5.0.
- - Add support for configuring startupProbes on the emissary-ingress deployment.
- - Allow setting pod and container security settings on the Ambassador Agent.
- - Added deprecation notice in the values.yaml file for 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:

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

- - Users that are using $productName$ with Certificate Revocation List and allow external users to provide input should upgrade to ensure they are not vulnerable to CVE-2023-0286. - - - version: 3.4.0 - date: '2023-01-03' - notes: - - title: Upgrade to Envoy 1.24.1 - type: feature - body: >- - This upgrades $productName$ to be built on Envoy v1.24.1. Two notable changes were introduced:

- - First, the team at LightStep and the Envoy Maintainers have decided to no longer support the native LightStep tracing driver in favor of using the Open Telemetry driver. The code for the native Enovy LightStep driver has been removed from the Envoy code base. This means $productName$ will no longer support LightStep in the 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.

- - Second, a bug was fixed in Envoy 1.24 that changes how the upstream clusters distributed tracing 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.

- - This allows the healthcheck server to be configured to use IPv6-only k8s environments. (Thanks to Dmitry Golushko!). - docs: https://www.getambassador.io/docs/emissary/pre-release/topics/running/environment/ - - - 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 - - - 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. $productName$ does not expose any of these golang servers to external clients directly. - - - 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: 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 - - - 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 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: 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/content/en/docs/3.5/topics/concepts/architecture.md b/content/en/docs/3.5/topics/concepts/architecture.md deleted file mode 100644 index fe9e0bd3..00000000 --- a/content/en/docs/3.5/topics/concepts/architecture.md +++ /dev/null @@ -1,27 +0,0 @@ -# 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). - -![Architecture](../../images/ambassador-arch.png) - -## 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/content/en/docs/3.5/topics/concepts/gitops-continuous-delivery.md b/content/en/docs/3.5/topics/concepts/gitops-continuous-delivery.md deleted file mode 100644 index 336a1c66..00000000 --- a/content/en/docs/3.5/topics/concepts/gitops-continuous-delivery.md +++ /dev/null @@ -1,66 +0,0 @@ -# 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/content/en/docs/3.5/topics/concepts/index.md b/content/en/docs/3.5/topics/concepts/index.md deleted file mode 100644 index 2d02a027..00000000 --- a/content/en/docs/3.5/topics/concepts/index.md +++ /dev/null @@ -1,10 +0,0 @@ -# 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/content/en/docs/3.5/topics/concepts/kubernetes-network-architecture.md b/content/en/docs/3.5/topics/concepts/kubernetes-network-architecture.md deleted file mode 100644 index 2239a24f..00000000 --- a/content/en/docs/3.5/topics/concepts/kubernetes-network-architecture.md +++ /dev/null @@ -1,52 +0,0 @@ -# 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: - -
- -![Kubernetes Network Architecture](/../../images/documentation/kubernetes-network.inline.svg) - -
- -Each of the components in this topology is discussed in further detail below. - -### Load balancer - -The load balancer is deployed outside of the Kubernetes cluster. Typically, the load balancer also has one or more static IP addresses assigned to it. A DNS entry is then created to map a domain name (e.g., example.com) to the static IP address. - -Cloud infrastructure providers such as Amazon Web Services, Azure, Digital Ocean, and Google make it easy to create these load balancers directly from Kubernetes. This is done by creating a Kubernetes service of `type: LoadBalancer`. When this service is created, the cloud provider will use the metadata contained in the Kubernetes service definition to provision a load balancer. - -If the Kubernetes cluster is deployed in a private data center, an external load balancer is still generally used. Provisioning of this load balancer usually requires the involvement of the data center operations team. - -In both the private data center and cloud infrastructure case, the external load balancer should be configured to point to the edge proxy. - -### Edge Proxy / ingress controller - -The Edge Proxy is typically a Layer 7 proxy that is deployed directly in the cluster. The core function of the edge proxy is to accept incoming traffic from the external load balancer and route the traffic to Kubernetes services. The edge proxy should be configured using Kubernetes manifests. This enables a common management workflow for both the edge proxy and Kubernetes services. - -The most popular approach to configuring edge proxies is with the Kubernetes ingress resource. When an edge proxy can process ingress resources, it is called an ingress controller. Not all edge proxies are ingress controllers (because they can't process ingress resources), but all ingress controllers are edge proxies. - -The ingress resource is a Kubernetes standard. As such, it is a lowest common denominator resource. In practice, users find that the ingress resource is insufficient in scope to address the requirements for edge routing. Semantics such as TLS termination, redirecting to TLS, timeouts, rate limiting, and authentication are all beyond the scope of the ingress resource. - -$productName$ can function as an ingress controller (i.e., it reads ingress resources), although it also includes many other capabilities that are beyond the scope of the ingress specification. Most $productName$ users find that the various additional capabilities of $productName$ are essential, and end up using $productName$'s extensions to the ingress resource, instead of using ingress resources themselves. - -### Kubernetes services and Pods - -Each instance of your application is deployed in a Kubernetes pod. As the workload on your application increases or decreases, Kubernetes can automatically add or remove pods. A Kubernetes _service_ represents a group of pods that comprise the same version of a given application. Traffic can be routed to the pods via a Kubernetes service, or it can be routed directly to the pods. - -When traffic is routed to the pods via a Kubernetes service, Kubernetes uses a built-in mechanism called `kube-proxy` to load balance traffic between the pods. Due to its implementation, `kube-proxy` is a Layer 4 proxy, i.e., it load balances at a connection level. For particular types of traffic such as HTTP/2 and gRPC, this form of load balancing is particularly problematic as it can easily result in a very uneven load balancing configuration. - -Traffic can also be routed directly to pods, bypassing the Kubernetes service. Since pods are much more ephemeral than Kubernetes services, this approach requires an edge proxy that is optimized for this use case. In particular, the edge proxy needs to support real-time discovery of pods, and be able to dynamically update pod locations without downtime. - -$productName$ supports routing both to Kubernetes services and directly to pods. - -## Further reading - -* [Kubernetes Ingress 101](https://blog.getambassador.io/kubernetes-ingress-nodeport-load-balancers-and-ingress-controllers-6e29f1c44f2d) -* [Envoy Proxy Performance on Kubernetes](/resources/envoyproxy-performance-on-k8s/) diff --git a/content/en/docs/3.5/topics/concepts/microservices-api-gateways.md b/content/en/docs/3.5/topics/concepts/microservices-api-gateways.md deleted file mode 100644 index ba95b8fc..00000000 --- a/content/en/docs/3.5/topics/concepts/microservices-api-gateways.md +++ /dev/null @@ -1,60 +0,0 @@ -# Microservices API gateways - -A microservices API gateway is an API gateway designed to accelerate the development workflow of independent services teams. A microservices API gateway provides all the functionality for a team to independently publish, monitor, and update a microservice. - -This focus on accelerating the development workflow is distinct from the purpose of traditional API gateways, which focus on the challenges of managing APIs. Over the past decade, organizations have worked to expose internal systems through well-defined APIs. The challenge of safely exposing hundreds or thousands of APIs to end-users (both internal and external) led to the emergence of API gateways. Over time, API gateways have become centralized, mission critical pieces of infrastructure that control access to these APIs. - -In this article, we'll discuss how the difference in business objective (productivity vs management) results in a very different API gateway. - -## Microservices organization - -In a microservices organization, small teams of developers work independently from each other to rapidly deliver functionality to the customer. In order for each service team to work independently, with a productive workflow, a services team needs to be able to: - -1. Publish their service, so that others can use the service -2. Monitor their service, to see how well it's working -3. Test and update their service, so they can keep on improving the service - -The team needs to do all of this *without* requiring assistance from another operations or platform team--as soon as a services team requires another team, they're no longer working independently, and this can lead to bottlenecks. - -For service publication, a microservices API gateway provides a static address for consumers, and dynamically route requests to the appropriate service address. In addition, providing authentication and TLS termination for security are typical considerations in exposing a service to other consumers. - -Understanding the end-user experience of a service is crucial to improving the service. For example, a software update could inadvertently impact the latency of certain requests. A microservices API gateway is well situated to collect key observability metrics on end-user traffic as it routes traffic to the end service. - -A microservices API gateway also supports dynamically routing user requests to different service versions for canary testing. By routing a small fraction of end-user requests to a new version of a service, service teams can safely test the impact of new updates to a small subset of users. - -## Microservices API Gateways vs. enterprise API Gateways - -At first glance, the use case described above may be fulfilled with an enterprise-focused API gateway. While this may be true, the actual emphasis of enterprise API gateways and microservices API gateways are somewhat different: - -| Use case | Traditional Enterprise API gateway | Microservices API gateway | -|---------------|-------------------|------------------------------| -| Primary Purpose | Expose, compose, and manage internal business APIs | Expose and observe internal business services | -| Publishing Functionality | API management team or service team registers / updates gateway via admin API | Service team registers / updates gateway via declarative code as part of the deployment process | -| Monitoring | Admin and operations focused e.g. meter API calls per consumer, report errors (e.g. internal 5XX). | Developer focused e.g. latency, traffic, errors, saturation | -| Handling and Debugging Issues | L7 error-handling (e.g. custom error page or payload). Run gateway/API with additional logging. Troubleshoot issue in staging environment | Configure more detailed monitoring. Enable traffic shadowing and / or canarying | -| Testing | Operate multiple environments for QA, Staging, and Production. Automated integration testing, and gated API deployment. Use client-driven API versioning for compatibility and stability (e.g. semver) | Facilitate canary routing for dynamic testing (taking care with data mutation side effects). Use developer-driven service versioning for upgrade management | -| Local Development | Deploy gateway locally (via installation script, Vagrant or Docker), and attempt to mitigate infrastructure differences with production. Use language-specific gateway mocking and stubbing frameworks | Deploy gateway locally via service orchestration platform (e.g. Kubernetes) | - -## Self-service publishing - -A team needs to be able to publish a new service to customers without requiring an operations or API management team. This ability to self-service for deployment and publication enables the team to keep the feature release velocity high. While a traditional enterprise API gateway may provide a simple mechanism (e.g., REST API) for publishing a new service, in practice, the usage is often limited to the use of a dedicated team that is responsible for the gateway. The primary reason for limiting publication to a single team is to provide an additional (human) safety mechanism: an errant API call could have potentially disastrous effects on production. - -Microservices API gateways utilize mechanisms that enable service teams to easily *and* safely publish new services, with the inherent understanding that the producing team are responsible for their service, and will fix an issue if one occurs. A microservices gateway provides configurable monitoring for issue detection, and provides hooks for debugging, such as inspecting traffic or traffic shifting/duplication. - -## Monitoring and rate limiting - -A common business model for APIs is metering, where a consumer is charged different fees depending on API usage. Traditional enterprise API gateways excel in this use case: they provide functionality for monitoring per-client usage of an API, and the ability to limit usage when the client exceeds their quota. - -A microservice gateway also requires monitoring and rate limiting, but for different reasons. Monitoring user-visible metrics such as throughput, latency, and availability, are important to ensure that new updates don't impact the end-user. Robust end-user metrics are critical to allowing rapid, incremental updates. Rate limiting is used to improve the overall resilience of a service. When a service is not responding as expected, an API gateway can throttle incoming requests to allow a service to recover and prevent a cascade failure. - -## Testing and updates - -A microservices application has multiple services, each of which is being independently updated. Automated pre-production testing of a moving target is necessary but not sufficient for microservices. Canary testing, where a small percentage of production traffic is routed to a new service version, is an important tool to help test an update. By limiting a new service version to a small percentage of users, the impact of a service failure is limited. - -In a traditional enterprise API gateway, routing is used to isolate or compose/aggregate changing API versions. Automated pre-production testing and manual post-production verification and exploration are required. - -## Summary - -Traditional enterprise API gateways are designed to solve the challenges of API management. While they may appear to solve some of the challenges of adopting microservices, the reality is that a microservices workflow creates a different set of requirements. Integrating a microservices API gateway into your development workflow empowers service teams to self-publish, monitor, and update their service, quickly and safely. This will enable your organization to ship software more rapidly, and with more reliability than ever before. - -For further reading on how an API Gateway can accelerate continuous delivery, read [this blog post](https://blog.getambassador.io/continuous-delivery-how-can-an-api-gateway-help-or-hinder-1ff15224ec4d). diff --git a/content/en/docs/3.5/topics/concepts/progressive-delivery.md b/content/en/docs/3.5/topics/concepts/progressive-delivery.md deleted file mode 100644 index f2ade27f..00000000 --- a/content/en/docs/3.5/topics/concepts/progressive-delivery.md +++ /dev/null @@ -1,47 +0,0 @@ -# Progressive delivery - -Today's cloud-native applications may consist of hundreds of services, each of which are being updated at any time. Thus, many cloud-native organizations augment regression test strategies with testing in production using progressive delivery techniques. - -Progressive Delivery is an approach for releasing software to production users. In the progressive delivery model, software is released to ever growing subsets of production users. This approach reduces the blast radius in the event of a failure. - -## Why test in production? - -Modern cloud applications are continuously deployed, as different teams rapidly update their respective services. Deploying and testing updates in a pre-production staging environment introduces a bottleneck to the speed of iteration. More importantly, staging environments are not representative of what will be running in production when the deployment actually occurs given the velocity of service updates and changes in production. Testing in production addresses both of these challenges: developers evaluate their changes in the real-world environment, enabling rapid iteration. - -## Progressive delivery strategies - -There are a number of different strategies for progressive delivery. These include: - -* Feature flags, where specific features are made available to specific user groups -* Canary releases, where a (small) percentage of traffic is routed to a new version of a service before the service is full production -* Traffic shadowing, where real user traffic is copied, or shadowed, from production to the service under test - -Observability is a critical requirement for testing in production. Regardless of progressive delivery strategy, collecting key metrics around latency, traffic, errors, and saturation (the [“Four Golden Signals of Monitoring”](https://landing.google.com/sre/sre-book/chapters/monitoring-distributed-systems/#xref_monitoring_golden-signals)) provides valuable insight into the stability and performance of a new version of the service. Moreover, application developers can compare the metrics (e.g., latency) between the production version and an updated version. If the metrics are similar, then updates can proceed with much greater confidence. - -$productName$ supports a variety of strategies for progressive delivery. These strategies are discussed in further detail below. - -### Canary releases - -Canary releases shifts a small amount of real user traffic from production to the service under test. - -The user will see the direct response from the canary version of the service from any traffic that is shifted to the canary release, and they will not trigger or see the response from the current production released version of the service. The canary results can also be verified (both the downstream response and associated upstream side effects), but it is key to understand that any side effects will be persisted. - -In addition to allowing verification that the service is not crashing or otherwise behaving badly from an operational perspective when dealing with real user traffic and behavior, canary releasing allows user validation. For example, if a business KPI performs worse for all canaried requests, then this most likely indicates that the canaried service should not be fully released in its current form. - -Canary tests can be automated, and are typically run after testing in a pre-production environment has been completed. The canary release is only visible to a fraction of actual users, and any bugs or negative changes can be reversed quickly by either routing traffic away from the canary or by rolling-back the canary deployment. - -![Canary release process overview](../../images/canary-release-overview.png) - -Canary releases are not a panacea. In particular, many services may not receive sufficient traffic in order for canary releases to provide useful information in an actionable timeframe. - -### Traffic shadowing - -This approach “shadows” or mirrors a small amount of real user traffic from production to the service under test. - -Although the shadowed results can be verified (both the downstream response and associated upstream side effects) they are not returned to the user -- the user only sees the results from the currently released service. Typically any side effects are not persisted or are executed as a no-op and verified (much like setting up a mock, and verifying that a method/function was called with the correct parameters). - -This allows verification that the service is not crashing or otherwise behaving badly from an operational perspective when dealing with real user traffic and behavior (and the larger the percentage of traffic shadowed, the higher the probability of confidence). - -## Further reading - -* [Canary release pattern](https://blog.getambassador.io/cloud-native-patterns-canary-release-1cb8f82d371a) diff --git a/content/en/docs/3.5/topics/concepts/rate-limiting-at-the-edge.md b/content/en/docs/3.5/topics/concepts/rate-limiting-at-the-edge.md deleted file mode 100644 index f471b6d5..00000000 --- a/content/en/docs/3.5/topics/concepts/rate-limiting-at-the-edge.md +++ /dev/null @@ -1,33 +0,0 @@ -# Rate limiting concepts at the edge - -Rate limiting at the edge is a technique that is used to prevent a sudden or sustained increase in user traffic from breaking an API or underlying service. On the Internet, users can do whatever they want to your APIs, as you have no direct control over these end-users. Whether it’s intentional or not, these users can impact the availability, responsiveness, and scalability of your service. - -## Two approaches: Rate limiting and load shedding - -Rate limiting use cases that fall into this scenario range from implementing functional requirements related to a business scenario -- for example, where requests from paying customers is prioritized over requests from non-paying trial users -- to implementing cross-functional requirements, such as resilience from a malicious actor attempting to issue a denial-of-service (DoS) attack. - -A closely related technique to rate limiting is load shedding, and this can be used to selectively prioritize traffic (by dropping requests) based on the state of the entire system. For example, if a backend data store has become overloaded and slow to respond, it may be appropriate to drop (or “shed”) low priority requests or requests that are not time sensitive. - -## Use cases and scenarios - -The table below outlines several scenarios where rate limiting and load shedding can provide an effective solution to a range of functional and cross-functional requirements. The “Type of Rate Limiter” column provides a summary of the category of rate limiting that would be most appropriate for the scenario, and the “Specifics” column outlines what business or system properties would be involved in computing rate limiting decisions. - -| Scenario | Type of Rate Limiter |                            Specifics                        -| --- | --- | --- | -**Fairness.** One or more users are sending large volumes of requests, and thus impacting other users of the API | **User request rate limiting -** restricts each user to a predetermined number of requests per time unit.

**Concurrent user request limiting -** limits the number of concurrent user requests that can be inflight at any given point in time. |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
  • Geographic rate limiter
  • Time-based rate limiter
-**Prioritisation.** The business model depends on handling high priority requests over others | **User request rate limiting** |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device, free vs non-free user etc)
-**Resilience.** The API backend cannot scale rapidly enough to meet request demand due to a technical issue. | **Backend utilisation load shedder -** rate limit based upon utilisation of aggregate backend instances.

**Node/server utilisation load shedder -** rate limit based upon utilisation of individual or isolated groups of compute nodes/servers. |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
-**Security.** Prevent bad actors from using a DoS attack to overwhelm services, fuzzing, or brute force attacks |**User request rate limiting**

**Node/server utilisation load shedder** |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
  • Service identifier load shedder e.g. login service, audit service
-**Responsiveness.** As per the Reactive Manifesto, responsive systems focus on providing rapid and consistent response times, establishing reliable upper bounds so they deliver a consistent quality of service | **Concurrent user request limiting**

**Backend utilisation load shedder**

**Node/server utilisation load shedder** |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
  • Service identifier load shedder e.g. login service, audit service
- -## Avoiding contention with rate limiting configuration: Decoupling Dev and Ops - -One of the core features of $productName$ is the decentralization of configuration, allowing operations and development teams to independently control $productName$, as well as individual application development teams to minimize collaboration when configuring independently deployable services. This same approach applies to rate limiting configuration. - -The $productName$ rate limiting configuration allows centralized operations teams to define and implement global rate limiting and load shedding policies to protect the system, while still allowing individual application teams to define rate limiting policies that enforce business rules, for example, around paying and non-paying customers (perhaps implementing the so-called “freemium” model). See [Advanced Rate Limiting](../../../../2.0/howtos/advanced-rate-limiting) documentation for examples. - -## Benefits of applying a rate limiter to the edge - -Modern applications and APIs can experience floods of traffic over a short time period (e.g. from achieving a HackerNews front page link), and increasingly bad actors and cyber criminals are targeting public-facing services. - -By implementing rate limiting and load shedding capabilities at the edge, a large amount of scenarios that are bad for business can be mitigated. These capabilities also make the life of the operations and development team that much easier, as the need to constantly firefight ingress traffic is reduced. diff --git a/content/en/docs/3.5/topics/install/ambassador-oss-community.md b/content/en/docs/3.5/topics/install/ambassador-oss-community.md deleted file mode 100644 index b53d1407..00000000 --- a/content/en/docs/3.5/topics/install/ambassador-oss-community.md +++ /dev/null @@ -1,14 +0,0 @@ -# Integration in community projects - -import Table from "../../../../../src/components/CommunityTable"; - -**$AESproductName$ is now available and includes additional functionality beyond the current $OSSproductName$.** -These features include automatic HTTPS, OAuth/OpenID Connect authentication support, integrated rate -limiting, a developer portal, and [more](/edge-stack-faq/). - -## $OSSproductName$ integrations - -If you still want to use just $OSSproductName$, don't worry! $OSSproductName$ -is currently available out-of-the-box in some Kubernetes installers and local environments. - -
\ No newline at end of file diff --git a/content/en/docs/3.5/topics/install/bare-metal.md b/content/en/docs/3.5/topics/install/bare-metal.md deleted file mode 100644 index 84ac1c8d..00000000 --- a/content/en/docs/3.5/topics/install/bare-metal.md +++ /dev/null @@ -1,93 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Install with bare metal - -In cloud environments, provisioning a readily available network load balancer with $productName$ is the best option for handling ingress into your Kubernetes cluster. When running Kubernetes on a bare metal setup, where network load balancers are not available by default, we need to consider different options for exposing $productName$. - -## Exposing $productName$ via NodePort - -The simplest way to expose an application in Kubernetes is via a `NodePort` service. In this configuration, we create the $productName$ service] and identify `type: NodePort` instead of `LoadBalancer`. Kubernetes will then create a service and assign that service a port to be exposed externally and direct traffic to $productName$ via the defined `port`. - -```yaml ---- -apiVersion: v1 -kind: Service -metadata: - name: ambassador -spec: - type: NodePort - ports: - - name: http - port: 8088 - targetPort: 8080 - nodePort: 30036 # Optional: Define the port you would like exposed - protocol: TCP - selector: - service: ambassador -``` - -Using a `NodePort` leaves $productName$ isolated from the host network, allowing the Kubernetes service to handle routing to $productName$ pods. You can drop-in this YAML to replace the `LoadBalancer` service in the [YAML installation guide](../yaml-install) and use `http://:/` as the host for requests. - -## Exposing $productName$ via host network - -When running $productName$ on a bare metal install of Kubernetes, you have the option to configure $productName$ pods to use the network of the host they are running on. This method allows you to bind $productName$ directly to port 80 or 443 so you won't need to identify the port in requests. - -i.e `http://:/` becomes `http:///` - -This can be configured by setting `hostNetwork: true` in the $productName$ deployment. `dnsPolicy: ClusterFirstWithHostNet` will also need to set to tell $productName$ to use *KubeDNS* when attempting to resolve mappings. - -```diff ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: ambassador -spec: - replicas: 1 - selector: - matchLabels: - service: ambassador - template: - metadata: - annotations: - sidecar.istio.io/inject: "false" - labels: - service: ambassador - app.kubernetes.io/managed-by: getambassador.io - spec: -+ hostNetwork: true -+ dnsPolicy: ClusterFirstWithHostNet - serviceAccountName: ambassador - containers: - - name: ambassador - image: docker.io/datawire/ambassador:$version$ - resources: - limits: - cpu: 1 - memory: 400Mi - requests: - cpu: 200m - memory: 100Mi - env: - - name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace - livenessProbe: - httpGet: - path: /ambassador/v0/check_alive - port: 8877 - initialDelaySeconds: 30 - periodSeconds: 3 - readinessProbe: - httpGet: - path: /ambassador/v0/check_ready - port: 8877 - initialDelaySeconds: 30 - periodSeconds: 3 - restartPolicy: Always -``` - -This configuration does not require a defined $productName$ service, so you can remove that service if you have defined one. - -**Note:** Before configuring $productName$ with this method, consider some of the functionality that is lost by bypassing the Kubernetes service including only having one $productName$ able to bind to port 8080 or 8443 per node and losing any load balancing that is typically performed by Kubernetes services. diff --git a/content/en/docs/3.5/topics/install/convert-to-v3alpha1.md b/content/en/docs/3.5/topics/install/convert-to-v3alpha1.md deleted file mode 100644 index 2d8dfb79..00000000 --- a/content/en/docs/3.5/topics/install/convert-to-v3alpha1.md +++ /dev/null @@ -1,275 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Convert Configuration to `getambassador.io/v3alpha1` - -Once your $productName$ $version$ installation is running, it is **strongly recommended** that -you convert your existing configuration resources from `getambassador.io/v2` to -`getambassador.io/v3alpha1`. - - - While it is not necessary to convert all your resources to getambassador.io/v3alpha1 - immediately, you should ultimately update them all for full functionality with $productName$ - - -In general, the best way to convert any resource is to start with `kubectl get`: using -`kubectl get -o yaml` on any `getambassador.io/v2` resource will cause $productName$ to -translate it to a `getambassador.io/v3alpha1` resource. You can then verify that the -`getambassador.io/v3alpha1` resource looks correct and re-apply it, which will convert the -stored copy to `getambassador.io/v3alpha1`. - -As you do the conversion, here are the things to bear in mind: - -## 1. `ambassador_id` must be an array, not a simple string. - -`getambassador.io/v2` allowed `ambassador_id` to be either an array of strings, or a simple -string. In `getambassador.io/v3alpha1`, only the array form is supported: instead of -`ambassador_id: "foo"`, use `ambassador_id: [ "foo" ]`. This applies to all $productName$ -resources, and is supported by all versions of Ambassador 1.X. - -## 2. You must have a `Listener` for each port on which $productName$ should listen. - - - Learn more about Listener - - -`Listener` is **mandatory**. Defining your own `Listener`(s) allows you to carefully -tailor the set of ports you actually need to use, and exactly which `Host` resources -are matched with them (see below). - -## 3. `Listener`, `Host`, and `Mapping` must be explicit about how they associate. - -You need to have `Listener`s, `Host`s, and `Mapping`s correctly associated with each other for $productName$ 2.X configuration. - -### 3.1. `Listener` and `Host` are associated through `Listener.hostBinding` - - - Learn more about Listener
- Learn more about Host - - -In a `Listener`, the `hostBinding` controls whether a given `Host` is associated with that `Listener`, as discussed in the [`Listener`](../../running/listener) documentation. -**The recommended setting is using `hostBinding.selector`** to choose only `Host`s that have a defined -Kubernetes label: - -```yaml -hostBinding: - selector: - matchLabels: - my-listener: listener-8080 -``` - -The above example shows a `Listener` configured to associate only with `Host`s that have a `my-listener: listener-8080` label. - -For migration purposes, it is possible to have a `Listener` associate with all of the `Host`s. This is not recommended for production environments, however, as it can resulting confusing behavior with large numbers of `Host`s, and it -can also result in larger Envoy configurations that slow reconfiguration. - -```yaml -hostBinding: - namespace: - from: ALL -``` - -but **this is not recommended in production**. Allowing every `Host` to associate -with every `Listener` can result in confusing behavior with large numbers of `Host`s, and it -can also result in larger Envoy configurations that slow reconfiguration. - -### 3.2. `Host` and `Mapping` are associated through `Host.mappingSelector` - - -In $productName$ 1.X, `Mapping`s were nearly always associated with every `Host`. Since this -tends to result in larger Envoy configurations that slow down reconfiguration, $productName$ 2.X -inverts this behavior: **`Host` and `Mapping` will not associate without explicit selection**. - -To have a `Mapping` associate with a `Host`, at least one of the following must hold: - -- Recommended: The `Host` must define a `mappingSelector` that matches a `label` on the `Mapping`. -- Alternately, the `Mapping` must define `hostname` that matches the `hostname` of the `Host`. - (Note that the `hostname` of both `Host` and `AmbasssadorMapping` is a DNS glob.) - -If the `Host` defines a `mappingSelector` and the `Mapping` also defines a `hostname`, both must match. - -As a migration aid: - -- A `Mapping` with a `hostname` of `"*"` will associate with any `Host` that -has no `mappingSelector`, and -- A `v3alpha1` `Mapping` will honor `host` if `hostname` is not present. - - - Learn more about Host
- Learn more about Mapping - - - - A Mapping that specifies host_regex: true is associated with  - all Hosts. This is generally far less desirable than using hostname - with a DNS glob. - - - - Support for host and host_regex will be removed before - v3alpha1 is promoted to v3. - - -## 4. Use `Host` to terminate TLS - - - Learn more about Host
- Learn more about TLSContext - - -In $productName$ 1.X, simply creating a `TLSContext` is sufficient to terminate TLS, but in -2.X you _must_ use a `Host`. The minimal setup to terminate TLS is now something like this: - -```yaml ---- -apiVersion: v1 -kind: Secret -metadata: - name: my-secret -type: kubernetes.io/tls -data: - tls.crt: base64-PEM - tls.key: base64-PEM ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: my-host -spec: - hostname: host.example.com - tlsSecret: my-secret -``` - -In the example above, TLS is terminated for `host.example.com`. A `TLSContext` is still right way to share data -about TLS configuration across `Host`s: set both `tlsSecret` and `tlsContext` in the `Host`. - -## 5. `Mapping` should use `hostname` if possible - - - Learn more about Mapping - - -The `getambassador.io/v3alpha1` `Mapping` introduces the new `hostname` element, which is always -a DNS glob. Using `hostname` instead of `host` is **strongly recommended** unless you absolutely -require regular expression matching: - -- if `host` is being used for an exact match, simply rename `host` to `hostname`. -- if `host` is being used for a regex that effects a prefix or suffix match, rename it - to `hostname` and rewrite the regex into a DNS glob, e.g. `host: .*\.example\.com` would become - `hostname: *.example.com`. - -Additionally, when `hostname` is used, the `Mapping` will be associated with a `Host` only -if `hostname` matches the hostname of the `Host`. If the `Host`'s `selector` is also set, -both the `selector` and the hostname must line up. - - - An 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. - - -## 6. `Mapping` added headers must not be simple strings - - - Learn more about Mapping - - -The `getambassador.io/v2` `Mapping` supported strings and dictionaries for `add_request_headers` and -`add_response_headers`, for example: - -```yaml -add_request_headers: - X-Add-String: bar - X-Add-Dict: - value: bar -``` - -In `getambassador.io/v2`, both `X-Add-String` and `X-Add-Dict` will be added with the value `bar`. - -The string form - shown with `X-Add-String` - is not supported in `getambassador.io/v3alpha1`. Use the -dictionary form instead (which works in both `getambassador.io/v2` and `getambassador.io/v3alpha1`). - -## 7. `Mapping` `headers` and `query_parameters` must not be `true` - - - Learn more about Mapping - - -`headers` and `query_parameters` in a `Mapping` control header matches and query-parameter matches. In -`getambassador.io/v2`, they support both strings and dictionaries, and each has a `_regex` variant. -For example: - - ```yaml - headers: - x-exact-match: foo - x-existence-match: true - headers_regex: - x-regex-match: "fo.*o" - ``` - -In this example, the `Mapping` requires the `x-exact-match` header to have the value `foo`, the -`x-regex-match` whose value starts with `fo` and ends with `o`. However, `x-existence-match` requires -simply that the `x-existence-match` header exists. - -In `getambassador.io/v3alpha1`, the `true` value for an existence match is not supported. Instead, -use `headers_regex` for the same header with value of `.*`. This is fully supported in 1.k) - -`query_parameters` and `query_parameters_regex` work exactly like `headers` and `headers_reex`. - -## 8. `Mapping` `labels` must be converted to new syntax - - - Learn more about Mapping - - -In `getambassador.io/v2`, the `labels` element in a `Mapping` supported several different types of -data. In `getambassador.io/v3alpha1`, all labels must have the same type, so labels must be converted -to the new syntax: - -| `getambassador.io/v2` | `getambassador.io/v3alpha1` | -| -------------------------------- | ----------------------------------------------------------- | -| `source_cluster` | `{ source_cluster: { key: source_cluster } }` | -| `destination_cluster` | `{ destination_cluster: { key: destination_cluster }` } | -| `remote_address` | `{ remote_address: { key: remote_address } }` | -| `{ my_key: { header: my_hdr } }` | `{ generic_key: { value: my_val } }` | -| `{ my_val }` | `{ generic_key: { value: my_val } }` | -| `{ my_key: { header: my_hdr } }` | `{ request_headers: { key: my_key, header_name: my_hdr } }` | - -You can check the [Rate Limiting Labels documentation](../../using/rate-limits#attaching-labels-to-requests) -for more examples. - -## 9. `tls` cannot be `true` in `AuthService`, `Mapping`, `RateLimitService`, and `TCPMapping` - - - Learn more about AuthService
- Learn more about Mapping
- Learn more about RateLimitService
- Learn more about TCPMapping - - -The `tls` element in `AuthService`, `Mapping`, `RateLimitService`, and `TCPMapping` controls TLS -origination. In `getambassador.io/v2`, it may be a string naming a `TLSContext` to use to determine -which client certificate is sent, or the boolean value `true` to request TLS origination with no -cluent certificate being sent. - -In `getambassador.io/v3alpha1`, only the string form is supported. To originate TLS with no client -certificate (the semantic of `tls: true`), omit the `tls` element and prefix the `service` with -`https://`. Note that `TCPMapping` in `getambassador.io/v2` does not support the `https://prefix`. - -## 10. Some `Module` settings have moved or changed - - - Learn more about Listener - - -A few settings have moved from the `Module` in 2.0. Make sure you review the following settings -and move them to their new locations if you are using them in a `Module`: - -- Configuration for the `PROXY` protocol is part of the `Listener` resource in $productName$ 2.0, -so the `use_proxy_protocol` element of the `ambassador` `Module` is no longer supported. - -- `xff_num_trusted_hops` has been removed from the `Module`, and its functionality has been moved -to the `l7Depth` setting in the `Listener` resource. - -- It is no longer possible to configure TLS using the `tls` element of the `Module`. Its -functionality is fully covered by the `TLSContext` resource. diff --git a/content/en/docs/3.5/topics/install/docker.md b/content/en/docs/3.5/topics/install/docker.md deleted file mode 100644 index e430a55c..00000000 --- a/content/en/docs/3.5/topics/install/docker.md +++ /dev/null @@ -1,73 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Run the demo with Docker - -In this Docker quickstart guide, we'll get $productName$ running locally -with a demo configuration. In the next section, we'll then walk through how to -deploy $productName$ in Kubernetes with a custom configuration. - -## 1. Running the demo configuration - -By default, $productName$ uses a demo configuration to show some of its basic features. Get it running with Docker, and expose $productName$ on port 8080: - -``` -docker run -it -p 8080:8080 --name=$productDeploymentName$ --rm docker.io/emissaryingress/emissary:$version$ --demo -``` - -## 2. $productName$'s diagnostics - -$productName$ provides live diagnostics viewable with a web browser. While this would normally not be exposed to the public network, the Docker demo publishes the diagnostics service at the following URL: - -`http://localhost:8080/ambassador/v0/diag/` - -You'll have to authenticate to view this page: use the username `admin`, -password `admin` (obviously this would be a poor choice in the real world!). -We'll talk more about authentication shortly. - -To access the Diagnostics page with authentication, use `curl http://localhost:8080/ambassador/v0/diag/ -u admin:admin` - -Some of the most important information - your $productName$ version, how recently $productName$'s configuration was updated, and how recently Envoy last reported status to $productName$ - is right at the top. The diagnostics overview can show you what it sees in your configuration map, and which Envoy objects were created based on your configuration. - -## 3. The Quote service - -Since $productName$ is a comprehensive, self-service edge stack, its primary purpose is to provide access and control to microservices for the teams that manage them. The demo is preconfigured with a mapping that connects the `/qotm/` resource to the "Quote" service -- a demo service that supplies quotations. You can try it out by opening - -`http://localhost:8080/qotm/` - -in your browser, or from the command line as - -``` -curl -L 'http://localhost:8080/qotm/?json=true' -``` - -This request will route to the `qotm` service at `demo.getambassador.io`, and return a random quote. - -You can see details of the mapping by clicking the blue `http://localhost:8080/qotm/` link at the very bottom of the `Ambassador Route Table` in the diagnostics overview. - -## 4. Authentication - -On the diagnostic overview, you can also see that $productName$ is configured to do authentication -- in the middle of the overview page, you'll see the `Ambassador Services In Use` section, and you can click the `tcp://127.0.0.1:5050` link for details on the `AuthService` configuration. This demo auth service is running inside the Docker container with $productName$ and the Quote service, and $productName$ uses it to mediate access to everything behind $productName$. - -You saw above that access to the diagnostic overview required you to authenticate as an administrator. Getting a random quote does not require authentication, but to get a specific quote, you'll have to authenticate as a demo user. To see this in action, open - -`http://localhost:8080/qotm/quote/5` - -in your browser. From the command line, you can see that: - -``` -curl -Lv 'http://localhost:8080/qotm/quote/5?json=true' -``` - -will return a 401, but - -``` -curl -Lv -u username:password 'http://localhost:8080/qotm/quote/5?json=true' -``` - -will succeed. (Note that that's literally "username" and "password" -- the demo auth service is deliberately not very secure!) - -Note that it's up to the auth service to decide what needs authentication -- teaming $productName$ with an authentication service can be as flexible or strict as you need it to be. - -## Next steps - -We've just walked through some of the core features of $productName$ in a local configuration. To see $productName$ in action on Kubernetes, check out the [Installation Guide](../). diff --git a/content/en/docs/3.5/topics/install/helm.md b/content/en/docs/3.5/topics/install/helm.md deleted file mode 100644 index 4c8a9836..00000000 --- a/content/en/docs/3.5/topics/install/helm.md +++ /dev/null @@ -1,102 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Install with Helm - - - - To migrate from $productName$ 1.X to $productName$ 2.X, see the - [$productName$ migration matrix](../migration-matrix/). This guide - **will not work** for that, due to changes to the configuration - resources used for $productName$ 2.X. - - - -[Helm](https://helm.sh) is a package manager for Kubernetes that automates the release and management of software on Kubernetes. $productName$ can be installed via a Helm chart with a few simple steps, depending on if you are deploying for the first time, upgrading $productName$ from an existing installation, or migrating from $productName$. - -## Before you begin - -The $productName$ Helm chart is hosted by Datawire and published at `https://app.getambassador.io`. - -Start by adding this repo to your helm client with the following command: - -``` -helm repo add datawire https://app.getambassador.io -helm repo update -``` - -## Install with Helm - -When you run the Helm chart, it installs $productName$. - -1. Install the $productName$ CRDs. - - Before installing $productName$ $version$ itself, you must configure your - Kubernetes cluster to support the `getambassador.io/v3alpha1` and `getambassador.io/v2` - configuration resources. This is required. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. Install the $productName$ Chart with the following command: - - ``` - helm install -n $productNamespace$ --create-namespace \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - -3. Next Steps - - $productName$ shold now be successfully installed and running, but in order to get started deploying Services and test routing to them you need to configure a few more resources. - - - [The `Listener` Resource](../../running/listener/) is required to configure which ports the $productName$ pods listen on so that they can begin responding to requests. - - [The `Mapping` Resouce](../../using/intro-mappings/) is used to configure routing requests to services in your cluster. - - [The `Host` Resource](../../running/host-crd/) configures TLS termination for enablin HTTPS communication. - - Explore how $productName$ [configures communication with clients](../../../howtos/configure-communications) - - - We strongly recommend following along with our Quickstart Guide to get started by creating a Listener, deploying a simple service to test with, and setting up a Mapping to route requests from $productName$ to the demo service. - - - - $productName$ $version$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - -For more advanced configuration and details about helm values, -[please see the helm chart.](https://artifacthub.io/packages/helm/datawire/emissary-ingress/) - -## Upgrading an existing installation - -See the [migration matrix](../migration-matrix) for instructions about upgrading -$productName$. diff --git a/content/en/docs/3.5/topics/install/index.less b/content/en/docs/3.5/topics/install/index.less deleted file mode 100644 index bc649e7c..00000000 --- a/content/en/docs/3.5/topics/install/index.less +++ /dev/null @@ -1,57 +0,0 @@ -@media (max-width: 769px) { - #index-installContainer { - flex-direction: column; - } - .index-dropdown { - width: auto; - } - .index-dropBtn { - width: 100%; - } -} - -.index-dropBtn { - background-color: #8e77ff; - color: white; - padding: 10px; - font-size: 16px; - border: none; - margin-top: -20px; -} - -.index-dropdown { - position: relative; - display: inline-block; -} - -.index-dropdownContent { - display: none; - position: absolute; - background-color: #f1f1f1; - width: 100%; - box-shadow: 0px 8px 16px 0px rgba(0, 0, 0, 0.2); - z-index: 1; -} - -.index-dropdownContent a { - color: black; - padding: 12px 16px; - text-decoration: none; - display: block; -} - -.index-dropdownContent a:hover { - background-color: #ddd; -} - -.index-dropdown:hover .index-dropdownContent { - display: block; -} - -.index-dropdown:hover .index-dropBtn { - background-color: #5f3eff; -} - -#index-installContainer { - display: flex; -} diff --git a/content/en/docs/3.5/topics/install/index.md b/content/en/docs/3.5/topics/install/index.md deleted file mode 100644 index 40fa95fd..00000000 --- a/content/en/docs/3.5/topics/install/index.md +++ /dev/null @@ -1,47 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; -import './index.less' - -# Installing $productName$ - -## 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/content/en/docs/3.5/topics/install/migrate-to-2-alternate.md b/content/en/docs/3.5/topics/install/migrate-to-2-alternate.md deleted file mode 100644 index edc42916..00000000 --- a/content/en/docs/3.5/topics/install/migrate-to-2-alternate.md +++ /dev/null @@ -1,40 +0,0 @@ ---- - 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/content/en/docs/3.5/topics/install/migrate-to-3-alternate.md b/content/en/docs/3.5/topics/install/migrate-to-3-alternate.md deleted file mode 100644 index 3b9df0c1..00000000 --- a/content/en/docs/3.5/topics/install/migrate-to-3-alternate.md +++ /dev/null @@ -1,36 +0,0 @@ -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/content/en/docs/3.5/topics/install/migration-matrix.md b/content/en/docs/3.5/topics/install/migration-matrix.md deleted file mode 100644 index ed3b1b5c..00000000 --- a/content/en/docs/3.5/topics/install/migration-matrix.md +++ /dev/null @@ -1,46 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrading $productName$ - - - Read the instructions below before making any changes to your cluster! - - -There are currently multiple paths for upgrading $productName$, depending on what version you're currently -running, what you want to be running, and whether you installed $productName$ using [Helm](../helm) or -YAML. - -(To check out if you installed $productName$ using Helm, run `helm list --all` and see if -$productName$ is listed. If so, you installed using Helm.) - - - Read the instructions below before making any changes to your cluster! - - -## If you are currently running $AESproductName$ - -See the [instructions on updating $AESproductName$](/docs/edge-stack/$aesDocsVersion$/topics/install/migration-matrix/). - -## If you installed $OSSproductName$ using Helm - -| If you're running. | You can upgrade to | -|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------| -| $OSSproductName$ $version$ | [$AESproductName$ $aesVersion$](/docs/edge-stack/$aesDocsVersion$/topics/install/upgrade/helm/emissary-3.5/edge-stack-3.X/) | -| $OSSproductName$ 3.4.X | [$OSSproductName$ $version$](../upgrade/helm/emissary-3.4/emissary-3.X) | -| $OSSproductName$ $versionTwoX$ | [$OSSproductName$ $version$](../upgrade/helm/emissary-2.5/emissary-3.X) | -| $OSSproductName$ 2.4.X | [$OSSproductName$ $version$](../upgrade/helm/emissary-2.4/emissary-2.X) | -| $OSSproductName$ 2.0.5 | [$OSSproductName$ $versionTwoX$](../upgrade/helm/emissary-2.0/emissary-2.X) | -| $OSSproductName$ $versionOneX$ | [$OSSproductName$ $versionTwoX$](../upgrade/helm/emissary-1.14/emissary-2.X) | -| $OSSproductName$ prior to $versionOneX$ | [$OSSproductName$ $versionOneX$](../../../../1.14/topics/install/upgrading) | - -## If you installed $OSSproductName$ manually by applying YAML - -| If you're running. | You can upgrade to | -|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------| -| $OSSproductName$ $version$ | [$AESproductName$ $aesVersion$](/docs/edge-stack/$aesDocsVersion$/topics/install/upgrade/yaml/emissary-3.5/edge-stack-3.X/) | -| $OSSproductName$ 3.4.X | [$OSSproductName$ $version$](../upgrade/yaml/emissary-3.4/emissary-3.X) | -| $OSSproductName$ $versionTwoX$ | [$OSSproductName$ $version$](../upgrade/yaml/emissary-2.5/emissary-3.X) | -| $OSSproductName$ 2.4.X | [$OSSproductName$ $version$](../upgrade/yaml/emissary-2.4/emissary-2.X) | -| $OSSproductName$ 2.0.5 | [$OSSproductName$ $versionTwoX$](../upgrade/yaml/emissary-2.0/emissary-2.X) | -| $OSSproductName$ $versionOneX$ | [$OSSproductName$ $versionTwoX$](../upgrade/yaml/emissary-1.14/emissary-2.X) | -| $OSSproductName$ prior to $versionOneX$ | [$OSSproductName$ $versionOneX$](../../../../1.14/topics/install/upgrading) | diff --git a/content/en/docs/3.5/topics/install/upgrade/helm/emissary-1.14/emissary-2.X.md b/content/en/docs/3.5/topics/install/upgrade/helm/emissary-1.14/emissary-2.X.md deleted file mode 100644 index bd61fafc..00000000 --- a/content/en/docs/3.5/topics/install/upgrade/helm/emissary-1.14/emissary-2.X.md +++ /dev/null @@ -1,312 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 1.14.X (Helm) - - - This guide covers migrating from $productName$ 1.14.X to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -We're pleased to introduce $productName$ $versionTwoX$! The 2.X family introduces a number of -changes to allow $productName$ to more gracefully handle larger installations (including -multitenant or multiorganizational installations), reduce memory footprint, and improve -performance. In keeping with [SemVer](https://semver.org), $productName$ 2.X introduces -some changes that aren't backward-compatible with 1.X. These changes are detailed in -[Major Changes in $productName$ 2.X](../../../../../../about/changes-2.x/). - -## Migration Overview - - - Read the migration instructions below before making any changes to your - cluster! - - -The recommended strategy for migration is to run $productName$ 1.14 and $productName$ -$versionTwoX$ side-by-side in the same cluster. This gives $productName$ $versionTwoX$ -and $productName$ 1.14 access to all the same configuration resources, with some -important caveats: - -1. **$productName$ 1.14 will not see any `getambassador.io/v3alpha1` resources.** - - This is intentional; it provides a way to apply configuration only to - $productName$ $versionTwoX$, while not interfering with the operation of your - $productName$ 1.14 installation. - -2. **If needed, you can use labels to further isolate configurations.** - - If you need to prevent your $productName$ $versionTwoX$ installation from - seeing a particular bit of $productName$ 1.14 configuration, you can apply - a Kubernetes label to the configuration resources that should be seen by - your $productName$ $versionTwoX$ installation, then set its - `AMBASSADOR_LABEL_SELECTOR` environment variable to restrict its 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$ $versionTwoX$, then set - `AMBASSADOR_LABEL_SELECTOR=version-two=true` in its Deployment. - -3. **Be careful about label selectors on Kubernetes Services!** - - If you have services in $productName$ 1.14 that use selectors that will match - Pods from $productName$ $versionTwoX$, traffic will be erroneously split between - $productName$ 1.14 and $productName$ $versionTwoX$. The labels used by $productName$ - $versionTwoX$ include: - - ```yaml - app.kubernetes.io/name: emissary-ingress - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/part-of: emissary-ingress - app.kubernetes.io/managed-by: getambassador.io - product: aes - profile: main - ``` - -4. **Be careful to only have one $productName$ Agent running at a time.** - - The $productName$ Agent is responsible for communications between - $productName$ and Ambassador Cloud. If multiple versions of the Agent are - running simultaneously, Ambassador Cloud could see conflicting information - about your cluster. - - The best way to avoid multiple agents when installing with Helm is to use - `--set agent.enabled=false` to tell Helm not to install a new Agent with - $productName$ $versionTwoX$. Once testing is done, you can switch Agents safely. - -You can also migrate by [installing $productName$ $versionTwoX$ in a separate cluster](../../../../migrate-to-2-alternate). -This permits absolute certainty that your $productName$ 1.14 configuration will not be -affected by changes meant for $productName$ $versionTwoX$, and it eliminates concerns about -ACME, but it is more effort. - -## Side-by-Side Migration Steps - -Migration is a seven-step process: - -1. **Make sure that older configuration resources are not present.** - - $productName$ 2.X does not support `getambassador.io/v0` or `getambassador.io/v1` - resources, and Kubernetes will not permit removing support for CRD versions that are - still in use for stored resources. To verify that no resources older than - `getambassador.io/v2` are active, run - - ``` - kubectl get crds -o 'go-template={{range .items}}{{.metadata.name}}={{.status.storedVersions}}{{"\n"}}{{end}}' | fgrep getambassador.io - ``` - - If `v1` is present in the output, **do not begin migration.** The old resources must be - converted to `getambassador.io/v2` and the `storedVersion` information in the cluster - must be updated. If necessary, contact Ambassador Labs on [Slack](http://a8r.io/slack) - for more information. - -2. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you must configure your - Kubernetes cluster to support its new `getambassador.io/v3alpha1` configuration - resources. Note that `getambassador.io/v2` resources are still supported, but **you - must install support for `getambassador.io/v3alpha1`** to run $productName$ $versionTwoX$, - even if you intend to continue using only `getambassador.io/v2` resources for some - time. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -3. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, you need to install $productName$ $versionTwoX$ itself - **in the same namespace as your existing $productName$ 1.14 installation**. It's important - to use the same namespace so that the two installations can see the same secrets, etc. - - Start by making sure that your `emissary` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Typically, $productName$ 1.14 was installed in the `ambassador` namespace. If you installed - $productName$ 1.14 in a different namespace, change the namespace in the commands below. - - - If you do not need to set `AMBASSADOR_LABEL_SELECTOR`: - - ```bash - helm install -n ambassador \ - --set agent.enabled=false \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - - - If you do need to set `AMBASSADOR_LABEL_SELECTOR`, use `--set`, for example: - - ```bash - helm install -n ambassador \ - --set agent.enabled=false \ - --set env.AMBASSADOR_LABEL_SELECTOR="version-two=true" \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 2.X. - Do not use the ambassador Helm chart. - - - - $productName$ $versionTwoX$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - -4. **Install `Listener`s and `Host`s as needed.** - - An important difference between $productName$ 1.14 and $productName$ $versionTwoX$ is the - new **mandatory** `Listener` CRD. Also, when running both installations side by side, - you will need to make sure that a `Host` is present for the new $productName$ $versionTwoX$ - Service. For example: - - ```bash - kubectl apply -f - < - Kubernetes will not allow you to have a 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.
-
- If you find that your $productName$ $versionTwoX$ installation and your $productName$ 1.14 - installation absolutely must have resources that are only seen by one version or the - other way, see overview section 2, "If needed, you can use labels to further isolate configurations". - - - **If you find that you need to roll back**, just reinstall your 1.14 CRDs and delete your - installation of $productName$ $versionTwoX$. - -6. **When ready, switch over to $productName$ $versionTwoX$.** - - You can run $productName$ 1.14 and $productName$ $versionTwoX$ side-by-side as long as you care - to. However, taking full advantage of $productName$ 2.X's capabilities **requires** - [updating your configuration to use `getambassador.io/v3alpha1` configuration resources](../../../../convert-to-v3alpha1), - since some useful features in $productName$ $versionTwoX$ are only available using - `getambassador.io/v3alpha1` resources. - - When you're ready to have $productName$ $versionTwoX$ handle traffic on its own, switch - your original $productName$ 1.14 Service to point to $productName$ $versionTwoX$. Use - `kubectl edit service ambassador` and change the `selectors` to: - - ``` - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/name: emissary-ingress - profile: main - ``` - - Repeat using `kubectl edit service ambassador-admin` for the `ambassador-admin` - Service. - -7. **Finally, install the $productName$ $versionTwoX$ Ambassador Agent.** - - First, scale the 1.14 agent to 0: - - ``` - kubectl scale -n ambassador deployment/ambassador-agent --replicas=0 - ``` - - Once that's done, install the new Agent. **Note that if you needed to set - `AMBASSADOR_LABEL_SELECTOR`, you must add that to this `helm upgrade` command.** - - ```bash - helm upgrade -n ambassador \ - --set agent.enabled=true \ - $productHelmName$ datawire/$productHelmName$ \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - -Congratulations! At this point, $productName$ $versionTwoX$ is fully running and it's safe to remove the `ambassador` and `ambassador-agent` Deployments: - -``` -kubectl delete deployment/ambassador deployment/ambassador-agent -``` - -Once $productName$ 1.14 is no longer running, you may [convert](../../../../convert-to-v3alpha1) -any remaining `getambassador.io/v2` resources to `getambassador.io/v3alpha1`. -You may also want to redirect DNS to the `edge-stack` Service and remove the -`ambassador` Service. diff --git a/content/en/docs/3.5/topics/install/upgrade/helm/emissary-2.0/emissary-2.X.md b/content/en/docs/3.5/topics/install/upgrade/helm/emissary-2.0/emissary-2.X.md deleted file mode 100644 index c0a392f1..00000000 --- a/content/en/docs/3.5/topics/install/upgrade/helm/emissary-2.0/emissary-2.X.md +++ /dev/null @@ -1,75 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.0.5 (Helm) - - - This guide covers migrating from $productName$ 2.0.5 to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster; Helm will not do this for you. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, use Helm to install $productName$ $versionTwoX$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 2.X. - Do not use the ambassador Helm chart. - diff --git a/content/en/docs/3.5/topics/install/upgrade/helm/emissary-2.4/emissary-2.X.md b/content/en/docs/3.5/topics/install/upgrade/helm/emissary-2.4/emissary-2.X.md deleted file mode 100644 index 3e44b511..00000000 --- a/content/en/docs/3.5/topics/install/upgrade/helm/emissary-2.4/emissary-2.X.md +++ /dev/null @@ -1,75 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.4.Z (Helm) - - - This guide covers migrating from $productName$ 2.4.Z to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster; Helm will not do this for you. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, use Helm to install $productName$ $versionTwoX$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 2.X. - Do not use the ambassador Helm chart. - diff --git a/content/en/docs/3.5/topics/install/upgrade/helm/emissary-2.5/emissary-3.X.md b/content/en/docs/3.5/topics/install/upgrade/helm/emissary-2.5/emissary-3.X.md deleted file mode 100644 index d8439c5a..00000000 --- a/content/en/docs/3.5/topics/install/upgrade/helm/emissary-2.5/emissary-3.X.md +++ /dev/null @@ -1,153 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.5.Z (Helm) - - - This guide covers migrating from $productName$ 2.5.Z to $productName$ $version$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - - - Make sure that you have updated any 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$. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -$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. - -### Resources to check before migrating to $version$. - -$productName$ 3.X has been upgraded from Envoy 1.17.X to Envoy 1.22 which removed support for the Envoy V2 Transport Protocol. This means all `AuthService`, `RatelimitService`, and `LogServices` must be updated to use the V3 Protocol. Additionally support for some of the runtime bootstrap flags has been removed. - -You can refer to the [Major changes in $productName$ 3.x](../../../../../../about/changes-3.y/) guide for an overview of the changes. - -1. $productName$ 3.2 fixed a bug with `Host.spec.selector\mappingSelector` and `Listener.spec.selector` not being properly enforced. - In previous versions, if only a single label from the selector was present on the resource then they would be associated. Additionally, when associating `Hosts` with `Mappings`, if the `Mapping` configured a `hostname` that matched the `hostname` of the `Host` then they would be associated regardless of the configuration of the `selector\mappingSelector` on the `Host`. - - Before upgrading, review your Ambassador resources, and if you make use of the selectors, ensure that every other resource you want it to be associated with contains all the required labels. - - The environment variable `DISABLE_STRICT_LABEL_SELECTORS` can be set to `"true"` on the $productName$ deployment to revert to the - old incorrect behavior to help prevent any configuration issues after upgrading in the event that not all manifests making use of the selectors have been corrected yet. - - For more information on `DISABLE_STRICT_LABEL_SELECTORS` see the [Environment Variables page](../../../../../running/environment). - -2. Check Transport Protocol usage on all resources before migrating. - - The `AuthService`, `RatelimitService`, and `LogServices` 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. - - `protocol_version` should be updated to `v3` for all of the above resources while still running $productName$ $versionTwoX$. As of version `2.3.z`+, support for `protocol_version` `v2` and `v3` is supported in order to allow migration from `protocol_version` `v2` to `v3` before upgrading to $productName$ $version$ where support for `v2` is removed. - - Upgrading any application code for your own implementations of these services is very straightforward. - - The following imports simply need to be updated to switch from Envoy's Transport Protocol `v2` to `v3`, and then the configuration for these resources can be updated to add the `protocl_version: "v3"` when the updated service is deployed. - - `v2` Imports: - ```golang - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" - ``` - - `v3` Imports: - ```golang - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" - ``` - -3. Check removed runtime changes - - ```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, - - # Developers 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, - ``` - -4. Support for LightStep tracing driver removed - - - As of $productName$ 3.4.Z, the LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read before upgrading. - - -$productName$ 3.4 is based on Envoy 1.24.1 which removed support for the `LightStep` tracing driver. The team at LightStep and the maintainers of Envoy-Proxy recommend that users instead leverage the OpenTelemetry Collector to send tracing information to LightStep. We have written a guide which can be found here Distributed Tracing with OpenTelemetry and Lightstep that outlines how to set this up. **It is important that you follow this upgrade path prior to upgrading or you will drop tracing data.** - -## Migration Steps - -Migration is a two-step process: - -1. **Install new CRDs.** - - After reviewing the changes in 3.x and confirming that you are ready to upgrade, the process is the same as upgrading minor versions - in previous version of $productName$ and does not require the complex migration steps that the migration from 1.x tto 2.x required. - - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $version$.** - - After installing the new CRDs, use Helm to install $productName$ $version$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 3.Y. - diff --git a/content/en/docs/3.5/topics/install/upgrade/helm/emissary-3.4/emissary-3.X.md b/content/en/docs/3.5/topics/install/upgrade/helm/emissary-3.4/emissary-3.X.md deleted file mode 100644 index f5b4e26d..00000000 --- a/content/en/docs/3.5/topics/install/upgrade/helm/emissary-3.4/emissary-3.X.md +++ /dev/null @@ -1,87 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 3.4.Z (Helm) - - - This guide covers migrating from $productName$ 3.4.Z to $productName$ $version$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -### Resources to check before migrating to $version$. - - - As of $productName$ 3.4.Z, the LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read below before upgrading. - - -$productName$ 3.4 has been upgraded from Envoy 1.23 to Envoy 1.24.1 which removed support for the `LightStep` tracing driver. The team at LightStep and the maintainers of Envoy-Proxy recommend that users instead leverage the OpenTelemetry Collector to send tracing information to LightStep. We have written a guide which can be found here Distributed Tracing with OpenTelemetry and Lightstep that outlines how to set this up. **It is important that you follow this upgrade path prior to upgrading or you will drop tracing data.** - -## Migration Steps - -Migration is a two-step process: - -1. **Install new CRDs.** - - After reviewing the changes in 3.x and confirming that you are ready to upgrade, the process is the same as upgrading minor versions - in previous version of $productName$ and does not require the complex migration steps that the migration from 1.x tto 2.x required. - - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $version$.** - - After installing the new CRDs, use Helm to install $productName$ $version$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 3.Y. - diff --git a/content/en/docs/3.5/topics/install/upgrade/yaml/emissary-1.14/emissary-2.X.md b/content/en/docs/3.5/topics/install/upgrade/yaml/emissary-1.14/emissary-2.X.md deleted file mode 100644 index eb1dcf6c..00000000 --- a/content/en/docs/3.5/topics/install/upgrade/yaml/emissary-1.14/emissary-2.X.md +++ /dev/null @@ -1,282 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 1.14.X (YAML) - - - This guide covers migrating from $productName$ 1.14.X to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -We're pleased to introduce $productName$ $versionTwoX$! The 2.X family introduces a number of -changes to allow $productName$ to more gracefully handle larger installations (including -multitenant or multiorganizational installations), reduce memory footprint, and improve -performance. In keeping with [SemVer](https://semver.org), $productName$ 2.X introduces -some changes that aren't backward-compatible with 1.X. These changes are detailed in -[Major Changes in $productName$ 2.X](../../../../../../about/changes-2.x/). - -## Migration Overview - - - Read the migration instructions below before making any changes to your - cluster! - - -The recommended strategy for migration is to run $productName$ 1.14 and $productName$ -$versionTwoX$ side-by-side in the same cluster. This gives $productName$ $versionTwoX$ -and $productName$ 1.14 access to all the same configuration resources, with some -important caveats: - -1. **$productName$ 1.14 will not see any `getambassador.io/v3alpha1` resources.** - - This is intentional; it provides a way to apply configuration only to - $productName$ $versionTwoX$, while not interfering with the operation of your - $productName$ 1.14 installation. - -2. **If needed, you can use labels to further isolate configurations.** - - If you need to prevent your $productName$ $versionTwoX$ installation from - seeing a particular bit of $productName$ 1.14 configuration, you can apply - a Kubernetes label to the configuration resources that should be seen by - your $productName$ $versionTwoX$ installation, then set its - `AMBASSADOR_LABEL_SELECTOR` environment variable to restrict its 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$ $versionTwoX$, then set - `AMBASSADOR_LABEL_SELECTOR=version-two=true` in its Deployment. - -3. **Be careful about label selectors on Kubernetes Services!** - - If you have services in $productName$ 1.14 that use selectors that will match - Pods from $productName$ $versionTwoX$, traffic will be erroneously split between - $productName$ 1.14 and $productName$ $versionTwoX$. The labels used by $productName$ - $versionTwoX$ include: - - ```yaml - app.kubernetes.io/name: emissary-ingress - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/part-of: emissary-ingress - app.kubernetes.io/managed-by: getambassador.io - product: aes - profile: main - ``` - -4. **Be careful to only have one $productName$ Agent running at a time.** - - The $productName$ Agent is responsible for communications between - $productName$ and Ambassador Cloud. If multiple versions of the Agent are - running simultaneously, Ambassador Cloud could see conflicting information - about your cluster. - - The migration YAML used below to install $productName$ $versionTwoX$ will not - install a duplicate agent. If you are building your own YAML, make sure not - to include a duplicate agent. - -You can also migrate by [installing $productName$ $versionTwoX$ in a separate cluster](../../../../migrate-to-2-alternate). -This permits absolute certainty that your $productName$ 1.14 configuration will not be -affected by changes meant for $productName$ $versionTwoX$, and it eliminates concerns about -ACME, but it is more effort. - -## Side-by-Side Migration Steps - -Migration is a seven-step process: - -1. **Make sure that older configuration resources are not present.** - - $productName$ 2.X does not support `getambassador.io/v0` or `getambassador.io/v1` - resources, and Kubernetes will not permit removing support for CRD versions that are - still in use for stored resources. To verify that no resources older than - `getambassador.io/v2` are active, run - - ``` - kubectl get crds -o 'go-template={{range .items}}{{.metadata.name}}={{.status.storedVersions}}{{"\n"}}{{end}}' | fgrep getambassador.io - ``` - - If `v1` is present in the output, **do not begin migration.** The old resources must be - converted to `getambassador.io/v2` and the `storedVersion` information in the cluster - must be updated. If necessary, contact Ambassador Labs on [Slack](http://a8r.io/slack) - for more information. - -2. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you must configure your - Kubernetes cluster to support its new `getambassador.io/v3alpha1` configuration - resources. Note that `getambassador.io/v2` resources are still supported, but **you - must install support for `getambassador.io/v3alpha1`** to run $productName$ $versionTwoX$, - even if you intend to continue using only `getambassador.io/v2` resources for some - time. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -3. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, you need to install $productName$ $versionTwoX$ itself - **in the same namespace as your existing $productName$ 1.14 installation**. It's important - to use the same namespace so that the two installations can see the same secrets, etc. - - We publish two manifests for different namespaces. Use only the one that - matches the namespace into which you installed $productName$ 1.14: - - - [`emissary-emissaryns.yaml`] for the `emissary` namespace; or - - [`emissary-defaultns.yaml`] for the `default` namespace. - - If you installed $productName$ 1.14 into some other namespace, you'll need to - download one of the files and edit it to match your namespace. - - [`emissary-emissaryns.yaml`]: https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-emissaryns.yaml - [`emissary-defaultns.yaml`]: https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-defaultns.yaml - - **If you need to set `AMBASSADOR_LABEL_SELECTOR`**, you'll need to download - your chosen file and and edit it to do so. - - Assuming that you're using the `default` namespace: - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-defaultns.yaml && \ - kubectl rollout status -n default deployment/edge-stack -w - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - -4. **Install `Listener`s and `Host`s as needed.** - - An important difference between $productName$ 1.14 and $productName$ $versionTwoX$ is the - new **mandatory** `Listener` CRD. Also, when running both installations side by side, - you will need to make sure that a `Host` is present for the new $productName$ $versionTwoX$ - Service. For example: - - ```bash - kubectl apply -f - < - Kubernetes will not allow you to have a 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.
-
- If you find that your $productName$ $versionTwoX$ installation and your $productName$ 1.14 - installation absolutely must have resources that are only seen by one version or the - other way, see overview section 2, "If needed, you can use labels to further isolate configurations". - - - **If you find that you need to roll back**, just reinstall your 1.14 CRDs and delete your - installation of $productName$ $versionTwoX$. - -6. **When ready, switch over to $productName$ $versionTwoX$.** - - You can run $productName$ 1.14 and $productName$ $versionTwoX$ side-by-side as long as you care - to. However, taking full advantage of $productName$ 2.X's capabilities **requires** - [updating your configuration to use `getambassador.io/v3alpha1` configuration resources](../../../../convert-to-v3alpha1), - since some useful features in $productName$ $versionTwoX$ are only available using - `getambassador.io/v3alpha1` resources. - - When you're ready to have $productName$ $versionTwoX$ handle traffic on its own, switch - your original $productName$ 1.14 Service to point to $productName$ $versionTwoX$. Use - `kubectl edit service ambassador` and change the `selectors` to: - - ``` - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/name: emissary-ingress - profile: main - ``` - - Repeat using `kubectl edit service ambassador-admin` for the `ambassador-admin` - Service. - - -Congratulations! At this point, $productName$ $versionTwoX$ is fully running and it's safe to remove the `ambassador` and `ambassador-agent` Deployments: - -``` -kubectl delete deployment/ambassador deployment/ambassador-agent -``` - -Once $productName$ 1.14 is no longer running, you may [convert](../../../../convert-to-v3alpha1) -any remaining `getambassador.io/v2` resources to `getambassador.io/v3alpha1`. -You may also want to redirect DNS to the `edge-stack` Service and remove the -`ambassador` Service. diff --git a/content/en/docs/3.5/topics/install/upgrade/yaml/emissary-2.0/emissary-2.X.md b/content/en/docs/3.5/topics/install/upgrade/yaml/emissary-2.0/emissary-2.X.md deleted file mode 100644 index b16d046f..00000000 --- a/content/en/docs/3.5/topics/install/upgrade/yaml/emissary-2.0/emissary-2.X.md +++ /dev/null @@ -1,65 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.0.5 (YAML) - - - This guide covers migrating from $productName$ 2.0.5 to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, upgrade $productName$ $versionTwoX$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/3.5/topics/install/upgrade/yaml/emissary-2.4/emissary-2.X.md b/content/en/docs/3.5/topics/install/upgrade/yaml/emissary-2.4/emissary-2.X.md deleted file mode 100644 index ec8b6a70..00000000 --- a/content/en/docs/3.5/topics/install/upgrade/yaml/emissary-2.4/emissary-2.X.md +++ /dev/null @@ -1,67 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.4.Z (YAML) - - - This guide covers migrating from $productName$ 2.4.Z to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -## Migration Steps - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, upgrade $productName$ $versionTwoX$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/3.5/topics/install/upgrade/yaml/emissary-2.5/emissary-3.X.md b/content/en/docs/3.5/topics/install/upgrade/yaml/emissary-2.5/emissary-3.X.md deleted file mode 100644 index ea3b7bc9..00000000 --- a/content/en/docs/3.5/topics/install/upgrade/yaml/emissary-2.5/emissary-3.X.md +++ /dev/null @@ -1,144 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.5.Z (YAML) - - - This guide covers migrating from $productName$ 2.5.Z to $productName$ $version$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - - - Make sure that you have updated any 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$. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading -between versions is straightforward. - -$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. - -### Resources to check before migrating to $version$. - -$productName$ 3.X has been upgraded from Envoy 1.17.X to Envoy 1.22 which removed support for the Envoy V2 Transport Protocol. This means all `AuthService`, `RatelimitService`, and `LogServices` must be updated to use the V3 Protocol. Additionally support for some of the runtime bootstrap flags has been removed. - -You can refer to the [Major changes in $productName$ 3.x](../../../../../../about/changes-3.y/) guide for an overview of the changes. - -1. $productName$ 3.2 fixed a bug with `Host.spec.selector\mappingSelector` and `Listener.spec.selector` not being properly enforced. - In previous versions, if only a single label from the selector was present on the resource then they would be associated. Additionally, when associating `Hosts` with `Mappings`, if the `Mapping` configured a `hostname` that matched the `hostname` of the `Host` then they would be associated regardless of the configuration of the `selector\mappingSelector` on the `Host`. - - Before upgrading, review your Ambassador resources, and if you make use of the selectors, ensure that every other resource you want it to be associated with contains all the required labels. - - The environment variable `DISABLE_STRICT_LABEL_SELECTORS` can be set to `"true"` on the $productName$ deployment to revert to the - old incorrect behavior to help prevent any configuration issues after upgrading in the event that not all manifests making use of the selectors have been corrected yet. - - For more information on `DISABLE_STRICT_LABEL_SELECTORS` see the [Environment Variables page](../../../../../running/environment#disable_strict_label_selectors). - -2. Check Transport Protocol usage on all resources before migrating. - - The `AuthService`, `RatelimitService`, and `LogServices` 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. - - `protocol_version` should be updated to `v3` for all of the above resources while still running $productName$ $versionTwoX$. As of version `2.3.z`+, support for `protocol_version` `v2` and `v3` is supported in order to allow migration from `protocol_version` `v2` to `v3` before upgrading to $productName$ $version$ where support for `v2` is removed. - - Upgrading any application code for your own implementations of these services is very straightforward. - - The following imports simply need to be updated to switch from Envoy's Transport Protocol `v2` to `v3`, and then the configuration for these resources can be updated to add the `protocl_version: "v3"` when the updated service is deployed. - - `v2` Imports: - ```golang - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" - ``` - - `v3` Imports: - ```golang - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" - ``` - -3. Check removed runtime changes - - ```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, - - # Developers 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, - ``` - -4. Support for LightStep tracing driver removed - - - As of $productName$ 3.4.Z, the LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read before upgrading. - - -$productName$ 3.4 is based on Envoy 1.24.1 which removed support for the `LightStep` tracing driver. The team at LightStep and the maintainers of Envoy-Proxy recommend that users instead leverage the OpenTelemetry Collector to send tracing information to LightStep. We have written a guide which can be found here Distributed Tracing with OpenTelemetry and Lightstep that outlines how to set this up. **It is important that you follow this upgrade path prior to upgrading or you will drop tracing data.** - -## Migration Steps - -Migration is a two-step process: - -1. **Install new CRDs.** - - After reviewing the changes in 3.x and confirming that you are ready to upgrade, the process is the same as upgrading minor versions - in previous version of $productName$ and does not require the complex migration steps that the migration from 1.x tto 2.x required. - - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $version$.** - - After installing the new CRDs, upgrade $productName$ $version$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/3.5/topics/install/upgrade/yaml/emissary-3.4/emissary-3.X.md b/content/en/docs/3.5/topics/install/upgrade/yaml/emissary-3.4/emissary-3.X.md deleted file mode 100644 index 723ac6a1..00000000 --- a/content/en/docs/3.5/topics/install/upgrade/yaml/emissary-3.4/emissary-3.X.md +++ /dev/null @@ -1,75 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 3.4.Z (YAML) - - - This guide covers migrating from $productName$ 3.4.Z to $productName$ $version$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading -between versions is straightforward. - -### Resources to check before migrating to $version$. - - - As of $productName$ 3.4.Z, the LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read below before upgrading. - - -$productName$ 3.4 has been upgraded from Envoy 1.23 to Envoy 1.24.1 which removed support for the `LightStep` tracing driver. The team at LightStep and the maintainers of Envoy-Proxy recommend that users instead leverage the OpenTelemetry Collector to send tracing information to LightStep. We have written a guide which can be found here Distributed Tracing with OpenTelemetry and Lightstep that outlines how to set this up. **It is important that you follow this upgrade path prior to upgrading or you will drop tracing data.** - -## Migration Steps - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $version$.** - - After installing the new CRDs, upgrade $productName$ $version$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/3.5/topics/install/yaml-install.md b/content/en/docs/3.5/topics/install/yaml-install.md deleted file mode 100644 index b28e6265..00000000 --- a/content/en/docs/3.5/topics/install/yaml-install.md +++ /dev/null @@ -1,87 +0,0 @@ ---- - description: In this guide, we'll walk through the process of deploying $productName$ in Kubernetes for ingress routing. ---- - -import Alert from '@material-ui/lab/Alert'; - -# Install manually - - - - To migrate from $productName$ 1.X to $productName$ 2.X, see the - [$productName$ migration matrix](../migration-matrix/). This guide - **will not work** for that, due to changes to the configuration - resources used for $productName$ 2.X. - - - -In this guide, we'll walk you through installing $productName$ in your Kubernetes cluster. - -The manual install process does not allow for as much control over configuration -as the [Helm install method](../helm), so if you need more control over your $productName$ -installation, it is recommended that you use helm. - -## Before you begin - -$productName$ is designed to run in Kubernetes for production. The most essential requirements are: - -* Kubernetes 1.11 or later -* The `kubectl` command-line tool - -## Install with YAML - -$productName$ is typically deployed to Kubernetes from the command line. If you don't have Kubernetes, you should use our [Docker](../docker) image to deploy $productName$ locally. - -1. In your terminal, run the following command: - - ``` - kubectl create namespace $productNamespace$ || true - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml && \ - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-emissaryns.yaml && \ - kubectl -n $productNamespace$ wait --for condition=available --timeout=90s deploy $productDeploymentName$ - ``` - - - $productName$ $version$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. Determine the IP address or hostname of your cluster by running the following command: - - ``` - kubectl get -n $productNamespace$ service $productDeploymentName$ -o "go-template={{range .status.loadBalancer.ingress}}{{or .ip .hostname}}{{end}}" - ``` - - Your load balancer may take several minutes to provision your IP address. Repeat the provided command until you get an IP address. - -3. Next Steps - - $productName$ shold now be successfully installed and running, but in order to get started deploying Services and test routing to them you need to configure a few more resources. - - - [The `Listener` Resource](../../running/listener/) is required to configure which ports the $productName$ pods listen on so that they can begin responding to requests. - - [The `Mapping` Resouce](../../using/intro-mappings/) is used to configure routing requests to services in your cluster. - - [The `Host` Resource](../../running/host-crd/) configures TLS termination for enablin HTTPS communication. - - Explore how $productName$ [configures communication with clients](../../../howtos/configure-communications) - - - We strongly recommend following along with our Quickstart Guide to get started by creating a Listener, deploying a simple service to test with, and setting up a Mapping to route requests from $productName$ to the demo service. - - -## Upgrading an existing installation - -See the [migration matrix](../migration-matrix) for instructions about upgrading -$productName$. diff --git a/content/en/docs/3.5/topics/running/ambassador-deployment.md b/content/en/docs/3.5/topics/running/ambassador-deployment.md deleted file mode 100644 index d870f32c..00000000 --- a/content/en/docs/3.5/topics/running/ambassador-deployment.md +++ /dev/null @@ -1,21 +0,0 @@ -# Deployment architecture - -$productName$ can be deployed in a variety of configurations. The specific configuration depends on your data center. - -## Public cloud - -If you're using a public cloud provider such as Amazon, Azure, or Google, $productName$ can be deployed directly to a Kubernetes cluster running in the data center. Traffic is routed to $productName$ via a cloud-managed load balancer such as an Amazon Elastic Load Balancer or Google Cloud Load Balancer. Typically, this load balancer is transparently managed by Kubernetes in the form of the `LoadBalancer` service type. $productName$ then routes traffic to your services running in Kubernetes. - -## On-Premise data center - -In an on-premise data center, $productName$ is deployed on the Kubernetes cluster. Instead of exposing it via the `LoadBalancer` service type, $productName$ is exposed as a `NodePort`. Traffic is sent to a specific port on any of the nodes in the cluster, which route the traffic to $productName$, which then routes the traffic to your services running in Kubernetes. You'll also need to deploy a separate load balancer to route traffic from your core routers to $productName$. [MetalLB](https://metallb.universe.tf/) is an open-source external load balancer for Kubernetes designed for this problem. Other options are traditional TCP load balancers such as F5 or Citrix Netscaler. - -## Hybrid data center - -Many data centers include services that are running outside of Kubernetes on virtual machines. For $productName$ to route to services both inside and outside of Kubernetes, it needs the real-time network location of all services. This problem is known as "[service discovery](https://www.datawire.io/guide/traffic/service-discovery-microservices/)" and $productName$ supports using [Consul](https://www.consul.io). Services in your data center register themselves with Consul, and $productName$ uses Consul-supplied data to dynamically route requests to available services. - -## Hybrid on-premise data center - -The diagram below details a common network architecture for a hybrid on-premise data center. Traffic flows from core routers to MetalLB, which routes to $productName$ running in Kubernetes. $productName$ routes traffic to individual services running on both Kubernetes and VMs. Consul tracks the real-time network location of the services, which $productName$ uses to route to the given services. - -![Architecture](../../images/consul-ambassador.png) diff --git a/content/en/docs/3.5/topics/running/ambassador-with-aws.md b/content/en/docs/3.5/topics/running/ambassador-with-aws.md deleted file mode 100644 index b321543a..00000000 --- a/content/en/docs/3.5/topics/running/ambassador-with-aws.md +++ /dev/null @@ -1,364 +0,0 @@ -# $productName$ with AWS - -$productName$ is a platform agnostic Kubernetes API gateway. It will run in any distribution of Kubernetes whether it is managed by a cloud provider or on homegrown bare-metal servers. - -This document serves as a reference for different configuration options available when running Kubernetes in AWS. See [Installing $productName$](../../install) for the various installation methods available. - -## Recommended configuration - -There are lot of configuration options available to you when running $productName$ in AWS. While you should read this entire document to understand what is best for you, the following is the recommended configuration when running $productName$ in AWS: - -It is recommended to terminate TLS at $productName$ so you can take advantage of all the TLS configuration options available in $productName$ including setting the allowed TLS versions, setting `alpn_protocol` options, enforcing HTTP -> HTTPS redirection, and [automatic certificate management](../host-crd) in the $productName$. - -When terminating TLS at $productName$, you should deploy a L4 [Network Load Balancer (NLB)](#network-load-balancer-nlb) with the proxy protocol enabled to get the best performance out of your load balancer while still preserving the client IP address. - -The following `Service` should be configured to deploy an NLB with cross zone load balancing enabled (see [NLB notes](#network-load-balancer-nlb) for caveat on the cross-zone-load-balancing annotation). You will need to configure the proxy protocol in the NLB manually in the AWS Console. - -```yaml -apiVersion: v1 -kind: Service -metadata: - name: ambassador - namespace: ambassador - annotations: - service.beta.kubernetes.io/aws-load-balancer-type: "nlb" - service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: "true" -spec: - type: LoadBalancer - ports: - - name: HTTP - port: 80 - targetPort: 8080 - - name: HTTPS - port: 443 - targetPort: 8443 - selector: - service: ambassador -``` - - After deploying the `Service` above and manually enabling the proxy protocol you will need to deploy the following [Ambassador `Module`](../ambassador) to tell $productName$ to use the proxy protocol and then restart $productName$ for the configuration to take effect. - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - use_proxy_proto: true - ``` - - $productName$ will now expect traffic from the load balancer to be wrapped with the proxy protocol so it can read the client IP address. - -## AWS load balancer notes - -AWS provides three types of load balancers: - -### "Classic" Elastic Load Balancer (ELB) - -The ELB is the first generation AWS Elastic Load Balancer. It is the default type of load balancer ensured by a `type: LoadBalancer` `Service` and routes directly to individual EC2 instances. It can be configured to run at layer 4 or layer 7 of the OSI model. See [What is a Classic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/introduction.html) for more details. - -* Ensured by default for a `type: LoadBalancer` `Service` -* Layer 4: TCP, TCP/SSL - * Protocol support - * HTTP(S) - * Websockets - * HTTP/2 - * Connection based load balancing - * Cannot modify the request -* Layer 7: HTTP, HTTPS - * Protocol support - * HTTP(S) - * Request based load balancing - * Can modify the request (append to `X-Forwarded-*` headers) -* Can perform TLS termination - -**Notes:** -- While it has been superseded by the `Network Load Balancer` and `Application Load Balancer` the ELB offers the simplest way of provisioning an L4 or L7 load balancer in Kubernetes. -- All of the [load balancer annotations](#load-balancer-annotations) are respected by the ELB. -- If using the ELB for TLS termination, it is recommended to run in L7 mode so it can modify `X-Forwarded-Proto` correctly. - -### Network Load Balancer (NLB) - -The NLB is a second generation AWS Elastic Load Balancer. It can be ensure by a `type: LoadBalancer` `Service` using an annotation. It can only run at layer 4 of the OSI model and load balances based on connection allowing it to handle millions of requests per second. See [What is a Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/introduction.html) for more details. - -* Can be ensured by a `type: LoadBalancer` `Service` -* Layer 4: TCP, TCP/SSL - * Protocol support - * HTTP(S) - * Websockets - * HTTP/2 - * Connection based load balacing - * Cannot modify the request -* Can perform TLS termination - -**Notes:** -- The NLB is the most efficient load balancer capable of handling millions of requests per second. It is recommended for streaming connections since it will maintain the connection stream between the client and $productName$. -- Most of the [load balancer annotations](#load-balancer-annotations) are respected by the NLB. You will need to manually configure the proxy protocol and take an extra step to enable cross zone load balancing. -- Since it operates at L4 and cannot modify the request, you will need to tell $productName$ if it is terminating TLS or not (see [TLS termination](#tls-termination) notes below). - -### Application Load Balancer (ALB) - -The ALB is a second generation AWS Elastic Load Balancer. It cannot be ensured by a `type: LoadBalancer` `Service` and must be deployed and configured manually. It can only run at layer 7 of the OSI model and load balances based on request information allowing it to perform fine-grained routing to applications. See [What is a Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/introduction.html) for more details. - -* Cannot be configured by a `type: LoadBalancer` `Service` -* Layer 7: HTTP, HTTPS - * Protocol support - * HTTP(S) - * Request based load balancing - * Can modify the request (append to `X-Forwarded-*` headers) -* Can perform TLS termination - -**Notes:** - -- The ALB can perform routing based on the path, headers, host, etc.. Since $productName$ performs this kind of routing in your cluster, unless you are using the same load balancer to route to services outside of Kubernetes, the overhead of provisioning an ALB is often not worth the benefits. -- If you would like to use an ALB, you will need to expose $productName$ with a `type: NodePort` service and manually configure the ALB to forward to the correct ports. -- None of the [load balancer annotations](#load-balancer-annotations) are respected by the ALB. You will need to manually configure all options. -- The ALB will properly set the `X-Forward-Proto` header if terminating TLS. See (see [TLS termination](#tls-termination) notes below). - -## Load balancer annotations - -Kubernetes on AWS exposes a mechanism to request certain load balancer configurations by annotating the `type: LoadBalancer` `Service`. The most complete set and explanations of these annotations can be found in this [Kubernetes document](https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer). This document will go over the subset that is most relevant when deploying $productName$. - -- `service.beta.kubernetes.io/aws-load-balancer-ssl-cert`: - - Configures the load balancer to use a valid certificate ARN to terminate TLS at the Load Balancer. - - Traffic from the client into the load balancer is encrypted but, since TLS is being terminated at the load balancer, traffic from the load balancer to $productName$ will be cleartext. You will need to configure $productName$ differently depending on whether the load balancer is running in L4 or L7 (see [TLS termination](#tls-termination) notes below). - -- `service.beta.kubernetes.io/aws-load-balancer-ssl-ports`: - - Configures which port the load balancer will be listening for SSL traffic on. Defaults to `"*"`. - - If you want to enable cleartext redirection, make sure to set this to `"443"` so traffic on port 80 will come in over cleartext. - -- `service.beta.kubernetes.io/aws-load-balancer-backend-protocol`: - - Configures the ELB to operate in L4 or L7 mode. Can be set to `"tcp"`/`"ssl"` for an L4 listener or `"http"`/`"https"` for an L7 listener. Defaults to `"tcp"` or `"ssl"` if `aws-load-balancer-ssl-cert` is set. - -- `service.beta.kubernetes.io/aws-load-balancer-type: "nlb"`: - - When this annotation is set it will launch a [Network Load Balancer (NLB)](#network-load-balancer-nlb) instead of a classic ELB. - -- `service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled`: - - Configures the load balancer to load balance across zones. For high availability, it is typical to deploy nodes across availability zones so this should be set to `"true"`. - - **Note:** You cannot configure this annotation and `service.beta.kubernetes.io/aws-load-balancer-type: "nlb"` at the same time. You must first deploy the `Service` with an NLB and then update it with the cross zone load balancing configuration. - -- `service.beta.kubernetes.io/aws-load-balancer-proxy-protocol`: - - Configures the ELB to enable the proxy protocol. `"*"`, which enables the proxy protocol on all ELB backends, is the only acceptable value. - - The proxy protocol can be used to preserve the client IP address. - - If setting this value, you need to make sure $productName$ is configured to use the proxy protocol (see [preserving the client IP address](#preserving-the-client-ip-address) below). - - **Note:** This annotation will not be recognized if `aws-load-balancer-type: "nlb"` is configured. Proxy protocol must be manually enabled for NLBs. - -## TLS termination - -TLS termination is an important part of any modern web app. $productName$ exposes a lot of TLS termination configuration options that make it a powerful tool for managing encryption between your clients and microservices. Refer to the [TLS Termination](../tls) documentation for more information on how to configure TLS termination at $productName$. - -With AWS, the AWS Certificate Manager (ACM) makes it easy to configure TLS termination at an AWS load balancer using the annotations explained above. - -This means that, when running $productName$ in AWS, you have the choice between terminating TLS at the load balancer using a certificate from the ACM or at $productName$ using a certificate stored as a `Secret` in your cluster. - -The following documentation will cover the different options available to you and how to configure $productName$ and the load balancer to get the most of each. - -### TLS termination at $productName$ - -Terminating TLS at $productName$ will guarantee you to be able to use all of the TLS termination options that $productName$ exposes including enforcing the minimum TLS version, setting the `alpn_protocols`, and redirecting cleartext to HTTPS. - -If terminating TLS at $productName$, you can provision any AWS load balancer that you want with the following (default) port assignments: - -```yaml -spec: - ports: - - name: http - port: 80 - targetPort: 8080 - - name: https - port: 443 - targetPort: 8443 -``` - -While terminating TLS at $productName$ makes it easier to expose more advanced TLS configuration options, it does have the drawback of not being able to use the ACM to manage certificates. You will have to manage your TLS certificates yourself or use the [automatic certificate management](../host-crd) available in $productName$ to have $productName$ do it for you. - -### TLS termination at the load balancer - -If you choose to terminate TLS at your Amazon load balancer you will be able to use the ACM to manage TLS certificates. This option does add some complexity to your $productName$ configuration, depending on which load balancer you are using. - -Terminating TLS at the load balancer means that $productName$ will be receiving all traffic as un-encrypted cleartext traffic. Since $productName$ expects to be serving both encrypted and cleartext traffic by default, you will need to make the following configuration changes to $productName$ to support this: - -#### L4 load balancer (default ELB or NLB) - -* **Load Balancer Service Configuration:** - The following `Service` will deploy a L4 ELB with TLS termination configured at the load balancer: - ```yaml - apiVersion: v1 - kind: Service - metadata: - name: ambassador - namespace: ambassador - annotations: - service.beta.kubernetes.io/aws-load-balancer-ssl-cert: {{ACM_CERT_ARN}} - service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "443" - spec: - type: LoadBalancer - ports: - - name: HTTP - port: 80 - targetPort: 8080 - - name: HTTPS - port: 443 - targetPort: 8080 - selector: - service: ambassador - ``` - - Note that the `spec.ports` has been changed so both the HTTP and HTTPS ports forward to the cleartext port 8080 on $productName$. - -* **`Host`:** - - The `Host` configures how $productName$ handles encrypted and cleartext traffic. The following `Host` configuration will tell $productName$ to `Route` cleartext traffic that comes in from the load balancer: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Host - metadata: - name: ambassador - spec: - hostname: "*" - selector: - matchLabels: - hostname: wildcard - acmeProvider: - authority: none - requestPolicy: - insecure: - action: Route - ``` - -**Important:** - -Because L4 load balancers do not set `X-Forwarded` headers, $productName$ will not be able to distinguish between traffic that came in to the load balancer as encrypted or cleartext. Because of this, **HTTP -> HTTPS redirection is not possible when terminating TLS at a L4 load balancer**. - -#### L7 load balancer (ELB or ALB) - -* **Load Balancer Service Configuration (L7 ELB):** - - The following `Service` will deploy a L7 ELB with TLS termination configured at the load balancer: - ```yaml - apiVersion: v1 - kind: Service - metadata: - name: ambassador - namespace: ambassador - annotations: - service.beta.kubernetes.io/aws-load-balancer-ssl-cert: {{ACM_CERT_ARN}} - service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "443" - service.beta.kubernetes.io/aws-load-balancer-backend-protocol: "http" - spec: - type: LoadBalancer - ports: - - name: HTTP - port: 80 - targetPort: 8080 - - name: HTTPS - port: 443 - targetPort: 8080 - selector: - service: ambassador - ``` - - Note that the `spec.ports` has been changed so both the HTTP and HTTPS ports forward to the cleartext port 8080 on $productName$. - -* **`Host`:** - - The `Host` configures how $productName$ handles encrypted and cleartext traffic. The following `Host` configuration will tell $productName$ to `Redirect` cleartext traffic that comes in from the load balancer: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Host - metadata: - name: ambassador - spec: - hostname: "*" - selector: - matchLabels: - hostname: wildcard - acmeProvider: - authority: none - requestPolicy: - insecure: - action: Redirect - ``` - -* **Module:** - - Since a L7 load balancer will be able to append to `X-Forwarded` headers, we need to configure $productName$ to trust the value of these headers. The following `Module` will configure $productName$ to trust a single L7 proxy in front of $productName$: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - xff_num_trusted_hops: 1 - use_remote_address: false - ``` - -**Note:** - -$productName$ uses the value of `X-Forwarded-Proto` to know if the request originated as encrypted or cleartext. Unlike L4 load balancers, L7 load balancers will set this header so HTTP -> HTTPS redirection is possible when terminating TLS at a L7 load balancer. - -## Preserving the client IP address - -Many applications will want to know the IP address of the connecting client. In Kubernetes, this IP address is often obscured by the IP address of the `Node` that is forwarding the request to $productName$ so extra configuration must be done if you need to preserve the client IP address. - -In AWS, there are two options for preserving the client IP address. - -1. Use a L7 Load Balancer that sets `X-Forwarded-For` - - A L7 load balancer will populate the `X-Forwarded-For` header with the IP address of the downstream connecting client. If your clients are connecting directly to the load balancer, this will be the IP address of your client. - - When using L7 load balancers, you must configure $productName$ to trust the value of `X-Forwarded-For` and not append its own IP address to it by setting `xff_num_trusted_hops` and `use_remote_address: false` in the [Ambassador `Module`](../ambassador): - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - xff_num_trusted_hops: 1 - use_remote_address: false - ``` - - After configuring the above `Module`, you will need to restart $productName$ for the changes to take effect. - -2. Use the proxy protocol - - The [proxy protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) is a wrapper around an HTTP request that, like `X-Forwarded-For`, lists the IP address of the downstream connecting client but is able to be set by L4 load balancers as well. - - In AWS, you can configure ELBs to use the proxy protocol by setting the `service.beta.kubernetes.io/aws-load-balancer-proxy-protocol: "*"` annotation on the service. You must manually configure this on ALBs and NLBs. - - After configuring the load balancer to use the proxy protocol, you need to tell $productName$ to expect it on the request. - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - use_proxy_proto: true - ``` - - After configuring the above `Module`, you will need to restart $productName$ for the changes to take effect. diff --git a/content/en/docs/3.5/topics/running/ambassador-with-gke.md b/content/en/docs/3.5/topics/running/ambassador-with-gke.md deleted file mode 100644 index 2b90581d..00000000 --- a/content/en/docs/3.5/topics/running/ambassador-with-gke.md +++ /dev/null @@ -1,187 +0,0 @@ -# $productName$ with GKE - -Google offers a [L7 load balancer](https://cloud.google.com/kubernetes-engine/docs/concepts/ingress) to -leverage network services such as managed SSL certificates, SSL offloading or the Google content delivery network. -A L7 load balancer in front of $productName$ can be configured by hand or by using the Ingress-GCE resource. Using the -Ingress resource also allows you to create Google-managed SSL certificates through Kubernetes. - -With this setup, HTTPS will be terminated at the Google load balancer. The load balancer will be created and configured by -the Ingress-GCE resource. The load balancer consists of a set of -[forwarding rules](https://cloud.google.com/load-balancing/docs/forwarding-rule-concepts#https_lb) and a set of -[backend services](https://cloud.google.com/load-balancing/docs/backend-service). -In this setup, the ingress resource creates two forwarding rules, one for HTTP and one for HTTPS. The HTTPS -forwarding rule has the SSL certificates attached. Also, one backend service will be created to point to -a list of instance groups at a static port. This will be the NodePort of the $productName$ service. - -With this setup, the load balancer terminates HTTPS and then directs the traffic to the $productName$ service -via the `NodePort`. $productName$ is then doing all the routing to the other internal/external services. - -# Overview of steps - -1. Install and configure the ingress with the HTTP(S) load balancer -2. Install $productName$ -3. Configure and connect $productName$ to ingress -4. Create an SSL certificate and enable HTTPS -5. Create BackendConfig for health checks -6. Configure $productName$ to do HTTP -> HTTPS redirection - -`ambassador` will be running as a `NodePort` service. Health checks will be configured to go to a BackendConfig resource. - -## 0. $productName$ - -This guide will install $OSSproductName$. You can also install $AESproductName$. Please note: -- The ingress and the `ambassador` service need to run in the same namespace -- The `ambassador` service needs to be of type `NodePort` and not `LoadBalancer`. Also remove the line with `externalTrafficPolicy: Local` -- Ambassador-Admin needs to be of type `NodePort` instead of `ClusterIP` since it needs to be available for health checks - -## 1 . Install and configure ingress with the HTTP(S) load balancer - -Create a GKE cluster through the web console. Use the release channel. When the cluster -is up and running follow [this tutorial from Google](https://cloud.google.com/kubernetes-engine/docs/tutorials/http-balancer) to configure -an ingress and a L7 load balancer. After you have completed these steps you will have a running L7 load balancer -and one service. - -## 2. Install $productName$ - -Follow the first section of the [$OSSproductName$ installation guide](../../install/) to install $OSSproductName$. -Stop before defining the `ambassador` service. - -$productName$ needs to be deployed as `NodePort` instead of `LoadBalancer` to work with the L7 load balancer and the ingress. - -Save the YAML below in ambassador.yaml and apply with `kubectl apply -f ambassador.yaml` - -```yaml -apiVersion: v1 -kind: Service -metadata: - name: ambassador -spec: - type: NodePort - ports: - - port: 8080 - targetPort: 8080 - selector: - service: ambassador -``` - -You will now have an `ambassador` service running next to your ingress. - -## 3. Configure and connect `ambassador` to the ingress - -You need to change the ingress for it to send traffic to `ambassador`. Assuming you have followed the tutorial, you should -have a file named basic-ingress.yaml. Change it to point to `ambassador` instead of web: - -```yaml -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - name: basic-ingress -spec: - backend: - serviceName: ambassador - servicePort: 8080 -``` - -Now let's connect the other service from the tutorial to `ambassador` by specifying a Mapping: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: web - namespace: default -spec: - hostname: "*" - prefix: / - service: web:8080 -``` - -All traffic will now go to `ambassador` and from `ambassador` to the `web` service. You should be able to hit your load balancer and get the output. It may take some time until the load balancer infrastructure has rolled out all changes and you might see gateway errors during that time. -As a side note: right now all traffic will go to the `web` service, including the load balancer health check. - -## 4. Create an SSL certificate and enable HTTPS - -Read up on [managed certificates on GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/managed-certs). You need -a DNS name and point it to the external IP of the load balancer. - -certificate.yaml: -```yaml -apiVersion: networking.gke.io/v1beta1 -kind: ManagedCertificate -metadata: - name: www-example-com -spec: - domains: - - www.example.com -``` - -Modify the ingress from before: -```yaml -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - name: basic-ingress - annotations: - networking.gke.io/managed-certificates: www-example-com -spec: - backend: - serviceName: ambassador - servicePort: 8080 -``` - -Please wait (5-15 minutes) until the certificate is created and all edge servers have the certificates ready. -`kubectl describe ManagedCertificate` will show you the status or go to the web console to view the load balancer. - -You should now be able to access the web service via `https://www.example.com`. - -## 5. Configure BackendConfig for health checks - -Create and apply a BackendConfig resource with a [custom health check](https://cloud.google.com/kubernetes-engine/docs/how-to/ingress-features#direct_health) specified: - -```yaml -apiVersion: cloud.google.com/v1 -kind: BackendConfig -metadata: - name: ambassador-hc-config - namespace: ambassador -spec: - # https://cloud.google.com/kubernetes-engine/docs/how-to/ingress-features - timeoutSec: 30 - connectionDraining: - drainingTimeoutSec: 30 - logging: - enable: true - sampleRate: 1.0 - healthCheck: - checkIntervalSec: 10 - timeoutSec: 10 - port: 8877 - type: HTTP - requestPath: /ambassador/v0/check_alive -``` - -Then edit your previous `ambassador.yaml` file to add an annotation referencing the BackendConfig and apply the file: - -``` -apiVersion: v1 -kind: Service -metadata: - name: ambassador - annotations: - cloud.google.com/backend-config: '{"default": "ambassador-hc-config"}' -spec: - type: NodePort - ports: - - port: 8080 - targetPort: 8080 - selector: - service: ambassador -``` - -## 6. Configure $productName$ to do HTTP -> HTTPS redirection - -Configure $productName$ to [redirect traffic from HTTP to HTTPS](../tls/cleartext-redirection/#http-https-redirection). You will need to restart $productName$ to effect the changes with `kubectl rollout restart deployment ambassador`. - -The result should be that `http://www.example.com` will redirect to `https://www.example.com`. - -You can now add more services by specifying the hostname in the Mapping. diff --git a/content/en/docs/3.5/topics/running/ambassador.md b/content/en/docs/3.5/topics/running/ambassador.md deleted file mode 100644 index 3af41d93..00000000 --- a/content/en/docs/3.5/topics/running/ambassador.md +++ /dev/null @@ -1,558 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# The `Ambassador` `Module` Resource - -
-

Contents

- -* [Envoy](#envoy) -* [General](#general) -* [gRPC](#grpc) -* [Header behavior](#header-behavior) -* [Observability](#observability) -* [Protocols](#protocols) -* [Security](#security) -* [Service health / timeouts](#service-health--timeouts) -* [Traffic management](#traffic-management) - - -
- -If present, the `ambassador` `Module` defines system-wide configuration for $productName$. You won't need it unless you need to change one of the system-wide configuration settings below. - -To use the `ambassador` `Module` to configure $productName$, it MUST be named `ambassador`, otherwise it will be ignored. To create multiple `ambassador` `Module`s in the same Kubernetes namespace, you will need to apply them as annotations with separate `ambassador_id`s: you will not be able to use multiple CRDs. - -There are many items that can be configured on the `ambassador` `Module`. They are listed below with examples and grouped by category. - -## Envoy - -##### Content-Length headers - -* `allow_chunked_length: true` tells Envoy to allow requests or responses with both `Content-Length` and `Transfer-Encoding` headers set. The default is `false`. - -By default, messages with both `Content-Length` and `Content-Transfer-Encoding` are rejected. If `allow_chunked_length` is `true`, $productName$ will remove the `Content-Length` header and process the message. See the [Envoy documentation for more details](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto.html?highlight=allow_chunked_length#config-core-v3-http1protocoloptions). - -##### Envoy access logs - -* `envoy_log_path` defines the path of Envoy's access log. By default this is standard output. -* `envoy_log_type` defines the type of access log Envoy will use. Currently, only `json` or `text` are supported. -* `envoy_log_format` defines the Envoy access log line format. - -These logs can be formatted using [Envoy operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) to display specific information about an incoming request. The example below will show only the protocol and duration of a request: - -```yaml -envoy_log_path: /dev/fd/1 -envoy_log_type: json -envoy_log_format: - { - "protocol": "%PROTOCOL%", - "duration": "%DURATION%" - } -``` - -See the Envoy documentation for the [standard log format](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#default-format-string) and a [complete list of log format operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/access_log). - -##### Envoy validation timeout - -* `envoy_validation_timeout` defines the timeout, in seconds, for validating a new Envoy configuration. The default is 10. - -A value of 0 disables Envoy configuration validation. Most installations will not need to change this setting. - -For example: - -```yaml -envoy_validation_timeout: 30 -``` - -would allow 30 seconds to validate the generated Envoy configuration. - -##### Error response overrides - -* `error_response_overrides` permits changing the status code and body text for 4XX and 5XX response codes. The default is not to override any error responses. - -By default, $productName$ will pass through error responses without modification, and errors generated locally will use Envoy's default response body, if any. - -See [using error response overrides](../custom-error-responses) for usage details. For example, this configuration: - -```yaml -error_response_overrides: - - on_status_code: 404 - body: - text_format: "File not found" -``` - -would explicitly modify the body of 404s to say "File not found". - -##### Forwarding client cert details - -Two attributes allow providing information about the client's TLS certificate to upstream certificates: - -* `forward_client_cert_details: true` will tell Envoy to add the `X-Forwarded-Client-Cert` to upstream - requests. The default is `false`. -* `set_current_client_cert_details` will tell Envoy what information to include in the - `X-Forwarded-Client-Cert` header. The default is not to include the `X-Forwarded-Client-Cert` header at all. - -$productName$ will not forward information about a certificate that it cannot validate. - -See the Envoy documentation on [X-Forwarded-Client-Cert](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers.html?highlight=xfcc#x-forwarded-client-cert) and [SetCurrentClientCertDetails](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto.html#extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-setcurrentclientcertdetails) for more information. - -```yaml -forward_client_cert_details: true -set_current_client_cert_details: SANITIZE -``` - -##### Server name - -* `server_name` allows overriding the server name that Envoy sends with responses to clients. The default is `envoy`. - -##### Suppress Envoy headers - -* `suppress_envoy_headers: true` will prevent $productName$ from emitting certain additional - headers to HTTP requests and responses. The default is `false`. - -For the exact set of headers covered by this config, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter#config-http-filters-router-headers-set) - ---- -## General - -##### Ambassador ID - -* `ambassador_id` allows using multiple instances of $productName$ in the same cluster. The default is unset. - -We recommend _not_ setting `ambassador_id` if you are running only one instance of $productName$ in your cluster. For more information, see the [Running and Deployment documentation](../running/#ambassador_id). - -If used, the `ambassador_id` value must be an array, for example: - -```yaml -ambassador_id: [ "test_environment" ] -``` - -##### Defaults - -* `defaults` provides a dictionary of default values that will be applied to various $productName$ resources. The default is to have no defaults configured. - -See [Using `ambassador` `Module` Defaults](../../using/defaults) for more information. - ---- - -## gRPC - -##### Bridges - -* `enable_grpc_http11_bridge: true` will enable the gRPC-HTTP/1.1 bridge. The default is `false`. -* `enable_grpc_web: true` will enable the gRPC-Web bridge. The default is `false`. - -gRPC is a binary HTTP/2-based protocol. While this allows high performance, it can be problematic for clients that are unable to speak HTTP/2 (such as JavaScript in many browsers, or legacy clients in difficult-to-update environments). - -The gRPC-HTTP/1.1 bridge can translate HTTP/1.1 calls with `Content-Type: application/grpc` into gRPC calls: $productName$ will perform buffering and translation as necessary. For more details on the translation process, see the [Envoy gRPC HTTP/1.1 bridge documentation](https://www.envoyproxy.io/docs/envoy/v1.11.2/configuration/http_filters/grpc_http1_bridge_filter.html). - -Likewise, gRPC-Web is a JSON and HTTP-based protocol that allows browser-based clients to take advantage of gRPC protocols. The gRPC-Web specification requires a server-side proxy to translate between gRPC-Web requests and gRPC backend services, and $productName$ can fill this role when the gRPC-Web bridge is enabled. For more details on the translation process, see the [Envoy gRPC HTTP/1.1 bridge documentation](https://www.envoyproxy.io/docs/envoy/v1.11.2/configuration/http_filters/grpc_http1_bridge_filter.html); for more details on gRPC-Web itself, see the [gRPC-Web client GitHub repo](https://github.com/grpc/grpc-web). - -##### Statistics - -* `grpc_stats` allows enabling telemetry for gRPC calls using Envoy's [gRPC Statistics Filter](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/grpc_stats_filter). The default is disabled. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - grpc_stats: - upstream_stats: true - services: - - name: . - method_names: [] -``` - -Supported parameters: -* `all_methods` -* `services` -* `upstream_stats` - -Available metrics: -* `envoy_cluster_grpc__` -* `envoy_cluster_grpc__request_message_count` -* `envoy_cluster_grpc__response_message_count` -* `envoy_cluster_grpc__success` -* `envoy_cluster_grpc__total` -* `envoy_cluster_grpc_upstream_` - **only when `upstream_stats: true`** - -Please note that `` will only be present if `all_methods` is set or the service and the method are present under `services`. If `all_methods` is false or the method is not on the list, the available metrics will be in the format `envoy_cluster_grpc_`. - -* `all_methods`: If set to true, emit stats for all service/method names. -If set to false, emit stats for all service/message types to the same stats without including the service/method in the name. -**This option is only safe if all clients are trusted. If this option is enabled with untrusted clients, the clients could cause unbounded growth in the number -of stats in Envoy, using unbounded memory and potentially slowing down stats pipelines.** - -* `services`: If set, specifies an allow list of service/methods that will have individual stats emitted for them. Any call that does not match the allow list will be counted in a stat with no method specifier (generic metric). - - - If both all_methods and services are present, all_methods will be ignored. - - -* `upstream_stats`: If true, the filter will gather a histogram for the request time of the upstream. - ---- - -## Header behavior - -##### Header case - -* `proper_case: true` forces headers to have their "proper" case as shown in RFC7230. The default is `false`. -* `header_case_overrides` allows forcing certain headers to have specific casing. The default is to override no headers. - -proper_case and header_case_overrides are mutually exclusive. - -RFC7230 specifies that HTTP header names are case-insensitive, but always shows and refers to headers as starting with a capital letter, continuing in lowercase, then repeating the single capital letter after each non-alpha character. This has become an established convention when working with HTTP: - -- `Host`, not `host` or `HOST` -- `Content-Type`, not `content-type`, `Content-type`, or `cOnTeNt-TyPe` - -Internally, Envoy typically uses [all lowercase](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/header_casing) for header names. This is fully compliant with RFC7230, but some services and clients may require headers to follow the stricter casing rules implied by RFC7230 section headers: in that situation, setting `proper_case: true` will tell Envoy to force all headers to use the casing above. - -Alternately, it is also possible - although less common - for services or clients to require some other specific casing for specific headers. `header_case_overrides` specifies an array of header names: if a case-insensitive match for a header is found in the list, the matching header will be replaced with the one in the list. For example, the following configuration will force headers that match `X-MY-Header` and `X-EXPERIMENTAL` to use that exact casing, regardless of the original case used in flight: - -```yaml -header_case_overrides: -- X-MY-Header -- X-EXPERIMENTAL -``` - -If the upstream service responds with `x-my-header: 1`, $productName$ will return `X-MY-Header: 1` to the client. Similarly, if the client includes `x-ExperiMENTAL: yes` in its request, the request to the upstream service will include `X-EXPERIMENTAL: yes`. Other headers will not be altered; $productName$ will use its default lowercase header. - -Please see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto.html#config-core-v3-http1protocoloptions-headerkeyformat) for more information. Note that in general, we recommend updating clients and services rather than relying on `header_case_overrides`. - -##### Linkerd interoperability - -* `add_linkerd_headers: true` will force $productName$ to include the `l5d-dst-override` header for Linkerd. The default is `false`. - -When using older Linkerd installations, requests going to an upstream service may need to include the `l5d-dst-override` header to ensure that Linkerd will route them correctly. Setting `add_linkerd_headers` does this automatically. See the [Mapping](../../using/mappings#linkerd-interoperability-add_linkerd_headers) documentation for more details. - -##### Max request headers size - -* `max_request_headers_kb` sets the maximum allowed request header size in kilobytes. If not set, the default is 60 KB. - -See [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto.html) for more information. - -##### Preserve external request ID - -* `preserve_external_request_id: true` will preserve any `X-Request-Id` header presented by the client. The default is `false`, in which case Envoy will always generate a new `X-Request-Id` value. - -##### Strip matching host port - -* `strip_matching_host_port: true` will tell $productName$ to strip any port number from the host/authority header before processing and routing the request if that port number matches the port number of Envoy's listener. The default is `false`, which will preserve any port number. - -In the default installation of $productName$ the public port is 443, which then maps internally to 8443, so this only works in custom installations where the public Service port and Envoy listener port match. - -A common reason to try using this property is if you are using gRPC with TLS and your client library appends the port to the Host header (i.e. `myurl.com:443`). We have an alternative solution in our [gRPC guide](../../../howtos/grpc#working-with-host-headers-that-include-the-port) that uses a [Lua script](#lua-scripts) to remove all ports from every Host header for that use case. - ---- - -## Miscellaneous - - -##### Envoy's admin port - -* `admin_port` specifies the port where $productName$'s Envoy will listen for low-level admin requests. The default is 8001; it should almost never need changing. - -##### Lua scripts - -* `lua_scripts` allows defining a custom Lua script to run on every request. The default is to run no script. - -This is useful for simple use cases that mutate requests or responses, for example to add a custom header: - -```yaml -lua_scripts: | - function envoy_on_response(response_handle) - response_handle:headers():add("Lua-Scripts-Enabled", "Processed") - end -``` - -For more details on the Lua API, see the [Envoy Lua filter documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/lua_filter.html). - -Some caveats around the embedded scripts: - -* They run in-process, so any bugs in your Lua script can break every request. -* They're run on every request/response to every URL. -* They're inlined in the $productName$ YAML; as such, we do not recommend using Lua scripts for long, complex logic. - -If you need more flexible and configurable options, $AESproductName$ supports a [pluggable Filter system](/docs/edge-stack/latest/topics/using/filters/). - -##### Merge slashes - -* `merge_slashes: true` will cause $productName$ to merge adjacent slashes in incoming paths when doing route matching and request filtering. The default is `false`. - -For example, with `merge_slashes: true`, a request for `//foo///bar` would be matched to a `Mapping` with prefix `/foo/bar`. - -##### Modify Default Buffer Size - -By default, the Envoy that ships with $productName$ uses a defailt of 1MiB soft limit for an upstream service's read and write buffer limits. This setting allows you to configure that buffer limit. See the [Envoy docs](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto.html?highlight=per_connection_buffer_limit_bytes) for more information. - -```yaml -buffer_limit_bytes: 5242880 # Sets the default buffer limit to 5 MiB -``` - -##### Use $productName$ namespace for service resolution - -* `use_ambassador_namespace_for_service_resolution: true` tells $productName$ to assume that unqualified services are in the same namespace as $productName$. The default is `false`. - -By default, when $productName$ sees a service name without a namespace, it assumes that the namespace is the same as the resource referring to the service. For example, for this `Mapping`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-1 - namespace: foo -spec: - hostname: "*" - prefix: / - service: upstream -``` - -$productName$ would look for a Service named `upstream` in namespace `foo`. - -However, if `use_ambassador_namespace_for_service_resolution` is `true`, this `Mapping` would look for a Service named `foo` in the namespace in which $productName$ is installed instead. - ---- - -## Observability - -##### Diagnostics - -* `diagnostics` controls access to the diagnostics interface. - -By default, $productName$ creates a `Mapping` that allows access to the diagnostic interface at `/ambassador/v0/diag` from anywhere in the cluster. To disable the `Mapping` entirely, set `diagnostics.enabled` to `false`: - - -```yaml -diagnostics: - enabled: false -``` - -With diagnostics disabled, `/ambassador/v0/diag` will respond with 404; however, the service itself is still running, and `/ambassador/v0/diag/` is reachable from inside the $productName$ Pod at `https://localhost:8877`. You can use Kubernetes port forwarding to set up remote access to the diagnostics page temporarily: - -``` -kubectl port-forward -n ambassador deploy/ambassador 8877 -``` - -Alternately, to leave the `Mapping` intact but restrict access to only the local Pod, set `diagnostics.allow_non_local` to `false`: - -```yaml -diagnostics: - allow_non_local: true -``` - -See [Protecting Access to the Diagnostics Interface](../../../howtos/protecting-diag-access) for more information. - ---- -## Protocols - -##### Enable IPv4 and IPv6 - -* `enable_ipv4` determines whether IPv4 DNS lookups are enabled. The default is `true`. -* `enable_ipv6` determines whether IPv6 DNS lookups are enabled. The default is `false`. - -If both IPv4 and IPv6 are enabled, $productName$ will prefer IPv6. This can have strange effects if $productName$ receives `AAAA` records from a DNS lookup, but the underlying network of the pod doesn't actually support IPv6 traffic. For this reason, the default is IPv4 only. - -An [`Mapping`](../../using/mappings) can override both `enable_ipv4` and `enable_ipv6`, but if either is not stated explicitly in a `Mapping`, the values here are used. Most $productName$ installations will probably be able to avoid overriding these settings in Mappings. - -##### HTTP/1.0 support - -* `enable_http10: true` will enable handling incoming HTTP/1.0 and HTTP/0.9 requests. The default is `false`. - ---- -## Security - -##### Cross origin resource sharing (CORS) - -* `cors` sets the default CORS configuration for all mappings in the cluster. The default is that CORS is not configured. - -For example: - -```yaml -cors: - origins: http://foo.example,http://bar.example - methods: POST, GET, OPTIONS - ... -``` - -See the [CORS syntax](../../using/cors) for more information. - -##### IP allow and deny - -* `ip_allow` and `ip_deny` define HTTP source IP address ranges to allow or deny. The default is to allow all traffic. - -Only one of ip_allow and ip_deny may be specified. - -If `ip_allow` is specified, any traffic not matching a range to allow will be denied. If `ip_deny` is specified, any traffic not matching a range to deny will be allowed. A list of ranges to allow and a separate list to deny may not both be specified. - -Both take a list of IP address ranges with a keyword specifying how to interpret the address, for example: - -```yaml -ip_allow: -- peer: 127.0.0.1 -- remote: 99.99.0.0/16 -``` - -The keyword `peer` specifies that the match should happen using the IP address of the other end of the network connection carrying the request: `X-Forwarded-For` and the `PROXY` protocol are both ignored. Here, our example specifies that connections originating from the $productName$ pod itself should always be allowed. - -The keyword `remote` specifies that the match should happen using the IP address of the HTTP client, taking into account `X-Forwarded-For` and the `PROXY` protocol if they are allowed (if they are not allowed, or not present, the peer address will be used instead). This permits matches to behave correctly when, for example, $productName$ is behind a layer 7 load balancer. Here, our example specifies that HTTP clients from the IP address range `99.99.0.0` - `99.99.255.255` will be allowed. - -You may specify as many ranges for each kind of keyword as desired. - -##### Rejecting Client Requests With Escaped Slashes - -* `reject_requests_with_escaped_slashes: true` will tell $productName$ to reject requests containing escaped slashes. The default is `false`. - -When set to `true`, $productName$ will reject any client requests that contain escaped slashes (`%2F`, `%2f`, `%5C`, or `%5c`) in their URI path by returning HTTP 400. By default, $productName$ will forward these requests unmodified. - -In general, a request with an escaped slash will _not_ match a `Mapping` prefix with an unescaped slash. However, external authentication services and other upstream services may handle escaped slashes differently, which can lead to security issues if paths with escaped slashes are allowed. By setting `reject_requests_with_escaped_slashes: true`, this class of security concern can be largely avoided. - -##### Trust downstream client IP - -* `use_remote_address: false` tells $productName$ that it cannot trust the remote address of incoming connections, and must instead rely exclusively on the `X-Forwarded-For` header. The default is `true`. - -When `true` (the default), $productName$ will append its own IP address to the `X-Forwarded-For` header so that upstream services of $productName$ can get the full set of IP addresses that have propagated a request. You may also need to set `externalTrafficPolicy: Local` on your `LoadBalancer` to propagate the original source IP address. - -See the [Envoy documentation on the `X-Forwarded-For header` ](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers) and the [Kubernetes documentation on preserving the client source IP](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/#preserving-the-client-source-ip) for more details. - -##### `X-Forwarded-For` trusted hops - -* `xff_num_trusted_hops` sets the default value for [the `l7Depth` setting of a `Listener`](../listener/#securitymodel). The default is 0. - -See the [`Listener` documentation](../listener/#securitymodel) for more details. - ---- - -## Service health / timeouts - -##### Incoming connection idle timeout - -* `listener_idle_timeout_ms` sets the idle timeout for incoming connections. The default is no timeout, meaning that incoming connections may remain idle forever. - -If set, this specifies the length of time (in milliseconds) that an incoming connection is allowed to be idle before being dropped. This can useful if you have proxies and/or firewalls in front of $productName$ and need to control how $productName$ initiates closing an idle TCP connection. - -Please see the [Envoy documentation on HTTP protocol options](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#config-core-v3-httpprotocoloptions) for more information. - -##### Keepalive - -* `keepalive` sets the global TCP keepalive settings. - -$productName$ will use these settings for all `AmbasasdorMapping`s unless overridden in a `Mapping`'s configuration. Without `keepalive`, $productName$ follows the operating system defaults. - -For example, the following configuration: - -```yaml -keepalive: - time: 2 - interval: 2 - probes: 100 -``` - -would enable keepalives every two seconds (`interval`), starting after two seconds of idleness (`time`), with the connection being dropped if 100 keepalives are sent with no response (`probes`). For more information, see the [Envoy keepalive documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/address.proto.html#config-core-v3-tcpkeepalive). - -##### Upstream idle timeout - -* `cluster_idle_timeout_ms` sets the default idle timeout for upstream connections (by default, one hour). - -If set, this specifies the timeout (in milliseconds) after which an idle connection upstream is closed. The idle timeout can be completely disabled by setting `cluster_idle_timeout_ms: 0`, which risks idle upstream connections never getting closed. - -If not set, the default idle timeout is one hour. - -You can override this setting with [`idle_timeout_ms` on a `Mapping`](../../using/timeouts/). - -##### Upstream max lifetime - -* `cluster_max_connection_lifetime_ms` sets the default maximum lifetime of an upstream connection. - -If set, this specifies the maximum amount of time (in milliseconds) after which an upstream connection is drained and closed, regardless of whether it is idle or not. Connection recreation incurs additional overhead when processing requests. The overhead tends to be nominal for plaintext (HTTP) connections within the same cluster, but may be more significant for secure HTTPS connections or upstreams with high latency. For this reason, it is generally recommended to set this value to at least 10000 ms to minimize the amortized cost of connection recreation while providing a reasonable bound for connection lifetime. - -If not set (or set to zero), then upstream connections may remain open for arbitrarily long. - -You can override this setting with [`cluster_max_connection_lifetime_ms` on a `Mapping`](../../using/timeouts/). - -##### Request timeout - -* `cluster_request_timeout_ms` sets the default end-to-end timeout for a single request. - -If set, this specifies the default end-to-end timeout for every request. - -If not set, the default is three seconds. - -You can override this setting with [`timeout_ms` on a `Mapping`](../../using/timeouts/). - -##### Readiness and liveness probes - -* `readiness_probe` sets whether `/ambassador/v0/check_ready` is automatically mapped -* `liveness_probe` sets whether `/ambassador/v0/check_alive` is automatically mapped - -By default, $productName$ creates `Mapping`s that support readiness and liveness checks at `/ambassador/v0/check_ready` and `/ambassador/v0/check_alive`. To disable the readiness `Mapping` entirely, set `readiness_probe.enabled` to `false`: - - -```yaml -readiness_probe: - enabled: false -``` - -Likewise, to disable the liveness `Mapping` entirely, set `liveness_probe.enabled` to `false`: - - -```yaml -liveness_probe: - enabled: false -``` - -A disabled probe endpoint will respond with 404; however, the service is still running, and will be accessible on localhost port 8877 from inside the $productName$ Pod. - -You can change these to route requests to some other service. For example, to have the readiness probe map to the `quote` application's health check: - -```yaml -readiness_probe: - enabled: true - service: quote - rewrite: /backend/health -``` - -The liveness and readiness probes both support `prefix` and `rewrite`, with the same meanings as for [Mappings](../../using/mappings). - -##### Retry policy - -This lets you add resilience to your services in case of request failures by performing automatic retries. - -```yaml -retry_policy: - retry_on: "5xx" -``` - ---- - -## Traffic management - -##### Circuit breaking - -* `circuit_breakers` sets the global circuit breaking configuration defaults - -You can override the circuit breaker settings for individual `Mapping`s. By default, $productName$ does not configure any circuit breakers. For more information, see the [circuit breaking reference](../../using/circuit-breakers). - -##### Default label domain and labels - -* `default_labels` sets default domains and labels to apply to every request. - -For more on how to use the default labels, , see the [Rate Limit reference](../../using/rate-limits/#attaching-labels-to-requests). - -##### Default load balancer - -* `load_balancer` sets the default load balancing type and policy - -For example, to set the default load balancer to `least_request`: - -```yaml -load_balancer: - policy: least_request -``` - -If not set, the default is to use round-robin load balancing. For more information, see the [load balancer reference](../load-balancer). diff --git a/content/en/docs/3.5/topics/running/custom-error-responses.md b/content/en/docs/3.5/topics/running/custom-error-responses.md deleted file mode 100644 index b0ad9877..00000000 --- a/content/en/docs/3.5/topics/running/custom-error-responses.md +++ /dev/null @@ -1,217 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Custom error responses - -Custom error responses set overrides for HTTP response statuses generated either -by $productName$ or upstream services. - -They can be configured either on the $productName$ -[`Module`](../ambassador) -or on an [`Mapping`](../../using/intro-mappings/), the schema is identical. See -below for more information on [rule precedence](#rule-precedence). - -- `on_status_code`: HTTP status code to match for this rewrite - rule. Only 4xx and 5xx classes are supported. -- `body`: Describes the response body contents and format. - + `content_type`: A string that sets the content type of the - response. - + `text_format`: A string whose value will be used as the new - response body. `Content-Type` will default to `text/plain` if - unspecified. - + `json_format`: A config object whose keys and values will be - serialized as JSON and used as the new response body. - + `text_format_source`: Describes a file to be used as the - response. If used, `filename` must be set and the file must exist - on the $productName$ pod. - * `filename`: A file path on the $productName$ pod that will be used - as the new response body. - -Only one of `text_format`, `json_format`, or `text_format_source` may be provided. - -Custom response bodies are subject to Envoy's AccessLog substitution syntax -and variables, see [Envoy's documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#config-access-log-format-strings) for more information. - -Note that the AccessLog substitutions use `%` as a delimiter (for example, -`%RESPONSE_CODE%`). To include a literal `%` in a custom response body, use `%%`. -For example, - -``` -%%RESPONSE_CODE%% %RESPONSE_CODE% -``` - -would render as - -``` -%RESPONSE_CODE% 401 -``` - -for a request that resulted in a response code of 401. - - - If the % 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. - - -## Simple response bodies - -Simple responses can be be added quickly for convenience. They are inserted into -the manifest as either text or JSON: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador - namespace: ambassador -spec: - config: - error_response_overrides: - - on_status_code: 404 - body: - text_format: "File not found" - - on_status_code: 500 - body: - json_format: - error: "Application error" - status: "%RESPONSE_CODE%" - cluster: "%UPSTREAM_CLUSTER%" -``` -## File response bodies - -For more complex response bodies a file can be returned as the response. -This could be used for a customer friendly HTML document for example. Use -`text_format_source` with a `filename` set as a path on the $productName$ pod. -`content_type` should be used set the specific file type, such as `text/html`. - -First configure the $productName$ module: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador - namespace: ambassador -spec: - config: - error_response_overrides: - - on_status_code: 404 - body: - content_type: "text/html" - text_format_source: - filename: '/ambassador/ambassador-errorpages/404.html' -``` - -Then create the config map containing the HTML file: - -```yaml ---- -apiVersion: v1 -kind: ConfigMap -metadata: - name: ambassador-errorpages - namespace: ambassador -data: - 404.html: | - -

File not found

-

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/content/en/docs/3.5/topics/running/debugging.md b/content/en/docs/3.5/topics/running/debugging.md deleted file mode 100644 index bd376483..00000000 --- a/content/en/docs/3.5/topics/running/debugging.md +++ /dev/null @@ -1,192 +0,0 @@ -# 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. - - - Enabling debug-level logging can produce a lot of log output — enough to - potentially impact the performance of $productName$. We don't recommend running with debug - logging enabled as a matter of course; it's usually better to enable it only when needed, - then reset logging to normal once you're finished debugging. - - -### $productName$ debug logging - -Much of $productName$'s logging is concerned with the business of noticing changes to -Kubernetes resources that specify the $productName$ configuration, and generating new -Envoy configuration in response to those changes. Enabling debug logging for this part -of the system is under the control of two environment variables: - -- Set `AES_LOG_LEVEL=debug` to debug the early boot sequence and $productName$'s interactions - with the Kubernetes cluster (finding changed resources, etc.). -- Set `AMBASSADOR_DEBUG=diagd` to debug the process of generating an Envoy configuration from - the input resources. - -### $productName$ Envoy logging - -Envoy logging is concerned with the actions Envoy is taking for incoming requests. -Typically, Envoy will only output access logs, and certain errors, but enabling Envoy -debug logging will show very verbose information about the actions Envoy is actually -taking. It can be useful for understanding why connections are being closed, or whether -an error status is coming from Envoy or from the upstream service. - -It is possible to enable Envoy logging at boot, but for the most part, it's safer to -enable it at runtime, right before sending a request that is known to have problems. -To enable Envoy debug logging, use `kubectl exec` to get a shell on the $productName$ -pod, then: - - ``` - curl -XPOST http://localhost:8001/logging?level=trace && \ - sleep 10 && \ - curl -XPOST http://localhost:8001/logging?level=warning - ``` - -This will turn on Envoy debug logging for ten seconds, then turn it off again. - -### Viewing logs - -To view the logs from $productName$: - -1. Use the following command to target an individual $productName$ Pod: `kubectl get pods -n $productNamespace$` - - The terminal will print something similar to the following: - - ``` - $ kubectl get pods -n $productNamespace$ - NAME READY STATUS RESTARTS AGE - $productDeploymentName$-85c4cf67b-4pfj2 1/1 Running 0 3m - ``` - -2. Then, run the following: `kubectl logs -n $productNamespace$ <$productDeploymentName$-pod-name>` - -The terminal will print something similar to the following: - - ``` - $ kubectl logs -n $productNamespace$ $productDeploymentName$-85c4cf67b-4pfj2 - 2018-10-10 12:26:50 kubewatch 0.40.0 INFO: generating config with gencount 1 (0 changes) - /usr/lib/python3.6/site-packages/pkg_resources/__init__.py:1235: UserWarning: /ambassador is writable by group/others and vulnerable to attack when used with get_resource_filename. Consider a more secure location (set with .set_extraction_path or the PYTHON_EGG_CACHE environment variable). - warnings.warn(msg, UserWarning) - 2018-10-10 12:26:51 kubewatch 0.40.0 INFO: Scout reports {"latest_version": "0.40.0", "application": "ambassador", "notices": [], "cached": false, "timestamp": 1539606411.061929} - - 2018-10-10 12:26:54 diagd 0.40.0 [P15TMainThread] INFO: thread count 3, listening on 0.0.0.0:8877 - [2018-10-10 12:26:54 +0000] [15] [INFO] Starting gunicorn 19.8.1 - [2018-10-10 12:26:54 +0000] [15] [INFO] Listening at: http://0.0.0.0:8877 (15) - [2018-10-10 12:26:54 +0000] [15] [INFO] Using worker: threads - [2018-10-10 12:26:54 +0000] [42] [INFO] Booting worker with pid: 42 - 2018-10-10 12:26:54 diagd 0.40.0 [P42TMainThread] INFO: Starting periodic updates - [2018-10-10 12:27:01.977][21][info][main] source/server/drain_manager_impl.cc:63] shutting down parent after drain - ``` - -Note that many deployments will have multiple logs, and the logs are independent for each Pod. - -## Examine Pod and container contents - -You can examine the contents of the $productName$ Pod for issues, such as if volume mounts are correct and TLS certificates are present in the required directory, to determine if the Pod has the latest $productName$ configuration, or if the generated Envoy configuration is correct or as expected. In these instructions, we will look for problems related to the Envoy configuration. - -1. To look into an $productName$ Pod, get a shell on the Pod using `kubectl exec`. For example, - - ``` - kubectl exec -it -n $productNamespace$ <$productDeploymentName$-pod-name> -- bash - ``` - -2. Determine the latest configuration. If you haven't overridden the configuration directory, the latest configuration will be in `/ambassador/snapshots`. If you have overridden it, $productName$ saves configurations in `$AMBASSADOR_CONFIG_BASE_DIR/snapshots`. - - In the snapshots directory: - - * `snapshot.yaml` contains the full input configuration that $productName$ has found; - * `aconf.json` contains the $productName$ configuration extracted from the snapshot; - * `ir.json` contains the IR constructed from the $productName$ configuration; and - * `econf.json` contains the Envoy configuration generated from the IR. - - In the snapshots directory, the current configuration will be stored in files with no digit suffix, and older configurations have increasing numbers. For example, `ir.json` is current, `ir-1.json` is the next oldest, then `ir-2.json`, etc. - -3. If something is wrong with `snapshot` or `aconf`, there is an issue with your configuration. If something is wrong with `ir` or `econf`, you should [open an issue on Github](https://github.com/emissary-ingress/emissary/issues/new/choose). - -4. The actual input provided to Envoy is split into `$AMBASSADOR_CONFIG_BASE_DIR/bootstrap-ads.json` and `$AMBASSADOR_CONFIG_BASE_DIR/envoy/envoy.json`. - - - The `bootstrap-ads.json` file contains details about Envoy statistics, logging, authentication, etc. - - The `envoy.json` file contains information about request routing. - - You may generally find it simplest to just look at the `econf.json` files in the `snapshot` - directory, which includes both kinds of configuration. diff --git a/content/en/docs/3.5/topics/running/diagnostics.md b/content/en/docs/3.5/topics/running/diagnostics.md deleted file mode 100644 index 20506304..00000000 --- a/content/en/docs/3.5/topics/running/diagnostics.md +++ /dev/null @@ -1,54 +0,0 @@ -# Diagnostics - -With $productName$ Diagnostics and Ambassador Cloud, you get a summary of the current status and Mappings of your cluster and it's services, which gets displayed -in [Diagnostics Overview](https://www.getambassador.io/docs/cloud/latest/diagnostics-ui/view-diagnostics/). - -## Troubleshooting - -### Can't access $productName$ Diagnostics Overview? - -Create an Ambassador `Module` if one does not already exist, and add the following config to enable diagnostics data. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - diagnostics: - enabled: true -``` -Next, ensure that the 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/content/en/docs/3.5/topics/running/environment.md b/content/en/docs/3.5/topics/running/environment.md deleted file mode 100644 index 265fcedd..00000000 --- a/content/en/docs/3.5/topics/running/environment.md +++ /dev/null @@ -1,366 +0,0 @@ -# $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/content/en/docs/3.5/topics/running/gzip.md b/content/en/docs/3.5/topics/running/gzip.md deleted file mode 100644 index e3005c83..00000000 --- a/content/en/docs/3.5/topics/running/gzip.md +++ /dev/null @@ -1,55 +0,0 @@ -# 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/content/en/docs/3.5/topics/running/host-crd.md b/content/en/docs/3.5/topics/running/host-crd.md deleted file mode 100644 index cd187ebe..00000000 --- a/content/en/docs/3.5/topics/running/host-crd.md +++ /dev/null @@ -1,279 +0,0 @@ -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` - - - Remember that Listener resources are required for a functioning - $productName$ installation!
- Learn more about Listener. - - - - Remember than $productName$ does not make sure that a wildcard Host exists! If the - wildcard behavior is needed, a Host with a hostname of "*" - must be defined by the user. - - -A minimal `Host` resource, assuming no TLS configuration, would be: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: minimal-host -spec: - hostname: host.example.com -``` - -This `Host` tells $productName$ to expect to be reached at `host.example.com`, -with no TLS termination, and only associating with `Mapping`s that also set a -`hostname` that matches `host.example.com`. - -Remember that a 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/content/en/docs/3.5/topics/running/http3.md b/content/en/docs/3.5/topics/running/http3.md deleted file mode 100644 index 9aeb6cac..00000000 --- a/content/en/docs/3.5/topics/running/http3.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -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`. - - -The protocolStack elements need to be entered in the specific order of TLS, HTTP, UDP. - - -The `Listener` configured for HTTP/3 can be bound to the same address and port (`0.0.0.0:8443`) as the `Listener` that supports HTTP/2 and HTTP/1.1. This is not required, but it allows $productName$ to inject the default `alt-svc: h3=":443"; ma=86400, h3-29=":443"; ma=86400` header into the responses returned over the TCP connection with no additional configuration needed. **Most clients such as browsers require the `alt-svc` header to upgrade to HTTP/3**. - - -The current default of 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. - - -```yaml -# This is a standard Listener that leverages TCP to serve HTTP/2 and HTTP/1.1 traffic. -# It is bound to the same address and port (0.0.0.0:8443) as the UDP listener. -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: $productDeploymentName$-https-listener - namespace: $productNamespace$ -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: - namespace: - from: ALL ---- -# This is a Listener that leverages UDP and HTTP to serve HTTP/3 traffic. -# NOTE: Raw UDP traffic is not supported. UDP and HTTP must be used together. -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: $productDeploymentName$-https-listener-udp - namespace: $productNamespace$ -spec: - port: 8443 - # Order is important here. HTTP is required. - protocolStack: - - TLS - - HTTP - - UDP - securityModel: XFP - hostBinding: - namespace: - from: ALL -``` - -### Configuring the Host resource - -Because the QUIC network requires TLS, the certificate needs to be valid so the client can upgrade a connection to HTTP/3. See the [Host documentation](./host-crd.md) for more information on how to configure TLS for a `Host`. - -### Certificate verification - -Clients can only upgrade to an HTTP/3 connection with a valid certificate. If the client won’t upgrade to HTTP/3, verify that you have a valid TLS certificate and that your client can speak **TLS v1.3**. Your `Host` resource should be configured similar to the following: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: my-domain-host -spec: - hostname: your-hostname - # acme isn't required but just shown as an example of how to manage a valid TLS cert - acmeProvider: - email: your-email@example.com - authority: https://acme-v02.api.letsencrypt.org/directory - tls: - # QUIC requires TLS v1.3 version. Verify your client supports it. - min_tls_version: v1.3 - # Either protocol can be upgraded, but http/2 is recommended. - alpn_protocols: h2,http/1.1 -``` - -### External load balancers - -The two most common service types to expose traffic outside of a Kubernetes cluster are: - -- `LoadBalancer`: A load balancer controller generates and manages the cloud provider-specific external load balancer. -- `NodePort`: The platform administrator has to manually set up things like the external load balancer, firewall rules, and health checks. - -#### LoadBalancer setup - -The ideal setup would be to configure a single service of type `LoadBalancer`, but this comes with some current restrictions: -- You need version 1.24 or later of Kubernetes with the [`MixedProtocolLBService` feature enabled](https://kubernetes.io/docs/concepts/services-networking/service/#load-balancers-with-mixed-protocol-types). -- Your cloud service provider needs to support the creation of an external load balancer with mixed protocol types (TCP/UDP), port reuse, and port forwarding. Support for Kubernetes feature flags may vary between cloud service providers. Refer to your provider’s documentation to see if they support this scenario. - -An example `LoadBalancer` configuration that fits the criteria listed above: - -```yaml - -# note: extra fields such as labels and selectors removed for clarity -apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$ - namespace: $productNamespace$ -spec: - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - - name: http3 - port: 443 - targetPort: 8443 - protocol: UDP - type: LoadBalancer -``` - -## Cloud service provider setup - -Once you've completed the steps above, you need to configure HTTP/3 support through your cloud service provider. The configuration processes for each provider can be found here: - -- HTTP/3 setup for [Amazon Elastic Kubernetes Service (EKS)](../../../howtos/http3-eks) -- HTTP/3 setup for [Azure Kubernetes Service (AKS)](../../../howtos/http3-aks) -- HTTP/3 setup for [Google Kubernetes Engine (GKE)](../../../howtos/http3-gke) diff --git a/content/en/docs/3.5/topics/running/index.md b/content/en/docs/3.5/topics/running/index.md deleted file mode 100644 index 6eb7af94..00000000 --- a/content/en/docs/3.5/topics/running/index.md +++ /dev/null @@ -1,16 +0,0 @@ -# Running $productName$ in production - -This section of the documentation is designed for operators and site reliability engineers who are managing the deployment of $productName$. Learn more below: - -* *Global Configuration:* The [Ambassador module](ambassador) is used to set system-wide configuration. -* *Exposing $productName$ to the Internet:* The [`Listener` CRD](listener) defines which ports are exposed, including their protocols and security models. The [`Host` CRD](host-crd) defines how $productName$ manages TLS, domains, and such. -* *Load Balancing:* $productName$ supports a number of different [load balancing strategies](load-balancer) as well as different ways to configure [service discovery](resolvers) -* [Gzip Compression](gzip) -* *Deploying $productName$:* On [Amazon Web Services](ambassador-with-aws) | [Google Cloud](ambassador-with-gke) | [general security and operational notes](running), including running multiple $productNamePlural$ on a cluster -* *TLS/SSL:* [Simultaneously Routing HTTP and HTTPS](tls/cleartext-redirection#cleartext-routing) | [HTTP -> HTTPS Redirection](tls/cleartext-redirection#http-https-redirection) | [Mutual TLS](tls/mtls) | [TLS origination](tls/origination) -* *Statistics and Monitoring:* [Integrating with Prometheus, DataDog, and other monitoring systems](statistics) -* *Extending $productName$* $productName$ can be extended with custom plug-ins that connect via HTTP/gRPC interfaces. [Custom Authentication](services/auth-service) | [The External Auth protocol](services/ext-authz) | [Custom Logging](services/log-service) | [Rate Limiting](services/rate-limit-service) | [Distributed Tracing](services/tracing-service) -* *Troubleshooting:* [Diagnostics](diagnostics) | [Debugging](debugging) -* *Scaling $productName$:* [Scaling $productName$](scaling) -* *Ingress:* $productName$ can function as an [Ingress Controller](ingress-controller) -* *Error Response Overrides:* $productName$ can override 4xx and 5xx responses with [custom response bodies](custom-error-responses) diff --git a/content/en/docs/3.5/topics/running/ingress-controller.md b/content/en/docs/3.5/topics/running/ingress-controller.md deleted file mode 100644 index 9b7afb82..00000000 --- a/content/en/docs/3.5/topics/running/ingress-controller.md +++ /dev/null @@ -1,325 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Ingress controller - -
-

Contents

- -- [When and how to use the Ingress resource](#when-and-how-to-use-the-ingress-resource) -- [What is required to use the Ingress resource?](#what-is-required-to-use-the-ingress-resource) -- [When to use an Ingress instead of annotations or CRDs](#when-to-use-an-ingress-instead-of-annotations-or-crds) -- [Ingress support](#ingress-support) -- [Examples of Ingress configs vs Mapping configs](#examples-of-ingress-configs-vs-mapping-configs) -- [Ingress routes and mappings](#ingress-routes-and-mappings) -- [The Minimal Ingress](#the-minimal-ingress) -- [Name based virtual hosting with an Ambassador ID](#name-based-virtual-hosting-with-an-ambassador-id) -- [TLS Termination](#tls-termination) - -
- -An Ingress resource is a popular way to expose Kubernetes services to the Internet. In order to use Ingress resources, you need to install an [ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/). $productName$ can function as a fully-fledged Ingress controller, making it easy to work with other Ingress-oriented tools within the Kubernetes ecosystem. - -## When and how to use the Ingress resource - -If you're new to $productName$ and to Kubernetes, we'd recommend you start with our [quickstart](../../../tutorials/getting-started/) instead of this Ingress guide. If you're a power user and need to integrate with other software that leverages the Ingress resource, read on. The Ingress specification is very basic and does not support many of the features of $productName$, so you'll be using both the Ingress resource and $productName$'s Mapping resource to manage your Kubernetes services. - -### What is required to use the Ingress resource? - -- Know what version of Kubernetes you are using. - - - In Kubernetes 1.13 and below, the Ingress was only included in the `extensions` API. - - - Starting in Kubernetes 1.14, the Ingress was added to the new `networking.k8s.io` API. - - - Kubernetes 1.18 introduced the IngressClass resource to the existing `networking.k8s.io/v1beta1` API. - - If you are using 1.14 and above, it is recommended to use 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. - - -- You will need RBAC permissions to create Ingress resources in either - the `extensions` `apiGroup` (present in all supported versions of - Kubernetes) or the `networking.k8s.io` `apiGroup` (introduced in - Kubernetes 1.14). - -- $productName$ will need RBAC permissions to get, list, watch, and update Ingress resources. - - You can see this in the [`aes-crds.yaml`](https://app.getambassador.io/yaml/ambassador-docs/latest/aes.yaml) - file, but this is the critical rule to add to $productName$'s `Role` or `ClusterRole`: - - ```yaml - - apiGroups: ['extensions', 'networking.k8s.io'] - resources: ['ingresses', 'ingressclasses'] - verbs: ['get', 'list', 'watch'] - - apiGroups: ['extensions', 'networking.k8s.io'] - resources: ['ingresses/status'] - verbs: ['update'] - ``` - - - This is included by default in all $productName$ installations. - - -- You must create your Ingress resource with the correct `ingress.class`. - - $productName$ will automatically read Ingress resources with the annotation - `kubernetes.io/ingress.class: ambassador`. - -- You may need to set your Ingress resource's `ambassador-id`. - - If you are [using `amabssador-id` on your Module](../running/#ambassador_id), you'll need to add the `getambassador.io/ambassador-id` - annotation to your Ingress. See the [examples below](#name-based-virtual-hosting-with-an-ambassador-id). - -- You must create a Service resource with the correct `app.kubernetes.io/component` label. - - $productName$ will automatically load balance Ingress resources using the endpoint exposed - from the Service with the annotation `app.kubernetes.io/component: ambassador-service`. - - ```yaml - --- - kind: Service - apiVersion: v1 - metadata: - name: ingress-ambassador - labels: - app.kubernetes.io/component: ambassador-service - spec: - externalTrafficPolicy: Local - type: LoadBalancer - selector: - service: ambassador - ports: - - name: http - port: 80 - targetPort: http - - name: https - port: 443 - targetPort: https - ``` - -### When to use an Ingress instead of annotations or CRDs - -We recommend that $productName$ be configured using CRDs. The Ingress resource is available to users who need it for integration with other ecosystem tools, or who feel that it more closely matches their workflows. However, it is important to recognize that the Ingress resource is rather more limited than the $productName$ Mapping is (for example, the Ingress spec has no support for rewriting or for TLS origination). **When in doubt, use CRDs.** - -## Ingress support - -$productName$ supports basic core functionality of the Ingress resource, as defined by the [Ingress resource](https://kubernetes.io/docs/concepts/services-networking/ingress/) itself: - -- Basic routing is supported, including the `route` specification and the default backend functionality. It's particularly easy to use a minimal Ingress to the $productName$ diagnostic UI. -- [TLS termination](../tls/) is supported. You can use multiple Ingress resources for SNI. -- Using the Ingress resource in concert with $productName$ CRDs or annotations is supported. This includes $productName$ annotations on the Ingress resource itself. - -$productName$ does **not** extend the basic Ingress specification with the following exceptions: - -- The `getambassador.io/ambassador-id` annotation allows you to set [the Ambassador ID](../running/#ambassador_id) for the Ingress itself. - -- The `getambassador.io/config` annotation can be provided on the Ingress resource, just as on a Service. - -Note that if you need to set `getambassador.io/ambassador-id` on the Ingress, you will also need to set `ambassador-id` on resources within the annotation. - -## Examples of Ingress configs vs Mapping configs - -### Ingress routes and Mappings - -$productName$ actually creates Mapping objects from the Ingress route rules. These Mapping objects interact with Mappings defined in CRDs **exactly** as they would if the Ingress route rules had been specified with CRDs originally. - -For example, this Ingress resource routes traffic to `/foo/` to `service1`: - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: test-ingress -spec: - rules: - - http: - paths: - - path: /foo/ - backend: - serviceName: service1 - servicePort: 80 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: test-ingress-0-0 -spec: - hostname: '*' - prefix: /foo/ - service: service1:80 -``` - -This YAML will set up $productName$ to do canary routing where 50% of the traffic will go to `service1` and 50% will go to `service2`. - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: test-ingress -spec: - rules: - - http: - paths: - - path: /foo/ - backend: - serviceName: service1 - servicePort: 80 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: my-mapping -spec: - hostname: '*' - prefix: /foo/ - service: service2 -``` - -### The minimal Ingress - -An Ingress resource must provide at least some routes or a [default backend](https://kubernetes.io/docs/concepts/services-networking/ingress/#default-backend). The default backend provides for a simple way to direct all traffic to some upstream service: - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: test-ingress -spec: - backend: - serviceName: exampleservice - servicePort: 8080 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: test-ingress -spec: - hostname: '*' - prefix: / - service: exampleservice:8080 -``` - -### Name based virtual hosting with an Ambassador ID - -This Ingress resource will result in all requests to `foo.bar.com` going to `service1`, and requests to `bar.foo.com` going to `service2`: - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - getambassador.io/ambassador-id: externalid - name: name-virtual-host-ingress -spec: - rules: - - host: foo.bar.com - http: - paths: - - backend: - serviceName: service1 - servicePort: 80 - - host: bar.foo.com - http: - paths: - - backend: - serviceName: service2 - servicePort: 80 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: host-foo-mapping -spec: - ambassador_id: ['externalid'] - prefix: / - host: foo.bar.com - service: service1 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: host-bar-mapping -spec: - ambassador_id: ['externalid'] - prefix: / - host: bar.foo.com - service: service2 -``` - -Read more on the [Kubernetes documentation on name based virtual routing](https://kubernetes.io/docs/concepts/services-networking/ingress/#name-based-virtual-hosting). - -### TLS termination - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: tls-example-ingress -spec: - tls: - - hosts: - - sslexample.foo.com - secretName: testsecret-tls - rules: - - host: sslexample.foo.com - http: - paths: - - path: / - backend: - serviceName: service1 - servicePort: 80 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: sslexample-termination-context -spec: - hosts: - - sslexample.foo.com - secret: testsecret-tls ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: sslexample-mapping -spec: - host: sslexample.foo.com - prefix: / - service: service1 -``` - -Note that this shows TLS termination, not origination: the Ingress spec does not support origination. Read more on the [Kubernetes docs on TLS termination](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls). diff --git a/content/en/docs/3.5/topics/running/listener.md b/content/en/docs/3.5/topics/running/listener.md deleted file mode 100644 index 152e1b74..00000000 --- a/content/en/docs/3.5/topics/running/listener.md +++ /dev/null @@ -1,218 +0,0 @@ -# The `Listener` CRD - -The `Listener` CRD defines where, and how, $productName$ should listen for requests from the network, and which `Host` definitions should be used to process those requests. For further examples of how to use `Listener`, see [Configuring $productName$ Communications](../../../howtos/configure-communications). - -**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. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 # int32, port number on which to listen - protocol: HTTPS # HTTP, HTTPS, HTTPPROXY, HTTPSPROXY, TCP - securityModel: XFP # XFP (for X-Forwarded-Proto), SECURE, INSECURE - statsPrefix: example-listener # default depends on protocol; see below - l7Depth: 0 # int32 - hostBinding: - namespace: - from: SELF # SELF, ALL - selector: ... # Kubernetes label selector -``` - -| Element | Type | Definition | -| :------ | :--- | :--------- | -| `port` | `int32` | The network port on which $productName$ should listen. *Required.* | -| `protocol` | `enum`; see below | A high-level protocol type, like "HTTPS". *Exactly one of `protocol` and `protocolStack` must be supplied.* | -| `protocolStack` | array of `enum`; see below | A sequence of low-level protocols to layer together. *Exactly one of `protocol` and `protocolStack` must be supplied.* | -| `securityModel` | `enum`; see below | How does $productName$ decide whether requests here are secure? *Required.* | -| `statsPrefix` | `string`; see below | Under what name do statistics for this `Listener` appear? *Optional; default depends on protocol.* | -| `l7Depth` | `int32` | How many layer 7 load balancers are between the edge of the network and $productName$? *Optional; default is 0.*| -| `hostBinding` | `struct`, see below | Mechanism for determining which `Host`s will be associated with this `Listener`. *Required* | - -### `protocol` and `protocolStack` - -`protocol` is the **recommended** way to tell $productName$ that a `Listener` expects connections using a well-known protocol. When using `protocol`, `protocolStack` may not also be supplied. - -Valid `protocol` values are: - -| `protocol` | Description | -| :--------- | :---------- | -| `HTTP` | Cleartext-only HTTP. HTTPS is not allowed. | -| `HTTPS` | Either HTTPS or HTTP -- Envoy's TLS support can tell whether or not TLS is in use, and it will set `X-Forwarded-Proto` correctly for later decision-making. | -| `HTTPPROXY` | Cleartext-only HTTP, using the HAProxy `PROXY` protocol. | -| `HTTPSPROXY` | Either HTTPS or HTTP, using the HAProxy `PROXY` protocol. | -| `TCP` | TCP sessions without HTTP at all. You will need to use `TCPMapping`s to route requests for this `Listener`. | -| `TLS` | TLS sessions without HTTP at all. You will need to use `TCPMapping`s to route requests for this `Listener`. | - -### `securityModel` - -`securityModel` defines how the `Listener` will decide whether a request is secure or insecure: - -| `securityModel` | Description | -| :--------- | :---------- | -| `XFP` | Requests are secure if, and only if, `X-Forwarded-Proto` indicates HTTPS. This is common; see below. | -| `SECURE` | Requests are always secure. You might set this if your load balancer always terminates TLS for you, and you can trust the clients. | -| `INSECURE` | Requests are always insecure. You might set this for an HTTP-only `Listener`, or a `Listener` for clients that are expected to be hostile. | - -The `X-Forwarded-Proto` header mentioned above is meant to reflect the protocol the _original client_ -used to contact $productName$. When no layer 7 proxies are in use, Envoy will make certain that the -`X-Forwarded-Proto` header matches the wire protocol of the connection the client made to Envoy, -which allows $productName$ to trust `X-Forwarded-Proto` for routing decisions such as deciding to -redirect requests made using HTTP over to HTTPS for greater security. When using $productName$ as an -edge proxy or a typical API gateway, this is a desirable configuration; setting `securityModel` to -`XFP` makes this easy. - -When layer proxies _are_ in use, the `XFP` setting is often still desirable; however, you will also -need to set `l7Depth` to allow it to function. See below. - -`SECURE` and `INSECURE` are helpful for cases where something downstream of $productName$ should be -allowing only one kind of request to reach $productName$. For example, a `Listener` behind a load -balancer that terminates TLS and checks client certificates might use -`SecurityModel: SECURE`, then use `Host`s to reject insecure requests if one somehow -arrives. - -### `l7Depth` - -When layer 7 (L7) proxies are in use, the connection to $productName$ comes from the L7 proxy itself -rather than from the client. Examining the protocol and IP address of that connection is useless, and -instead you need to configure the L7 proxy to pass extra information about the client to $productName$ -using the `X-Forwarded-Proto` and `X-Forwarded-For` headers. - -However, if $productName$ always trusted `X-Forwarded-Proto` and `X-Forwarded-For`, any client could -use them to lie about itself to $productName$. As a security mechanism, therefore, you must _also_ -set `l7Depth` in the `Listener` to the number of trusted L7 proxies in front of $productName$. If -`l7Depth` is not set in the `Listener`, the `xff_num_trusted_hops` value from the `ambassador` `Module` -will be used. If neither is set, the default `l7Depth` is 0. - -When `l7Depth` is 0, any incoming `X-Forwarded-Proto` is stripped: Envoy always provides an -`X-Forwarded-Proto` matching the wire protocol of the incoming connection, so that `X-Forwarded-Proto` -can be trusted. When `l7Depth` is non-zero, `X-Forwarded-Proto` is accepted from the L7 proxy, and -trusted. The actual wire protocol in use from the L7 proxy to $productName$ is ignored. - -`l7Depth` also affects $productName$'s view of the client's source IP address, which is used as the -`remote_address` field when rate limiting, and for the `X-Envoy-External-Address` header: - -- When `l7Depth` is 0, $productName$ uses the IP address of the incoming connection. -- When `l7Depth` is some value N that is non-zero, the behavior is determined by the value of - `use_remote_address` in the `ambassador` `Module`: - - - When `use_remote_address` is true (the default) then the trusted client address will be the Nth - address from the right end of the `X-Forwarded-For` header. (If the XFF contains fewer than N - addresses, Envoy falls back to using the immediate downstream connection’s source address as a - trusted client address.) - - - When `use_remote_address` is false, the trusted client address is the (N+1)th address from the - right end of XFF. (If the XFF contains fewer than N+1 addresses, Envoy falls back to using the - immediate downstream connection’s source address as a trusted client address.) - - For more detailed examples of this interaction, refer to [Envoy's documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers.html#x-forwarded-for). - - -### `hostBinding` - -`hostBinding` specifies how this `Listener` should determine which `Host`s are associated with it: - -- `namespace.from` allows filtering `Host`s by the namespace of the `Host`: - - `namespace.from: SELF` accepts only `Host`s in the same namespace as the `Listener`. - - `namespace.from: ALL` accepts `Host`s in any namespace. -- `selector` accepts only `Host`s that has labels matching the selector. - -`hostBinding` is mandatory, and at least one of `namespace.from` and `selector` must be set. If both are set, both must match for a `Host` to be accepted. - -### `statsPrefix` - -$productName$ produces detailed [statistics](../statistics) which can be monitored in a variety of ways. Statistics have hierarchical names, and the `Listener` will cause a set of statistics to be logged under the name specified by `statsPrefix`. - -The default `statsPrefix` depends on the protocol for this `Listener`: - -- If the `Listener` speaks HTTPS, the default is `ingress-https`. -- Otherwise, if the `Listener` speaks HTTP, the default is `ingress-http`. -- Otherwise, if the `Listener` speaks TLS, the default is `ingress-tls-$port`. -- Otherwise, the default is `ingress-$port`. - -Note that it doesn't matter whether you use `protocol` or `protocolStack`: what matters is what protocol is actually configured. Also note that the default doesn't take the HAProxy `PROXY` protocol into account. - -Some examples: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 - protocol: HTTPS - ... -``` - -will use a `statsPrefix` of `ingress-https`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 - protocol: TCP - ... -``` - -will use `statsPrefix` of `ingress-8080`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 - protocol: HTTPSPROXY - statsPrefix: proxy-8080 - ... -``` - -would also use `ingress-https`, but it explicitly overrides `statsPrefix` to `proxy-8080`. - -For complete information on which statistics will appear for the `Listener`, see [the Envoy listener statistics documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/listeners/stats.html). Some important statistics include - -| Statistic name | Type | Description | -| :-----------------------------------------------| :-------- | :-------------------------------- | -| `listener.$statsPrefix.downstream_cx_total` | Counter | Total connections | -| `listener.$statsPrefix.downstream_cx_active` | Gauge | Total active connections | -| `listener.$statsPrefix.downstream_cx_length_ms` | Histogram | Connection length in milliseconds | - -### `protocolStack` - -**`protocolStack` is not recommended if you can instead use `protocol`.** - -Where `protocol` allows configuring the `Listener` to use well-known protocol stacks, `protocolStack` allows configuring exactly which protocols will be layered together. If `protocol` allows what you need, it is safer to use `Protocol` than to risk having the stack broken with an incorrect `protocolStack`. - -The possible stack elements are: - -| `ProtocolStack` Element | Description | -| :---------------------- | :---------- | -| `HTTP` | Cleartext-only HTTP; must be layered with `TLS` for HTTPS | -| `PROXY` | The HAProxy `PROXY` protocol | -| `TLS` | TLS | -| `TCP` | Raw TCP | - -`protocolStack` supplies a list of these elements to describe the protocol stack. **Order matters.** Some examples: - -| `protocolStack` | Description | -| :-------------- | :---------- | -| [ `HTTP`, `TCP` ] | Cleartext-only HTTP, exactly equivalent to `protocol: HTTP`. | -| [ `TLS`, `HTTP`, `TCP` ] | HTTPS or HTTP, exactly equivalent to `protocol: HTTPS`. | -| [ `PROXY`, `TLS`, `TCP` ] | The `PROXY` protocol, wrapping `TLS` _afterward_, wrapping raw TCP. This isn't equivalent to any `protocol` setting, and may be nonsensical. | - -## Examples - -For further examples of how to use `Listener`, see [Configuring $productName$ to Communicate](../../../howtos/configure-communications). diff --git a/content/en/docs/3.5/topics/running/load-balancer.md b/content/en/docs/3.5/topics/running/load-balancer.md deleted file mode 100644 index 987a910b..00000000 --- a/content/en/docs/3.5/topics/running/load-balancer.md +++ /dev/null @@ -1,209 +0,0 @@ -# Load balancing - -Load balancing configuration can be set for all $productName$ mappings in the [`ambassador` `Module`](../ambassador), or set per [`Mapping`](../../using/mappings). If nothing is set, simple round robin balancing is used via Kubernetes services. - -To use advanced load balancing, you must first configure a [resolver](../resolvers) that supports advanced load balancing (e.g., the Kubernetes Endpoint Resolver or Consul Resolver). Once a resolver is configured, you can use the `load_balancer` attribute. The following fields are supported: - -```yaml -load_balancer: - policy: -``` - -Supported load balancer policies: - -- `round_robin` -- `least_request` -- `ring_hash` -- `maglev` - -For more information on the different policies and the implications, see [load balancing strategies in Kubernetes](https://blog.getambassador.io/load-balancing-strategies-in-kubernetes-l4-round-robin-l7-round-robin-ring-hash-and-more-6a5b81595d6c). - -## Round robin -When `policy` is set to `round_robin`, $productName$ discovers healthy endpoints for the given mapping, and load balances the incoming L7 requests with round robin scheduling. To specify this: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - resolver: my-resolver - load_balancer: - policy: round_robin -``` - -or, per mapping: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - resolver: my-resolver - hostname: '*' - load_balancer: - policy: round_robin -``` - -Note that load balancing may not appear to be "even" due to Envoy's threading model. For more details, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/faq/load_balancing/concurrency_lb). - -## Least request - -When `policy` is set to `least_request`, $productName$ discovers healthy endpoints for the given mapping, and load balances the incoming L7 requests to the endpoint with the fewest active requests. To specify this: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - resolver: my-resolver - load_balancer: - policy: least_request -``` - -or, per mapping: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend/ -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: least_request -``` - -## Sticky sessions / session affinity - -Configuring sticky sessions makes $productName$ route requests to a specific pod providing your service in a given session. One pod serves all requests from a given session, eliminating the need for session data to be transferred between pods. $productName$ lets you configure session affinity based on the following parameters in an incoming request: - -- Cookie -- Header -- Source IP - -**NOTE:** $productName$ supports sticky sessions using two load balancing policies, `ring_hash` and `maglev`. - -### Cookie - -```yaml -load_balancer: - policy: ring_hash - cookie: - name: - ttl: - path: -``` - -If the cookie you wish to set affinity on is already present in incoming requests, then you only need the `cookie.name` field. However, if you want $productName$ to generate and set a cookie in response to the first request, then you need to specify a value for the `cookie.ttl` field which generates a cookie with the given expiration time. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - hostname: '*' - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - cookie: - name: sticky-cookie - ttl: 60s -``` - -### Header - -```yaml -load_balancer: - policy: ring_hash - header:
-``` - -$productName$ allows header based session affinity if the given header is present on incoming requests. - -Example: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - header: STICKY_HEADER -``` - -#### Source IP - -```yaml -load_balancer: - policy: ring_hash - source_ip: -``` - -$productName$ allows session affinity based on the source IP of incoming requests. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - source_ip: true -``` - -Load balancing can be configured both globally, and overridden on a per mapping basis. The following example configures the default load balancing policy to be round robin, while using header-based session affinity for requests to the `/backend/` endpoint of the quote application: - -Load balancing can be configured both globally, and overridden on a per mapping basis. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - resolver: my-resolver - load_balancer: - policy: round_robin -``` - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - header: STICKY_HEADER -``` diff --git a/content/en/docs/3.5/topics/running/resolvers.md b/content/en/docs/3.5/topics/running/resolvers.md deleted file mode 100644 index 1ace9a86..00000000 --- a/content/en/docs/3.5/topics/running/resolvers.md +++ /dev/null @@ -1,128 +0,0 @@ -# Service discovery and resolvers - -Service discovery is how cloud applications and their microservices are located on the network. In a cloud environment, services are ephemeral, existing only as long as they are needed and in use, so a real-time service discovery mechanism is required. $productName$ uses information from service discovery to determine where to route incoming requests. - -## $productName$ support for service discovery - -$productName$ supports different mechanisms for service discovery. These mechanisms are: - -* Kubernetes service-level discovery (default). -* Kubernetes endpoint-level discovery. -* Consul endpoint-level discovery. - -### Kubernetes service-level discovery - -By default, $productName$ uses Kubernetes DNS and service-level discovery. In a `Mapping` resource, specifying `service: foo` will prompt $productName$ to look up the DNS address of the `foo` Kubernetes service. Traffic will be routed to the `foo` service. Kubernetes will then load balance that traffic between multiple pods. For more details on Kubernetes networking and how this works, see our blog post on [Session affinity, load balancing controls, gRPC-Web, and $productName$](https://blog.getambassador.io/session-affinity-load-balancing-controls-grpc-web-and-ambassador-0-52-2b916b396d0c). - -### Kubernetes endpoint-level discovery - -$productName$ can also watch Kubernetes endpoints. This bypasses the Kubernetes service routing layer and enables the use of advanced load balancing controls such as session affinity and maglev. For more details, see the [load balancing reference](../load-balancer). - -### Consul endpoint-level discovery - -$productName$ natively integrates with [Consul](https://www.consul.io) for endpoint-level service discovery. In this mode, $productName$ obtains endpoint information from Consul. One of the primary use cases for this architecture is in hybrid cloud environments that run a mixture of Kubernetes services as well as VMs, as Consul can serve as the single global registry for all services. - -## The Resolver resource - -The `Resolver` resource is used to configure the discovery service strategy for $productName$. - -### The Kubernetes service resolver - -The Kubernetes Service Resolver configures $productName$ to use Kubernetes services. If no resolver is specified, this behavior is the default. When this resolver is used, the `service.namespace` value from a `Mapping` is handed to the Kubernetes cluster's DNS resolver to determine where requests are sent. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: KubernetesServiceResolver -metadata: - name: kubernetes-service -``` - -### The Kubernetes endpoint resolver - -The Kubernetes Endpoint Resolver configures $productName$ to resolve Kubernetes endpoints. This enables the use of more a [advanced load balancing configuration](../load-balancer). When this resolver is used, the endpoints for the `service` defined in a `Mapping` are resolved and used to determine where requests are sent. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: KubernetesEndpointResolver -metadata: - name: endpoint -``` - -### The Consul resolver - -The Consul Resolver configures $productName$ to use Consul for service discovery. When this resolver is used, the `service` defined in a `Mapping` is passed to Consul, along with the datacenter specified, to determine where requests are sent. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: ConsulResolver -metadata: - name: consul-dc1 -spec: - address: consul-server.default.svc.cluster.local:8500 - datacenter: dc1 -``` -- `address`: The fully-qualified domain name or IP address of your Consul server. This field also supports environment variable substitution. -- `datacenter`: The Consul data center where your services are registered - -You may want to use an environment variable if you're running a Consul agent on each node in your cluster. In this setup, you could do the following: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: ConsulResolver -metadata: - name: consul-dc1 -spec: - address: "${HOST_IP}" - datacenter: dc1 -``` - -and then add the `HOST_IP` environment variable to your Kubernetes deployment: - -```yaml -containers: - - name: example - image: docker.io/datawire/ambassador:$version$ - env: - - name: HOST_IP - valueFrom: - fieldRef: - fieldPath: status.hostIP -``` - -## Using resolvers - -Once a resolver is defined, you can use them in a given `Mapping`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: "*" - prefix: /backend/ - service: quote - resolver: endpoint - load_balancer: - policy: round_robin ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: bar -spec: - hostname: "*" - prefix: /bar/ - service: https://bar:9000 - tls: client-context - resolver: consul-dc1 - load_balancer: - policy: round_robin -``` - -The YAML configuration above will configure $productName$ to use Kubernetes Service Discovery to route to the Consul Service Discovery to route to the `bar` service on requests with `prefix: /bar/`. diff --git a/content/en/docs/3.5/topics/running/running.md b/content/en/docs/3.5/topics/running/running.md deleted file mode 100644 index a28b0cb5..00000000 --- a/content/en/docs/3.5/topics/running/running.md +++ /dev/null @@ -1,338 +0,0 @@ -# Running and deployment - -This section is intended for operators running $productName$, and covers various aspects of deploying and configuring the $productName$ in production. - -## $productName$ and Kubernetes - -$productName$ relies on Kubernetes for reliability, availability, and scalability. This means that features such as Kubernetes readiness and liveness probes, rolling updates, and the Horizontal Pod Autoscaling should be utilized to manage $productName$. - -## Default configuration - -The default configuration of $productName$ includes default [resource limits](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-requests-and-limits-of-pod-and-container), as well as [readiness and liveness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/). These values should be adjusted for your specific environment. - -## Running as non-root - -Starting with $productName$ 0.35, we support running $productName$ as non-root. This is the recommended configuration, and will be the default configuration in future releases. We recommend you configure $productName$ to run as non-root as follows: - -* Have Kubernetes run $productName$ as non-root. This may happen by default (e.g., OpenShift) or you can set a `securityContext` in your Deployment as shown below in this abbreviated example: - -```yaml ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: ambassador -spec: - replicas: 1 - selector: - matchLabels: - service: ambassador - template: - metadata: - labels: - service: ambassador - spec: - containers: - image: docker.io/datawire/aes:$version$ - name: ambassador - restartPolicy: Always - securityContext: - runAsUser: 8888 - serviceAccountName: ambassador -``` - -* Set the `service_port` element in the `ambassador Module` to 8080 (cleartext) or 8443 (TLS). This is the port that $productName$ will use to listen to incoming traffic. Note that any port number above 1024 will work; $productName$ will use 8080/8443 as its defaults in the future. - -* Make sure that incoming traffic to $productName$ is configured to route to the `service_port`. If you're using the default $productName$ configuration, this means configuring the `targetPort` to point to the `service_port` above. - -* If you are using `redirect_cleartext_from`, change the value of this field to point to your cleartext port (e.g., 8080) and set `service_port` to be your TLS port (e.g., 8443). - -## Changing the configuration directory - -While running, $productName$ needs to use a directory within its container for generated configuration data. Normally this is `/ambassador`, but in some situations - especially if running as non-root - it may be necessary to change to a different directory. To do so, set the environment variable `AMBASSADOR_CONFIG_BASE_DIR` to the full pathname of the directory to use, as shown below in this abbreviated example: - -```yaml -env: -- name: AMBASSADOR_CONFIG_BASE_DIR - value: /tmp/ambassador-config -``` - -With `AMBASSADOR_CONFIG_BASE_DIR` set as above, $productName$ will create and use the directory `/tmp/ambassador-config` for its generated data. (Note that, while the directory will be created if it does not exist, attempts to turn an existing file into a directory will fail.) - -## Running as DaemonSet - -$productName$ can be deployed as a DaemonSet to have one pod per node in a Kubernetes cluster. This setup is especially helpful when you have a Kubernetes cluster running on a private cloud. - -* In an ideal example scenario, you are running containers on Kubernetes alongside with your non-containerized applications running exposed via VIP using BIG-IP or similar products. In such cases, east-west traffic is routed based on iRules to certain a set of application pools consisting of application or web servers. In this setup, alongside traditional application servers, two or more $productName$ pods can also be part of the application pools. In case of failure there is at least one $productName$ pod available to BIG-IP that can take care of routing traffic to the Kubernetes cluster. - -* In manifest files `kind: Deployment` needs to be updated to `kind: DaemonSet` and `replicas` should be removed in `spec` section. - -## Namespaces - -$productName$ supports multiple namespaces within Kubernetes. To make this work correctly, you need to set the `AMBASSADOR_NAMESPACE` environment variable in $productName$'s container. By far the easiest way to do this is using Kubernetes' downward API (this is included in the YAML files from `getambassador.io`): - -```yaml -env: -- name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace -``` - -Given that `AMBASSADOR_NAMESPACE` is set, $productName$ [`Mappings`](../../using/mappings) can operate within the same namespace, or across namespaces. **Note well** that `Mappings` will have to explicitly include the namespace with the service to cross namespaces; see the [`Mapping`](../../using/mappings) documentation for more information. - -If you want $productName$ to only work within a single namespace, set `AMBASSADOR_SINGLE_NAMESPACE` as an environment variable. - -```yaml -env: -- name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace -- name: AMBASSADOR_SINGLE_NAMESPACE - value: "true" -``` - -With $productName$, if you set `AMBASSADOR_NAMESPACE` or `AMBASSADOR_SINGLE_NAMESPACE`, set it in the deployment container. - -If you want to set a certificate for your `TLScontext` from another namespace, you can use the following: - -```yaml -env: -- name: AMBASSADOR_SINGLE_NAMESPACE - value: "YES" -- name: AMBASSADOR_CERTS_SINGLE_NAMESPACE - value: "YES" -- name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - apiVersion: v1 - fieldPath: metadata.namespace -``` - -## `AMBASSADOR_ID` - -$productName$ supports running multiple $productNamePlural$ in the same cluster, without restricting a given $productName$ to a single namespace. This is done with the `AMBASSADOR_ID` setting. In the `ambassador Module`, set the `ambassador_id`, e.g., - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - ambassador_id: [ "ambassador-1" ] - config: - ... -``` - -Then, assign each $productName$ pod a unique `AMBASSADOR_ID` with the environment variable as part of your deployment: - -```yaml -env: -- name: AMBASSADOR_ID - value: ambassador-1 -``` - -With $productName$, if you set `AMBASSADOR_ID`, you will need to set it in the deployment container. - -$productName$ will then only use YAML objects that include an appropriate `ambassador_id` attribute. For example, if $productName$ is given the ID `ambassador-1` as above, only the first two YAML objects below will be used: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-used -spec: - ambassador_id: [ "ambassador-1" ] - prefix: /demo1/ - service: demo1 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-used-2 -spec: - ambassador_id: [ "ambassador-1", "ambassador-2" ] - prefix: /demo2/ - service: demo2 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-skipped -spec: - prefix: /demo3/ - service: demo3 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-skipped-2 -spec: - ambassador_id: [ "ambassador-2" ] - prefix: /demo4/ - service: demo4 -``` - -`ambassador_id` is always a list, and may (as shown in `mapping-used-2` above) include multiple IDs to allow a given object in the configuration for multiple $productName$ instances. In this case, `mapping-used-2` will be included in the configuration for `ambassador-1` and also for `ambassador-2`. - -**Note well that _any_ $productName$ configuration resource can have an `ambassador_id` included** so, for example, it is _fully supported_ to use `ambassador_id` to qualify the `ambassador Module`, `TLSContext`, and `AuthService` objects. You will need to set `ambassador_id` in all resources you want to use for $productName$. - -If no `AMBASSADOR_ID` is assigned to an $productName$, it will use the ID `default`. If no `ambassador_id` is present in a YAML object, it will also use the ID `default`. - -## `AMBASSADOR_ENVOY_BASE_ID` - -$productName$ supports running side-by-side with other envoy-based projects in a single pod. An example of this is running with an `istio` sidecar. This is done with the `AMBASSADOR_ENVOY_BASE_ID` environment variable as part of your deployment: - -```yaml -env: -- name: AMBASSADOR_ENVOY_BASE_ID - value: 1 -``` - -If no `AMBASSADOR_ENVOY_BASE_ID` is provided then it will use the ID `0`. For more information on the Envoy base-id option please see the [Envoy command line documentation](https://www.envoyproxy.io/docs/envoy/latest/operations/cli.html?highlight=base%20id#cmdoption-base-id). - -## `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. - -## `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. - -## `AMBASSADOR_LEGACY_MODE` - -Setting `AMBASSADOR_LEGACY_MODE` to `true` will result in $productName$ disabling certain features -and reverting to older codepaths which may be better preserve certain older behaviors. Legacy mode -currently has the following effects: - -- $productName$ will switch back to the $productName$ 1.6 input-resource validator (which can significantly -increase configuration latency for $productName$ installations with many resources). -- $productName$ will use the shell boot sequence that was the default up through 1.9.1, rather than the Golang boot sequence that became the default in 1.10.0. -- `AMBASSADOR_FAST_RECONFIGURE` (see below) is not supported in legacy mode. - -## `AMBASSADOR_FAST_RECONFIGURE` - -Setting `AMBASSADOR_FAST_RECONFIGURE` to "true" enables incremental reconfiguration. When enabled, $productName$ will track deltas from one configuration to the next and recalculate only what is necessary to follow the change. When disabled (the default), $productName$ will recompute the entire configuration at every change. - -**`AMBASSADOR_FAST_RECONFIGURE` is not supported when `AMBASSADOR_LEGACY_MODE` is active.** - -## Configuration from the filesystem - -If desired, $productName$ can be configured from YAML files in the directory `$AMBASSADOR_CONFIG_BASE_DIR/ambassador-config` (by default, `/ambassador/ambassador-config`, which is empty in the images built by Datawire). You could volume mount an external configuration directory here, for example, or use a custom Dockerfile to build configuration directly into a Docker image. - -Note well that while $productName$ will read its initial configuration from this directory, configuration loaded from Kubernetes annotations will _replace_ this initial configuration. If this is not what you want, you will need to set the environment variable `AMBASSADOR_NO_KUBEWATCH` so that $productName$ will not try to update its configuration from Kubernetes resources. - -Also note that the YAML files in the configuration directory must contain the $productName$ resources, not Kubernetes resources with annotations. - -## Log levels and debugging - -The $OSSproductName$ and $AESproductName$ support more verbose debugging levels. If using $OSSproductName$, the [diagnostics](../diagnostics) service has a button to enable debug logging. Be aware that if you're running $productName$ on multiple pods, the debug log levels are not enabled for all pods -- they are configured on a per-pod basis. - -If using $AESproductName$, you can 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 format - -By default, $productName$ writes its own logs in a plain text format. To produce logs as JSON instead, set the `AMBASSADOR_JSON_LOGGING` environment variable: - -```yaml -env: -- name: AMBASSADOR_JSON_LOGGING - value: "true" -``` - -## Port assignments - -$productName$ uses some TCP ports in the range 8000-8499 internally, as well as port 8877. Third-party software integrating with $productName$ should not use ports in this range on the $productName$ pod. - -## $productName$ update checks (Scout) - -$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 $productName$ will run regardless of the status of Scout (i.e., our uptime has zero impact on your uptime.) - -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. - -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. - -Unless disabled, $productName$ will also report the following anonymized information back to Datawire: - -| Attribute | Type | Description | -| :------------------------ | :---- | :------------------------ | -| `cluster_count` | int | total count of clusters in use | -| `cluster_grpc_count` | int | count of clusters using GRPC upstream | -| `cluster_http_count` | int | count of clusters using HTTP or HTTPS upstream | -| `cluster_routing_envoy_rh_count` | int | count of clusters routing using Envoy `ring_hash` | -| `cluster_routing_envoy_maglev_count` | int | count of clusters routing using Envoy `maglev` | -| `cluster_routing_envoy_lr_count` | int | count of clusters routing using Envoy `least_request` | -| `cluster_routing_envoy_rr_count` | int | count of clusters routing using Envoy `round_robin` | -| `cluster_routing_kube_count` | int | count of clusters routing using Kubernetes | -| `cluster_tls_count` | int | count of clusters originating TLS | -| `custom_ambassador_id` | bool | has the `ambassador_id` been changed from 'default'? | -| `custom_listener_port` | bool | has the listener port been changed from 80/443? | -| `diagnostics` | bool | is the diagnostics service enabled? | -| `endpoint_grpc_count` | int | count of endpoints to which $productName$ will originate GRPC | -| `endpoint_http_count` | int | count of endpoints to which $productName$ will originate HTTP or HTTPS | -| `endpoint_routing` | bool | is endpoint routing enabled? | -| `endpoint_routing_envoy_rh_count` | int | count of endpoints being routed using Envoy `ring_hash` | -| `endpoint_routing_envoy_maglev_count` | int | count of endpoints being routed using Envoy `maglev` | -| `endpoint_routing_envoy_lr_count` | int | count of endpoints being routed using Envoy `least_request` | -| `endpoint_routing_envoy_rr_count` | int | count of endpoints being routed using Envoy `round_robin` | -| `endpoint_routing_kube_count` | int | count of endpoints being routed using Kubernetes | -| `endpoint_tls_count` | int | count of endpoints to which $productName$ will originate TLS | -| `extauth` | bool | is extauth enabled? | -| `extauth_allow_body` | bool | will $productName$ send the body to extauth? | -| `extauth_host_count` | int | count of extauth hosts in use | -| `extauth_proto` | str | extauth protocol in use ('http', 'grpc', or `null` if not active) | -| `group_canary_count` | int | count of Mapping groups that include more than one Mapping | -| `group_count` | int | total count of Mapping groups in use (length of the route table) | -| `group_header_match_count` | int | count of groups using header matching (including `host` and `method`) | -| `group_host_redirect_count` | int | count of groups using host_redirect | -| `group_host_rewrite_count` | int | count of groups using host_rewrite | -| `group_http_count` | int | count of HTTP Mapping groups | -| `group_precedence_count` | int | count of groups that explicitly set the precedence of the group | -| `group_regex_header_count` | int | count of groups using regex header matching | -| `group_regex_prefix_count` | int | count of groups using regex prefix matching | -| `group_resolver_consul` | int | count of groups using the Consul resolver | -| `group_resolver_kube_endpoint` | int | count of groups using the Kubernetes endpoint resolver | -| `group_resolver_kube_service` | int | count of groups using the Kubernetes service resolver | -| `group_shadow_count` | int | count of groups using shadows | -| `group_shadow_weighted_count` | int | count of groups using shadows but not shadowing all traffic | -| `group_tcp_count` | int | count of TCP Mapping groups | -| `host_count` | int | count of Host resources in use | -| `k8s_ingress_class_count` | int | count of IngressClass resources in use | -| `k8s_ingress_count` | int | count of Ingress resources in use | -| `listener_count` | int | count of active listeners (1 unless `redirect_cleartext_from` or TCP Mappings are in use) | -| `liveness_probe` | bool | are liveness probes enabled? | -| `managed_by` | string | tool that manages the $productName$ deployment, if any (e.g. helm, edgectl, etc.) | -| `mapping_count` | int | count of Mapping resources in use | -| `ratelimit` | bool | is rate limiting in use? | -| `ratelimit_custom_domain` | bool | has the rate limiting domain been changed from 'ambassador'? | -| `ratelimit_data_plane_proto` | bool | is rate limiting using the data plane proto? | -| `readiness_probe` | bool | are readiness probes enabled? | -| `request_4xx_count` | int | lower bound for how many requests have gotten a 4xx response | -| `request_5xx_count` | int | lower bound for how many requests have gotten a 5xx response | -| `request_bad_count` | int | lower bound for how many requests have failed (either 4xx or 5xx) | -| `request_elapsed` | float | seconds over which the request_ counts are valid | -| `request_hr_elapsed` | string | human-readable version of `request_elapsed` (e.g. "3 hours 35 minutes 20 seconds" | -| `request_ok_count` | int | lower bound for how many requests have succeeded (not a 4xx or 5xx) | -| `request_total_count` | int | lower bound for how many requests were handled in total | -| `statsd` | bool | is StatsD enabled? | -| `server_name` | bool | is the `server_name` response header overridden? | -| `service_resource_total` | int | total count of service resources loaded from all discovery sources | -| `tls_origination_count` | int | count of TLS origination contexts | -| `tls_termination_count` | int | count of TLS termination contexts | -| `tls_using_contexts` | bool | are new TLSContext resources in use? ? | -| `tls_using_module` | bool |is the old TLS module in use | -| `tracing` | bool | is tracing in use? | -| `tracing_driver` | str | tracing driver in use ('zipkin', 'lightstep', 'datadog', or `null` if not active) | -| `use_proxy_proto` | bool | is the `PROXY` protocol in use? | -| `use_remote_address` | bool | is $productName$ honoring remote addresses? | -| `x_forwarded_proto_redirect` | bool | is $productName$ redirecting based on `X-Forwarded-Proto`? | -| `xff_num_trusted_hops` | int | what is the count of trusted hops for `X-Forwarded-For`? | - -The `request_*` counts are always incremental: they contain only information about the last `request_elapsed` seconds. Additionally, they only provide a lower bound -- notably, if an $productName$ pod crashes or exits, no effort is made to ship out a final update, so it's very easy for counts to never be reported. - -To completely disable feature reporting, set the environment variable `AMBASSADOR_DISABLE_FEATURES` to any non-empty value. diff --git a/content/en/docs/3.5/topics/running/scaling.md b/content/en/docs/3.5/topics/running/scaling.md deleted file mode 100644 index 22fa743e..00000000 --- a/content/en/docs/3.5/topics/running/scaling.md +++ /dev/null @@ -1,194 +0,0 @@ -# Performance and scaling $productName$ - -Scaling any cloud native application is inherently domain specific, however the content here -reflects common issues, tips, and tricks that come up frequently. - -## Performance dimensions - -The performance of $productName$'s control plane can be characterized along a number of -different dimensions: - - - The number of `TLSContext` resources. - - The number of `Host` resources. - - The number of `Mapping` resources per `Host` resource. - - The number of `Mapping` resources that will span all `Host` resources (either because they're using `host_regex`, or because they're using `hostname: "*"`). - -If your application involves a larger than average number of any of the above resources, you may -find yourself in need of some of the content in this section. - -## Mysterious pod restarts (aka pushing the edge of the envelope) - -Whether your application is growing organically or whether you are deliberately scale testing, it's -helpful to recognize how $productName$ behaves as it reaches the edge of its performance -envelope along any of these dimensions. - -As $productName$ approaches the edge of its performance envelope, it will often manifest as -mysterious pod restarts triggered by Kubernetes. This does not always mean there is a problem, it -could just mean you need to tune some of the resource limits set in your deployment. When it comes -to scaling, Kubernetes will generally kill an $productName$ pod for one of two reasons: exceeding -memory limits or failed liveness/readiness probes. See the [Memory Limits](#memory-limits), -[Liveness Probes](#liveness-probes), and [Readiness Probes](#readiness-probes) -sections for more on how to cope with these situations. - -## Memory limits - -$productName$ can grow in memory usage and be killed by Kubernetes if it exceeds the limits -defined in its pod spec. When this happens it is confusing and difficult to catch because the only -indication that this has occurred is the pod transitioning momentarily into the `OOMKilled` -state. The only way to actually observe this is if you are lucky enough to be running the following -command (or have similar monitoring configured) when $productName$ gets `OOMKilled`: - -``` - kubectl get pods -n ambassador -w -``` - -In order to take the luck out of the equation, $productName$ will periodically log its -memory usage so you can see in the logs if memory limits might be a problem and require adjustment: - -``` -2020/11/26 22:35:20 Memory Usage 0.56Gi (28%) - PID 1, 0.22Gi: busyambassador entrypoint - PID 14, 0.04Gi: /usr/bin/python /usr/bin/diagd /ambassador/snapshots /ambassador/bootstrap-ads.json /ambassador/envoy/envoy.json --notices /ambassador/notices.json --port 8004 --kick kill -HUP 1 - PID 16, 0.12Gi: /ambassador/sidecars/amb-sidecar - PID 37, 0.07Gi: /usr/bin/python /usr/bin/diagd /ambassador/snapshots /ambassador/bootstrap-ads.json /ambassador/envoy/envoy.json --notices /ambassador/notices.json --port 8004 --kick kill -HUP 1 - PID 48, 0.08Gi: envoy -c /ambassador/bootstrap-ads.json --base-id 0 --drain-time-s 600 -l error -``` - -In general you should try to keep $productName$'s memory usage below 50% of the pod's limit. This may -seem like a generous safety margin, but when reconfiguration occurs, $productName$ requires additional -memory to avoid disrupting active connections. At each reconfiguration, $productName$ keeps around the -old version for the duration of the configured drain time. See -[AMBASSADOR_DRAIN_TIME](#ambassador_drain_time) for more details on how to tune this -behavior. - -$productName$'s exact memory usage depends on (among other things) how many `Host` and -`Mapping` resources are defined in your cluster. If this number has grown over time, you may need to -increase the memory limit defined in your deployment. - -## Liveness probes - -$productName$ defines the `/ambassador/v0/check_alive` endpoint on port `8877` for use with Kubernetes -liveness probes. See the Kubernetes documentation for more details on [HTTP liveness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-a-liveness-http-request). - -Kubernetes will restart the $productName$ pod if it fails to get a 200 result from the endpoint. If -this happens it won't necessarily show up in an easily recognizable way in the pod logs. You can -look for Kubernetes events to see if this is happening. Use `kubectl describe pod -n ambassador` or -`kubectl get events -n ambassador` or equivalent. - -The purpose of liveness probes is to rescue an $productName$ instance that is wedged, however if -liveness probes are too sensitive they can take out $productName$ instances that are functioning -normally. This is more prone to happen as the number of $productName$ inputs increase. The -`timeoutSeconds` and `failureThreshold` fields of the $productName$ deployment's liveness Probe -determines how tolerant Kubernetes is with its probes. If you observe pod restarts along with -`Unhealthy` events, try tuning these fields upwards from their default values. See the Kubernetes documentation for more details on [tuning probes](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#probe-v1-core). - -Note that whatever changes you make to $productName$'s liveness probes should most likely be made to -its readiness probes also. - -## Readiness probes - -$productName$ defines the `/ambassador/v0/check_ready` endpoint on port `8877` for use with Kubernetes -readiness probes. See the Kubernetes documentation for more details on [readiness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-readiness-probes). - -Kubernetes uses readiness checks to prevent traffic from going to pods that are not ready to handle -requests. The only time $productName$ cannot usefully handle requests is during initial startup when it -has not yet loaded all the routing information from Kubernetes and/or consul. During this bootstrap -period there is no guarantee $productName$ would know where to send a given request. The `check_ready` -endpoint will only return 200 when all routing information has been loaded. After the initial -bootstrap period it behaves identically to the `check_alive` endpoint. - -Generally $productName$'s readiness probes should be configured with the same settings as its liveness -probes. - -## `AMBASSADOR_FAST_RECONFIGURE` and `AMBASSADOR_LEGACY_MODE` flags - -`AMBASSADOR_FAST_RECONFIGURE` is a feature flag that enables a higher performance implementation of -the code $productName$ uses to validate and generate envoy configuration. It will eventually be enabled -by default, but if you are experiencing performance problems you should try setting -`AMBASSADOR_FAST_RECONFIGURE` to `true` to see if this helps. - -`AMBASSADOR_LEGACY_MODE` is **not** recommended when performance is critical. - -## `AMBASSADOR_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. - -## Unconstrained Mappings with many hosts - -When working with a large number of `Host` resources, it's important to understand the impact of -unconstrained `Mapping`s. An unconstrained `Mapping` is one that is not restricted to a specific -`Host`. Such a `Mapping` will create a route for all of your `Host`s. If this is what you want then -it is the appropriate thing to do, however if you do not intend to do this, then you can end up with -many more routes than you had intended and this can adversely impact performance. - -## Inspecting $productName$ performance - -$productName$ internally tracks a number of key performance indicators. You can inspect these via the -debug endpoint at `localhost:8877/debug`. Note that the `AMBASSADOR_FAST_RECONFIGURE` flag needs to -be set to `"true"` for this endpoint to be present: - -``` -$ kubectl exec -n ambassador -it ${POD} curl localhost:8877/debug -{ - "timers": { - # These two timers track how long it takes to respond to liveness and readiness probes. - "check_alive": "7, 45.411495ms/61.85999ms/81.358927ms", - "check_ready": "7, 49.951304ms/61.976205ms/86.279038ms", - - # These two timers track how long we spend updating our in-memory snapshot when our Kubernetes - # watches tell us something has changed. - "consulUpdate": "0, 0s/0s/0s", - "katesUpdate": "3382, 28.662µs/102.784µs/95.220222ms", - - # These timers tell us how long we spend notifying the sidecars if changed input. This - # includes how long the sidecars take to process that input. - "notifyWebhook:diagd": "2, 1.206967947s/1.3298432s/1.452718454s", - "notifyWebhooks": "2, 1.207007216s/1.329901037s/1.452794859s", - - # This timer tells us how long we spend parsing annotations. - "parseAnnotations": "2, 21.944µs/22.541µs/23.138µs", - - # This timer tells us how long we spend reconciling changes to consul inputs. - "reconcileConsul": "2, 50.104µs/55.499µs/60.894µs", - - # This timer tells us how long we spend reconciling secrets related changes to $productName$ - # inputs. - "reconcileSecrets": "2, 18.704µs/20.786µs/22.868µs" - }, - "values": { - "envoyReconfigs": { - "times": [ - "2020-11-06T13:13:24.218707995-05:00", - "2020-11-06T13:13:27.185754494-05:00", - "2020-11-06T13:13:28.612279777-05:00" - ], - "staleCount": 2, - "staleMax": 0, - "synced": true - }, - "memory": "39.73Gi of Unlimited (0%)" - } -} -``` - -## Running profiles - -$productName$ exposes endpoints at `localhost:8877/debug/pprof` to run Golang profiles to aid in live debugging. The endpoints are equivalent to those found in the [http/pprof](https://pkg.go.dev/net/http/pprof) package. `/debug/pprof/` returns an HTML page listing the available profiles. - -The following are the different types of profiles you can run: - -| Profile | Function | -| :------- | :-------- | -| /debug/pprof/allocs | Returns a sampling of all past memory allocations. | -| /debug/pprof/block | Returns stack traces of goroutines that led to blocking on sychronization primitives. | -| /debug/pprof/cmdline | Returns the command line that was invoked by the current program. | -| /debug/pprof/goroutine | Returns stack traces of all current goroutines. | -| /debug/pprof/heap | Returns a sampling of memory allocations of live objects. | -| /debug/pprof/mutex | Returns stack traces of goroutines holding contended mutexes. | -| /debug/pprof/profile | Returns pprof-formatted cpu profile. You can specify the duration using the seconds `GET` parameter. The default duration is 30 seconds. | -| /debug/pprof/symbol | Returns the program counters listed in the request. | -| /debug/pprof/threadcreate | Returns stack traces that led to creation of new OS threads. | -| /debug/pprof/trace | Returns the execution trace in binary form. You can specify the duration using the seconds `GET` parameter. The default duration is 1 second. | diff --git a/content/en/docs/3.5/topics/running/services/auth-service.md b/content/en/docs/3.5/topics/running/services/auth-service.md deleted file mode 100644 index adfb77e4..00000000 --- a/content/en/docs/3.5/topics/running/services/auth-service.md +++ /dev/null @@ -1,150 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Authentication service - -$productName$ provides a highly flexible mechanism for authentication, -via the `AuthService` resource. An `AuthService` configures -$productName$ to use an external service to check authentication and -authorization for incoming requests. Each incoming request is -authenticated before routing to its destination. - -All requests are validated by the `AuthService` (unless the `Mapping` -applied to the request sets `bypass_auth`). It is not possible to -combine multiple `AuthServices`. While it is possible to create -multiple `AuthService` resources, $productName$ load-balances between -them in a round-robin fashion. This is useful for canarying an -`AuthService` change, but is not useful for deploying multiple -distinct `AuthServices`. In order to combine multiple external -services (either having multiple services apply to the same request, -or selecting between different services for the different requests), -instead of using an `AuthService`, use an [$AESproductName$ `External` -`Filter`](/docs/edge-stack/latest/topics/using/filters/). - - - -Because of the limitations described above, **$AESproductName$ does -not support `AuthService` resources, and you should instead use an -[`External` -`Filter`](/docs/edge-stack/latest/topics/using/filters/external),** -which is mostly a drop-in replacement for an `AuthService`. The -`External` `Filter` relies on the $AESproductName$ `AuthService`. -Make sure the $AESproductName$ `AuthService` is deployed before -configuring `External` `Filters`. - - - -The currently supported version of the `AuthService` resource is -`getambassador.io/v3alpha1`. Earlier versions are deprecated. - -## Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: AuthService -metadata: - name: authentication -spec: - ambassador_id: [ "ambassador-1" ] - auth_service: "example-auth.authentication:3000" - tls: true - proto: http - timeout_ms: 5000 - include_body: - max_bytes: 4096 - allow_partial: true - status_on_error: - code: 403 - failure_mode_allow: false - - # proto: grpc only, default is v2. If upgrading from 2.x then you must set this to v3. - protocol_version: v3 - - # proto: http only - path_prefix: "/path" - allowed_request_headers: - - "x-example-header" - allowed_authorization_headers: - - "x-qotm-session" - add_auth_headers: - x-added-auth: auth-added - add_linkerd_headers: false -``` - -## Fields - -`auth_service` is the only required field, all others are optional. - -| Attribute | Default value | Description | -| ---------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `ambassador_id` | `[ "default" ]` | Which [Ambassador ID](../../running/#ambassador_id) the `AuthService` should apply to. | -| `auth_service` | (none; a value is required) | Identifies the external auth service to talk to. The format of this field is `scheme://host:port` where `scheme://` and `:port` are optional. The scheme-part, if present, must be either `http://` or `https://`; if the scheme-part is not present, it behaves as if `http://` is given. The scheme-part controls whether TLS or plaintext is used and influences the default value of the port-part. The host-part must be the [namespace-qualified DNS name](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#namespaces-of-services) of the service you want to use for authentication. | -| `tls` | `""` | This field is populated with the name of the defined TLSContext, which determines the TLS certificate presented to external auth services. | -| `proto` | `http` | Specifies which variant of the [`ext_authz` protocol](../ext-authz/) to use when communicating with the external auth service. Valid options are `http` or `grpc`. | -| `timeout_ms` | `5000` | The total maximum duration in milliseconds for the request to the external auth service, before triggering `status_on_error` or `failure_mode_allow`. | -| `include_body` | `null` | Controls how much to buffer the request body to pass to the external auth service, for use cases such as computing an HMAC or request signature. If `include_body` is `null` or unset, then the request body is not buffered at all, and an empty body is passed to the external auth service. If `include_body` is not `null`, the `max_bytes` and `allow_partial` subfields are required. | -| `include_body.max_bytes` | (none; a value is required if `include_body` is not `null`) | Controls the amount of body data that is passed to the external auth service. | -| `include_body.allow_partial` | (none; a value is required if `include_body` is not `null`) | Controls what happens to requests with bodies larger than `max_bytes`. If `allow_partial` is `true`, the first `max_bytes` of the body are sent to the external auth service. If `false`, the message is rejected with HTTP 413 ("Payload Too Large"). | -| `status_on_error.code` | `403` | Controls the status code returned when unable to communicate with external auth service. This is ignored if `failure_mode_allow: true`. | -| `failure_mode_allow` | `false` | Controls whether to allow or reject requests when there is an error communicating with the external auth service; a value of `true` allows the request through to the upstream backend service, a value of `false` returns a `status_on_error.code` response to the client. | -| `stats_name` | the `auth_service` value with non-alphanumeric characters replaced with underscores | See [Overriding Statistics Names](../../statistics/#overriding-statistics-names). | -| `circuit_breakers` | the value set in the [`ambassador` `Module`](../../../using/defaults) | See [Circuit Breakers](../../../using/circuit-breakers/). | - -The following field is only used if `proto` is set to `grpc`. It is -ignored if `proto` is `http`. - -| Attribute | Default value | Description | -| ------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `protocol_version` | `v3` | Allowed values are `v3` and `v2`(defualt). `protocol_version` was used in previous versions of $productName$ to control the protocol used by the gRPC service. $productName$ 3.x is running an updated version of Envoy that has dropped support for the `v2` protocol, so starting in 3.x, if `protocol_version` is not specified, 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. | - -The following fields are only used if `proto` is set to `http`. They -are ignored if `proto` is `grpc`. - -| Attribute | Default value | Description | -| ------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `path_prefix` | `""` | Prepends a string to the request path of the request when sending it to the external auth service. By default this is empty, and nothing is prepended. For example, if the client makes a request to `/foo`, and `path_prefix: /bar`, then the path in the request made to the external auth service will be `/foo/bar`. | -| `allowed_request_headers` | `[]` | Lists the headers (case-insensitive) that are copied from the incoming request to the request made to the external auth service. In addition to the headers listed in this field, the following headers are always included: `Authorization`, `Cookie`, `From`, `Proxy-Authorization`, `User-Agent`, `X-Forwarded-For`, `X-Forwarded-Host`, and `X-Forwarded-Proto`. | -| `allowed_authorization_headers` | `[]` | Lists the headers (case-insensitive) that are copied from the response from the external auth service to the request sent to the upstream backend service (if the external auth service indicates that the request to the upstream backend service should be allowed). In addition to the headers listed in this field, the following headers are always included: `Authorization`, `Location`, `Proxy-Authenticate`, `Set-cookie`, `WWW-Authenticate` | -| `add_auth_headers` | `{}` | A dictionary of `header: value` pairs that are added to the request made to the external auth service. | -| `add_linkerd_headers` | Defaults to the value set in the [`ambassador` `Module`](../../ambassador) | When true, in the request to the external auth service, adds an `l5d-dst-override` HTTP header that is set to the hostname and port number of the external auth service. | - -## Canarying multiple `AuthServices` - -You may create multiple `AuthService` manifests to round-robin -authentication requests among multiple services. **All services must -use the same `path_prefix` and header definitions.** If you try to -have different values, you'll see an error in the [diagnostics -service](../../ambassador/#diagnostics), telling you which value is -being used. - -## Configuring public `Mappings` - -An `AuthService` can be disabled for a `Mapping` by setting -`bypass_auth` to `true`. This will tell $productName$ to allow all -requests for that `Mapping` through without interacting with the -external auth service. - - - -## Transport Protocol Migration - - -> **Note:** The following information is only applicable to `AuthServices` using `proto: grpc` -As of $productName$ version 2.3, the `v2` transport protocol is deprecated and any AuthServices making use -of it should migrate to `v3` before support for `v2` is removed in a future release. - -The following imports simply need to be updated to migrate an AuthService - -`v2` Imports: -``` - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" -``` - -`v3` Imports: -``` - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" -``` diff --git a/content/en/docs/3.5/topics/running/services/ext-authz.md b/content/en/docs/3.5/topics/running/services/ext-authz.md deleted file mode 100644 index d850ba4b..00000000 --- a/content/en/docs/3.5/topics/running/services/ext-authz.md +++ /dev/null @@ -1,83 +0,0 @@ -# ExtAuth protocol - -By design, the ExtAuth protocol used by [the AuthService](../auth-service) and by [External Filters](/docs/edge-stack/latest/topics/using/filters/external) is highly flexible. The authentication service is the first external service invoked on an incoming request (e.g., it runs before the rate limit filter). Because the logic of authentication is encapsulated in an external service, you can use this to support a wide variety of use cases. For example: - -* Supporting traditional SSO authentication protocols, e.g., OAuth, OpenID Connect, etc. -* Supporting HTTP basic authentication ([see a sample implementation](https://github.com/datawire/ambassador-auth-httpbasic)). -* Only authenticating requests that are under a rate limit and rejecting authentication requests above the rate limit. -* Authenticating specific services (URLs), and not others. - -For each request, the ExtAuth service may either: - 1. return a direct HTTP *response*, intended to be sent back to the requesting HTTP client (normally *denying* the request from being forwarded to the upstream backend service) or - 2. return a modification to make to the HTTP *request* before sending it to the upstream backend service (normally *allowing* the request to be forwarded to the upstream backend service with modifications). - -The ExtAuth service receives information about every request through $productName$ and must indicate whether the request is to be allowed or not. If not, the ExtAuth service provides the HTTP response which is to be handed back to the client. A potential control flow for Authentication is shown in the image below. - -Giving the ExtAuth service the ability to control the response allows many different types of auth mechanisms, for example: - -- The ExtAuth service can simply return an error page with an HTTP 401 response. -- The ExtAuth service can choose to include a `WWW-Authenticate` header in the 401 response, to ask the client to perform HTTP Basic Auth. -- The ExtAuth service can issue a 301 `Redirect` to divert the client into an OAuth or OIDC authentication sequence. The control flow of this is shown below. ![Authentication flow](../../../images/auth-flow.png) - -There are two variants of the ExtAuth: gRPC and plain HTTP. - -### The gRPC protocol - -When `proto: grpc` is set, the ExtAuth service must implement the `Authorization` gRPC interface, defined in [Envoy's `external_auth.proto`](https://github.com/emissary-ingress/emissary/blob/master/api/envoy/service/auth/v3/external_auth.proto). - -### The HTTP protocol - -External services for `proto: http` are often easier to implement, but have several limitations compared to `proto: grpc`. - - The list of headers that the ExtAuth service is interested in reading must be known ahead of time, in order to set `allow_request_headers`. Inspecting headers that are not known ahead of time requires instead using `proto: grpc`. - - The list of headers that the ExtAuth service would like to set or modify must be known ahead of time, in order to set `allow_authorization_headers`. Setting headers that are not known ahead of time requires instead using `proto: grpc`. - - When returning a direct HTTP response, the HTTP status code cannot be 200 or in the 5XX range. Intercepting with a 200 or 5XX response requires instead using `proto: grpc`. - -#### The request From $productName$ to the ExtAuth service - -For every incoming request, a similar request is made to the ExtAuth service that mimics the: - - HTTP request method - - HTTP request path, potentially modified by `path_prefix` - - HTTP request headers that are either named in `allowed_request_headers` or in the fixed list of headers that are always included - - first `include_body.max_bytes` of the HTTP request body. - -The `Content-Length` HTTP header is set to the number of bytes in the body of the request sent to the ExtAuth service (`0` if `include_body` is not set). - -**ALL** request methods will be proxied, which implies that the ExtAuth service must be able to handle any request that any client could make. - -Take this incoming request for example: - -``` -PUT /path/to/service HTTP/1.1 -Host: myservice.example.com:8080 -User-Agent: curl/7.54.0 -Accept: */* -Content-Type: application/json -Content-Length: 27 - -{ "greeting": "hello world!", "spiders": "OMG no" } -``` - -The request $productName$ will make of the auth service is: - -``` -PUT /path/to/service HTTP/1.1 -Host: extauth.example.com:8080 -User-Agent: curl/7.54.0 -Accept: */* -Content-Type: application/json -Content-Length: 0 -``` - -#### The response returned from the ExtAuth service to $productName$ - - - If the HTTP response returned from the ExtAuth service to $productName$ has an HTTP status code of 200, then the request is allowed through to the upstream backend service. **Only** 200 indicates this; other 2XX status codes will prevent the request from being allowed through. - - The 200 response should not contain anything in the body, but may contain arbitrary headers. Any header present in the ExtAuth service' response that is also either listed in the `allow_authorization_headers` attribute of the AuthService resource or in the fixed list of headers that are always included will be copied from the ExtAuth service's response into the request going to the upstream backend service. This allows the ExtAuth service to inject tokens or other information into the request, or to modify headers coming from the client. - - The big limitation here is that the list of headers to be set must be known ahead of time, in order to set `allow_request_headers`. Setting headers that are not known ahead of time requires instead using `proto: grpc`. - - - If $productName$ cannot reach the ExtAuth service at all, if the ExtAuth service does not return a valid HTTP response, or if the HTTP response has an HTTP status code in the 5XX range, then the communication with the ExtAuth service is considered to have failed, and the `status_on_error` or `failure_mode_allow` behavior is triggered. - - - Any HTTP status code other than 200 or 5XX from the ExtAuth service tells $productName$ to **not** allow the request to continue to the upstream backend service, but that the ExtAuth service is instead intercepting the request. The entire HTTP response from the ExtAuth service--including the status code, the headers, and the body--is handed back to the client verbatim. This gives the ExtAuth service **complete** control over the entire response presented to the client. - - The big limitation here is that you cannot directly return a 200 or 5XX response. Intercepting with a 200 of 5XX response requires instead using `proto: grpc`. diff --git a/content/en/docs/3.5/topics/running/services/index.md b/content/en/docs/3.5/topics/running/services/index.md deleted file mode 100644 index 1646aa5a..00000000 --- a/content/en/docs/3.5/topics/running/services/index.md +++ /dev/null @@ -1,11 +0,0 @@ -# Available plugins - -You may need an API Gateway to enforce policies specific to your organization. $productName$ supports custom policies through external service plugins. The policy logic specific to your organization is implemented in the external service, and $productName$ is configured to send RPC requests to your service. - -Currently, $productName$ supports plugins for authentication, -access logging, rate limiting, and tracing. - -* [AuthService](auth-service) Plugin -* [LogService](log-service) Plugin -* [RateLimitService](rate-limit-service) Plugin -* [TracingService](tracing-service) Plugin diff --git a/content/en/docs/3.5/topics/running/services/log-service.md b/content/en/docs/3.5/topics/running/services/log-service.md deleted file mode 100644 index b3e90c7c..00000000 --- a/content/en/docs/3.5/topics/running/services/log-service.md +++ /dev/null @@ -1,116 +0,0 @@ -# Log service - -By default, $productName$ puts the access logs on stdout; such -that the can be read using `kubectl logs`. The format of those logs, -and the local destination of them, can be configured using the -[`envoy_log_` settings in the `ambassador -Module`](../../ambassador). However, the -options there only allow for logging local to $productName$'s Pod. By -configuring a `LogService`, you can configure $productName$ to -report its access logs to a remote service, in addition to the usual -`ambassador Module` configured logging. - -The remote access log service (or ALS) must implement the -`AccessLogService` gRPC interface, defined in [Envoy's `als.proto`][als.proto]. - -[als.proto]: https://github.com/emissary-ingress/emissary/blob/master/api/envoy/service/accesslog/v3/als.proto - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: LogService -metadata: - name: example-log-service -spec: - # Common to all $productName$ resources - ambassador_id: []string # optional; default is ["default"] - - # LogService specific - service: "string" # required - driver: "enum-string:[tcp, http]" # required - driver_config: # required - additional_log_headers: # optional; default is [] (only for `driver: http`) - - header_name: string # required - during_request: boolean # optional; default is true - during_response: boolean # optional; default is true - during_trailer: boolean # optional; default is true - flush_interval_time: int-seconds # optional; default is 1 - flush_interval_byte_size: integer # optional; default is 16384 - grpc: boolean # optional; default is false - protocol_version: enum # optional; default is v2 -``` - - - `service` is where to route the access log gRPC requests to - - - `driver` identifies which type of accesses to log; HTTP requests (`"http"`) or - TLS connections (`"tcp"`). - - - `driver_config` stores the configuration that is specific to the `driver`: - - * `driver: tcp` has no additional configuration; the config must - be set as `driver_config: {}`. - - * `driver: http` - - - `additional_log_headers` identifies HTTP headers to include in - the access log, and when in the logged-request's lifecycle to - include them. - - - `flush_interval_time` is the maximum number of seconds to buffer - accesses for before sending them to the ALS. The logs will be - flushed to the ALS every time this duration is reached, or when the - buffered data reaches `flush_interval_byte_size`, whichever comes - first. See the [Envoy documentation on - `buffer_flush_interval`][buffer_flush_interval] for more - information. - - - `flush_interval_byte_size` is a soft size limit for the access log - buffer. The logs will be flushed to the ALS every time the - buffered data reaches this size, or whenever `flush_interval_time` - elapses, whichever comes first. See the [Envoy documentation on - `buffer_size_bytes`][buffer_size_bytes] for more information. - - - `grpc` must be `true`. - -[buffer_flush_interval]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/access_loggers/grpc/v3/als.proto.html#extensions-access-loggers-grpc-v3-commongrpcaccesslogconfig -[buffer_size_bytes]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/access_loggers/grpc/v3/als.proto.html#extensions-access-loggers-grpc-v3-commongrpcaccesslogconfig - - - `protocol_version` was used in previous versions of $productName$ to control the gRPC service name used to communicate with the `LogService`. $productName$ 3.x is running an updated version of Envoy that has dropped support for the `v2` protocol, so starting in 3.x, if `protocol_version` is not specified, 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. - -## Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: LogService -metadata: - name: als -spec: - service: "als.default:3000" - driver: http - driver_config: {} # NB: driver_config must be set, even if it's empty - grpc: true # NB: grpc must be true and it will use the V3 transport protocol -``` - -## Transport Protocol Migration - - -> **Note:** The following information is only applicable to `AuthServices` using `proto: grpc` -As of $productName$ version 2.3, the `v2` transport protocol is deprecated and any AuthServices making use -of it should migrate to `v3` before support for `v2` is removed in a future release. - -The following imports simply need to be updated to migrate an AuthService - -`v2` Imports: -``` - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" -``` - -`v3` Imports: -``` - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" -``` diff --git a/content/en/docs/3.5/topics/running/services/rate-limit-service.md b/content/en/docs/3.5/topics/running/services/rate-limit-service.md deleted file mode 100644 index 39c2b0ce..00000000 --- a/content/en/docs/3.5/topics/running/services/rate-limit-service.md +++ /dev/null @@ -1,118 +0,0 @@ -# Rate limit service - -Rate limiting is a powerful technique to improve the [availability and -resilience of your -services](https://blog.getambassador.io/rate-limiting-a-useful-tool-with-distributed-systems-6be2b1a4f5f4). -In $productName$, each request can have one or more _labels_. These labels are -exposed to a third-party service via a gRPC API. The third-party service can -then rate limit requests based on the request labels. - -**Note that `RateLimitService` is only applicable to $OSSproductName$, -and not $AESproductName$, as $AESproductName$ includes a -built-in rate limit service.** - -## Request labels - -See [Attaching labels to -requests](../../../using/rate-limits#attaching-labels-to-requests) -for how to configure the labels that are attached to a request. - -## Domains - -In $productName$, each engineer (or team) can be assigned its own _domain_. A -domain is a separate namespace for labels. By creating individual domains, each -team can assign their own labels to a given request, and independently set the -rate limits based on their own labels. - -See [Attaching labels to -requests](../../../using/rate-limits/#attaching-labels-to-requests) -for how to labels under different domains. - -## External rate limit service - -In order for $productName$ to rate limit, you need to implement a -gRPC `RateLimitService`, as defined in [Envoy's `v3/rls.proto`] -interface. If you do not have the time or resources to implement your own rate -limit service, $AESproductName$ integrates a high-performance rate -limiting service. - -[envoy's `v3/rls.proto`]: https://github.com/emissary-ingress/emissary/tree/master/api/envoy/service/ratelimit/v3/rls.proto - -$productName$ generates a gRPC request to the external rate limit -service and provides a list of labels on which the rate limit service can base -its decision to accept or reject the request: - -``` -[ - {"source_cluster", ""}, - {"destination_cluster", ""}, - {"remote_address", ""}, - {"generic_key", ""}, - {"", ""} -] -``` - -If $productName$ cannot contact the rate limit service, it will -allow the request to be processed as if there were no rate limit service -configuration. - -It is the external rate limit service's responsibility to determine whether rate -limiting should take place, depending on custom business logic. The rate limit -service must simply respond to the request with an `OK` or `OVER_LIMIT` code: - -- If Envoy receives an `OK` response from the rate limit service, then $productName$ allows the client request to resume being processed by - the normal flow. -- If Envoy receives an `OVER_LIMIT` response, then $productName$ - will return an HTTP 429 response to the client and will end the transaction - flow, preventing the request from reaching the backing service. - -The headers injected by the [AuthService](../auth-service) can also be passed to -the rate limit service since the `AuthService` is invoked before the -`RateLimitService`. - -## Configuring the rate limit service - -A `RateLimitService` manifest configures $productName$ to use an -external service to check and enforce rate limits for incoming requests: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: RateLimitService -metadata: - name: ratelimit -spec: - service: 'example-rate-limit.default:5000' - protocol_version: # default is v2, if upgrading from 2.x then you must set this to v3. - failure_mode_deny: false # when set to true envoy will return 500 error when unable to communicate with RateLimitService -``` - -- `service` gives the URL of the rate limit service. If using a Kubernetes service, this should be the [namespace-qualified DNS name](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#namespaces-of-services) of that service. -- `protocol_version` Allowed values are `v3` and `v2`(default). `protocol_version` was used in previous versions of $productName$ to control the protocol used by the gRPC service to communicate with the `RateLimitService`. $productName$ 3.x is running an updated version of Envoy that has dropped support for the `v2` protocol, so starting in 3.x, if `protocol_version` is not specified, 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. -- `failure_mode_deny` By default, Envoy will fail open when unable to communicate with the service due to it becoming unvailable or due to timeouts. When this happens the upstream service that is being protected by a rate limit may be overloaded due to this behavior. When set to `true` Envoy will be configured to return a `500` status code when it is unable to communicate with the RateLimit service and will fail closed by rejecting request to the upstream service. - -You may only use a single `RateLimitService` manifest. - -## Rate limit service and TLS - -You can tell $productName$ to use TLS to talk to your service by -using a `RateLimitService` with an `https://` prefix. However, you may also -provide a `tls` attribute: if `tls` is present and `true`, $productName$ will originate TLS even if the `service` does not have the `https://` -prefix. - -If `tls` is present with a value that is not `true`, the value is assumed to be the name of a defined TLS context, which will determine the certificate presented to the upstream service. - -## Example - -The [$OSSproductName$ Rate Limiting -Tutorial](../../../../howtos/rate-limiting-tutorial) has a simple rate limiting -example. For a more advanced example, read the [advanced rate limiting -tutorial](../../../../../2.0/howtos/advanced-rate-limiting), which uses the rate limit -service that is integrated with $AESproductName$. - -## Further reading - -- [Rate limiting: a useful tool with distributed systems](https://blog.getambassador.io/rate-limiting-a-useful-tool-with-distributed-systems-6be2b1a4f5f4) -- [Rate limiting for API Gateways](https://blog.getambassador.io/rate-limiting-for-api-gateways-892310a2da02) -- [Implementing a Java Rate Limiting Service for $productName$](https://blog.getambassador.io/implementing-a-java-rate-limiting-service-for-the-ambassador-api-gateway-e09d542455da) -- [Designing a Rate Limit Service for $productName$](https://blog.getambassador.io/designing-a-rate-limiting-service-for-ambassador-f460e9fabedb) diff --git a/content/en/docs/3.5/topics/running/services/tracing-service.md b/content/en/docs/3.5/topics/running/services/tracing-service.md deleted file mode 100644 index b46e6870..00000000 --- a/content/en/docs/3.5/topics/running/services/tracing-service.md +++ /dev/null @@ -1,139 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Tracing Service - -Applications that consist of multiple services can be difficult to debug, as a single request can span multiple services. Distributed tracing tells the story of your request as it is processed through your system. Distributed tracing is a powerful tool to debug and analyze your system in addition to request logging and metrics. - -When enabled, the `TracingService` will instruct $productName$ to initiate a trace on requests by generating and populating an `x-request-id` HTTP header. Services can make use of this `x-request-id` header in logging and forward it in downstream requests for tracing. $productName$ also integrates with external trace visualization services, including Zipkin-compatible APIs such as [Zipkin](https://zipkin.io/) and [Jaeger](https://github.com/jaegertracing/) to allow you to store and visualize traces. You can read further on [Envoy's Tracing capabilities](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/tracing). - -A `TracingService` manifest configures $productName$ to use an external trace visualization service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TracingService -metadata: - name: tracing -spec: - service: "example-zipkin:9411" - driver: zipkin - config: {} - custom_tags: # optional - - tag: host - request_header: - name: ":authority" - default_value: "unknown" - - tag: path - request_header: - name: ":path" - default_value: "unknown" - sampling: - overall: 100 -``` - -| Field | Description | values | -| --------- | ----------- | ------------- | -| `service` | gives the URL of the external HTTP trace service. | ex. `example-zipkin:9411` | -| `driver` | provides the driver information that handles communicating with the service | enum:
`zipkin`
`datadog`
`opentelemetry` | -| `config` | provides additional configuration options for the selected `driver`. Supported configuration for each driver is found below. | | -| `tag_headers` | **Deprecated** - it is recommend that you switch to using `custom_tags`| | -| `custom_tags` | configure tags to attach to traces. See section below for more details. | | -| `propagation_modes` | (optional) if present, specifies a list of the propogation modes to be used | enum:
`ENVOY`
`B3`
`TRACE_CONTEXT` | -| `sampling` | (optional) if present, specifies some target percentages of requests that will be traced. | | - -Please note that you must use the HTTP/2 pseudo-header names. For example: - -- the `host` header should be specified as the `:authority` header; and -- the `method` header should be specified as the `:method` header. - - -$productName$ supports a single Global 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. - - -## Supported Tracing Drivers - -The `TracingService` currently supports the following drivers: - -- `zipkin` -- `datadog` -- `opentelemetry` - - -In Envoy 1.24, support for the 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 - - - -In $productName$ 3.5.0, support for Envoy's native OpenTelemetry driver was added to the TracingService. Envoy still considers this driver experimental. - - -## Sampling - -Configuring `sampling` will specify some target percentages of requests that will be traced. This is beneficial for high-volume services to control the amount of tracing data collected. Sampling can be configured with the following fields: - -- `client`: percentage of requests that will be force traced if the `x-client-trace-id` header is set. Defaults to 100. -- `random`: percentage of requests that will be randomly traced. Defaults to 100. -- `overall`: percentage of requests that will be traced after all other checks have been applied (force tracing, sampling, etc.). -This field functions as an upper limit on the total configured sampling rate. For instance, setting `client` -to `100%` but `overall` to `1%` will result in only `1%` of client requests with the appropriate headers to be force -traced. Defaults to 100. - -## Custom Tags and Tag Headers - -When collecting traces, $productName$ will attach tags to the `span`'s that are generated which are useful for observability. See the [Envoy Tracing Docs](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/tracing#what-data-each-trace-contains) for the default list of data collected. - -Previous versions of $productName$ only supported adding additional tags through the use of the `tag_headers` field. This field is now **deprecated** and it is recommended to use `custom_tags` which supports a more powerful set of features for adding additional tags to a span. - - -If both tag_headers and custom_tags are set then tag_headers will be ignored. - - -`custom_tags` provides support for configuring additional tags based on [Envoy Custom Tags](https://www.envoyproxy.io/docs/envoy/latest/api-v3/type/tracing/v3/custom_tag.proto%23custom-tag). The following custom tag kinds supported are: - -- `request_header` - set tag from header in the request -- `environment` - set tag from an environment variable -- `literal` - set tag based on a configured literal value - -Each custom_tag supports setting oneOf `request_header`, `literal` or `environment`. Each tag should have its own entry in `custom_tags`. - -For example: - -```yaml -custom_tags: - - tag: host - request_header: - name: ":authority" - default_value: "unknown host" # optional - - tag: path - request_header: ":path" - name: ":authority" - default_value: "unknown path" # optional - - tag: cluster - literal: - value: "us-east-cluster" - - tag: nodeID - environment: - name: SERVER_ID - default_value: "unknown" # optional -``` - -## Zipkin Driver Configurations - -- `collector_endpoint` gives the API endpoint of the Zipkin service where the spans will be sent. The default value is `/api/v2/spans` -- `collector_endpoint_version` gives the transport version used when sending data to your Zipkin collector. The default value is `HTTP_JSON` and it must be one of `HTTP_JSON` or `HTTP_PROTO`. -- `collector_endpoint_hostname` sets the hostname Envoy will use when sending data to your Zipkin collector. The default value is the name of the underlying Envoy cluster. -- `trace_id_128bit` whether a 128-bit `trace id` will be used when creating a new trace instance. Defaults to `true`. Setting to `false` will result in a 64-bit trace id being used. -- `shared_span_context` whether client and server spans will share the same `span id`. The default value is `true`. - -## Datadog Driver Configurations - -- `service_name` the name of the service which is attached to the traces. The default value is `ambassador`. - -## OpenTelemetry Driver Configurations - -- `service_name` the name of the service which is attached to traces. The default value is `ambassador`. - -## Example - -Check out the [DataDog](../../../../howtos/tracing-datadog) and [Zipkin](../../../../howtos/tracing-zipkin) HOWTOs. diff --git a/content/en/docs/3.5/topics/running/statistics/8877-metrics.md b/content/en/docs/3.5/topics/running/statistics/8877-metrics.md deleted file mode 100644 index 94bd2043..00000000 --- a/content/en/docs/3.5/topics/running/statistics/8877-metrics.md +++ /dev/null @@ -1,64 +0,0 @@ -# The metrics endpoint - -> For an overview of other options for gathering statistics on -> $productName$, see the [Statistics and Monitoring](../) overview. - -Each $productName$ pod exposes statistics and metrics for that pod at -`http://{POD}:8877/metrics`. The response is in the text-based -Prometheus [exposition format][]. - -[exposition format]: https://prometheus.io/docs/instrumenting/exposition_formats/ - -## Understanding the statistics - -The Prometheus exposition format includes special "HELP" lines that -make the file self-documenting as to what specific statistics mean. - - - -- `envoy_*`: See the [Envoy documentation][`GET /stats/prometheus`]. -- `ambassador_*`: - - `ambassador_edge_stack_*` (not present in $OSSproductName$): - - `ambassador_edge_stack_go_*`: See [`promethus.NewGoCollector()`][]. - - `ambassador_edge_stack_promhttp_*` See [`promhttp.Handler()`][]. - - `ambassador_edge_stack_process_*`: See [`promethus.NewProcessCollector()`][].. - - `ambassador_*_time_seconds` (for `*` = one of `aconf`, `diagnostics`, `econf`, `fetcher`, `ir`, or `reconfiguration`): - Gauges of how long the various core operations take in the diagd - process. - - `ambassador_diagnostics_(errors|notices)`: The number of - diagnostics errors and notices that would be shown in the - diagnostics UI or the Edge Policy Console. - - `ambassador_diagnostics_info`: [Info][`prometheus_client.Info`] - about the $productName$ install; all information is presented in - labels; the value of the Gauge is always "1". - - `ambassador_process_*`: See [`prometheus_client.ProcessCollector`][]. - -[`GET /stats/prometheus`]: https://www.envoyproxy.io/docs/envoy/v1.23.0/operations/admin.html#get--stats-prometheus -[`prometheus.NewProcessCollector`]: https://godoc.org/github.com/prometheus/client_golang/prometheus#NewProcessCollector -[`prometheus.NewGoCollector`]: https://godoc.org/github.com/prometheus/client_golang/prometheus#NewGoCollector -[`promhttp.Handler()`]: https://godoc.org/github.com/prometheus/client_golang/prometheus/promhttp#Handler -[`prometheus_client.Info`]: https://github.com/prometheus/client_python#info -[`prometheus_client.ProcessCollector`]: https://github.com/prometheus/client_python#process-collector - -## Polling the `:8877/metrics` endpoint with Prometheus - -To scrape metrics directly, follow the instructions for [Monitoring -with Prometheus and Grafana](../../../../howtos/prometheus). - -### Using Grafana to visualize statistics gathered by Prometheus - -#### Sample dashboard - -We provide a [sample Grafana dashboard](https://grafana.com/grafana/dashboards/4698-ambassador-edge-stack/) -that displays information collected by Prometheus from the -`:8877/metrics` endpoint. - -![Screenshot of a Grafana dashboard that displays just information from Envoy](../../../images/grafana.png) diff --git a/content/en/docs/3.5/topics/running/statistics/envoy-statsd.md b/content/en/docs/3.5/topics/running/statistics/envoy-statsd.md deleted file mode 100644 index 7cbcc208..00000000 --- a/content/en/docs/3.5/topics/running/statistics/envoy-statsd.md +++ /dev/null @@ -1,109 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Envoy statistics with StatsD - -> For an overview of other options for gathering statistics on -> $productName$, see the [Statistics and Monitoring](../) overview. - -At the core of $productName$ is [Envoy Proxy], which has built-in -support for exporting a multitude of statistics about its own -operations to StatsD (or to the modified DogStatsD used by Datadog). - -[Envoy Proxy]: https://www.envoyproxy.io - -If enabled, then $productName$ has Envoy expose this information via the -[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: - -```diff - spec: - containers: - - env: -+ - name: STATSD_ENABLED -+ value: "true" - - name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: -``` - -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. - -We have included a few example configurations in -[the `statsd-sink/` directory](https://github.com/emissary-ingress/emissary/tree/master/deployments/statsd-sink) -to help you get started. Clone or download the -repository to get local, editable copies and open a terminal -window in the `emissary/deployments/` folder. - -## Using Graphite as the StatsD sink - -[Graphite] is a web-based real-time graphing system. Spin up an -example Graphite setup: - -[Graphite]: http://graphite.readthedocs.org/ - -``` -kubectl apply -f statsd-sink/graphite/graphite-statsd-sink.yaml -``` - -This sets up the `statsd-sink` service and a deployment that contains -Graphite and its related infrastructure. Graphite's web interface is -available at `http://statsd-sink/` from within the cluster. Use port -forwarding to access the interface from your local machine: - -``` -SINKPOD=$(kubectl get pod -l service=statsd-sink -o jsonpath="{.items[0].metadata.name}") -kubectl port-forward $SINKPOD 8080:80 -``` - -This sets up Graphite access at `http://localhost:8080/`. - -## Using Datadog DogStatsD as the StatsD sink - -If you are a user of the [Datadog] monitoring system, pulling in the -Envoy statistics from $productName$ is very easy. - -[Datadog]: https://www.datadoghq.com/ - -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: - -```diff - spec: - containers: - - env: -+ - name: STATSD_ENABLED -+ value: "true" -+ - name: DOGSTATSD -+ value: "true" - - name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: -``` - -Then, you will need to deploy the DogStatsD agent in to your cluster -to act as the StatsD sink. To do this, replace the sample API key in -our [sample YAML file][`dd-statsd-sink.yaml`] with your own, then -apply that YAML: - -[`dd-statsd-sink.yaml`]: https://github.com/emissary-ingress/emissary/blob/master/deployments/statsd-sink/datadog/dd-statsd-sink.yaml - -``` -kubectl apply -f statsd-sink/datadog/dd-statsd-sink.yaml -``` - -This sets up the `statsd-sink` service and a deployment of the -DogStatsD agent that forwards the $productName$ statistics to your -Datadog account. - -Additionally, $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). diff --git a/content/en/docs/3.5/topics/running/statistics/index.md b/content/en/docs/3.5/topics/running/statistics/index.md deleted file mode 100644 index ab44009f..00000000 --- a/content/en/docs/3.5/topics/running/statistics/index.md +++ /dev/null @@ -1,84 +0,0 @@ -# Statistics and monitoring - -$productName$ collects many statistics internally, and makes it easy to -direct this information to a statistics and monitoring tool of your -choice. - -As an example, here are some interesting statistics to investigate: - -- `upstream_rq_total` is the total - number of requests that a particular service has received via $productName$. The rate of change of this value is one basic measure of - service utilization, i.e. requests per second. -- `upstream_rq_xx` is the total number - of requests to which a service responded with a given status code. - This value divided by the prior one, taken on - a rolling window basis, represents the recent response rate of the - service. There are corresponding classes for `2xx`, `3xx`, `4xx` and `5xx` counters that can - help clarify the nature of responses. -- `upstream_rq_time` is a Prometheus histogram or StatsD timer - that tracks the latency in milliseconds of a given service from $productName$'s perspective. - -## Overriding Statistics Names - -The optional `stats_name` element of every CRD that references a service (`Mapping`, `TCPMapping`, -`AuthService`, `LogService`, `RateLimitService`, and `TracingService`) can override the name under which cluster statistics -are logged (`usersvc` above). If not set, the default is the `service` value, with non-alphanumeric characters replaced by -underscores: - -- `service: foo` will just use `foo` -- `service: foo:8080` will use `foo_8080` -- `service: http://foo:8080` will use `http___foo_8080` -- `service: foo.othernamespace` will use `foo_othernamespace` - -The last example is worth special mention: a resource in a different namespace than the one in which $productName$ is running will automatically be qualified with the namespace of the resource itself. So, for example, if $productName$ is running in the `ambassador` namespace, and this `Mapping` is present in the `default` namespace: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: default-mapping - namespace: default -spec: - prefix: /default/ - service: default-service -``` - -then the `service` will be qualified to `default-service.default`, so the `stats_name` will be `default_service_default` rather than simply `default_service`. To change this behavior, set `stats_name` explicitly. - -## Monitoring Statistics - -There are several ways to get different statistics out of $productName$: - -- [The `:8877/metrics` endpoint](./8877-metrics) can be polled for - aggregated statistics (in a Prometheus-compatible format). This is - our recommended method as both Envoy metrics and $productName$ control plane - metrics are collected. -- $productName$ can push [Envoy statistics](./envoy-statsd) over the - StatsD or DogStatsD protocol. - -## The Four Golden Signals - -The [Four Golden Signals](https://sre.google/sre-book/monitoring-distributed-systems/) are four generally-accepted metrics -that are important to monitor for good information about service health: - -### Latency - -The time it takes to service a request as a histogram of time taken by individual requests, which can be an effective latency metric. -In StatsD, this stat would be expressed as `cluster.$name.upstream_rq_time`. -While in Prometheus format, this metric would be expressed as `envoy_cluster_upstream_rq_time_bucket{envoy_cluster_name="$name"}`. - -### Traffic - -The amount of demand being placed on your system as a gauge that shows the number of active outstanding requests, which can be a good proxy for traffic. -In StatsD, this stat would be expressed as `cluster.$name.upstream_rq_active`. -While in Prometheus format, this metric would be expressed as `envoy_cluster_upstream_rq_active{envoy_cluster_name="$name"}`. - -### Errors - -The number of failing requests. Some errors (e.g. a request succeeds, but gives the wrong answer) can only be detected by application-specific monitoring; however, many errors can be spotted simply by looking at the HTTP status code of requests. Monitoring it over time can show error rates. -In StatsD, `cluster.$name.upstream_rq_5xx` is a counter of HTTP `5xx` responses. -While in Prometheus, `envoy_cluster_upstream_rq_xx{envoy_response_code_class="5", envoy_cluster_name="$name"}` is a counter of HTTP `5xx` responses. - -### Saturation - -The hardest metric to measure, saturation describes how much of the total capability of the system to respond to requests is being used. Fully measuring saturation often requires application-specific monitoring, but looking at the 99th percentile of latency over a short window - perhaps a minute - can often give an early indication of saturation problems. diff --git a/content/en/docs/3.5/topics/running/tls/cleartext-redirection.md b/content/en/docs/3.5/topics/running/tls/cleartext-redirection.md deleted file mode 100644 index 7144b1a3..00000000 --- a/content/en/docs/3.5/topics/running/tls/cleartext-redirection.md +++ /dev/null @@ -1,76 +0,0 @@ -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`. - - - The 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. - - -## Cleartext Routing - -To allow cleartext to be routed, set the `requestPolicy.insecure.action` of a `Host` to `Route`: - -```yaml -requestPolicy: - insecure: - action: Redirect -``` - -This allows routing for either HTTP and HTTPS, or _only_ HTTP, depending on `tlsSecret` configuration: - -- If the `Host` does not specify a `tlsSecret`, it will only route HTTP, not terminating TLS at all. -- If the `Host` does specify a `tlsSecret`, it will route both HTTP and HTTPS. - - - The 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. - - -## HTTP->HTTPS redirection - -Most websites that force HTTPS will also automatically redirect any -requests that come into it over HTTP: - -``` -Client $productName$ -| | -| http:///api | -| --------------------------> | -| | -| 301: https:///api | -| <-------------------------- | -| | -| https:///api | -| --------------------------> | -| | -``` - -In $productName$, this is configured by setting the `insecure.action` in a `Host` to `Redirect`. - -```yaml -requestPolicy: - insecure: - action: Redirect -``` - -$productName$ determines which requests are secure and which are insecure using the -`securityModel` of the [`Listener`] that accepts the request. - -[`Listener`]: ../../listener - - - The 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. - diff --git a/content/en/docs/3.5/topics/running/tls/index.md b/content/en/docs/3.5/topics/running/tls/index.md deleted file mode 100644 index 850fb5c0..00000000 --- a/content/en/docs/3.5/topics/running/tls/index.md +++ /dev/null @@ -1,487 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Transport Layer Security (TLS) - -$productName$'s robust TLS support exposes configuration options -for many different TLS use cases, using the [`Host`](#host) and -[`TLSContext`](#host-and-tlscontext) resources in concert. - -## Certificates and Secrets - -Properly-functioning TLS requires the use of [TLS certificates] to prove that the -various systems communicating are who they say they are. At minimum, $productName$ -must have a server certificate that identifies it to clients; when [mTLS] or -[client certificate authentication] are in use, additional certificates are needed. - -You supply certificates to $productName$ in Kubernetes [TLS Secrets]. These Secrets -_must_ contain valid X.509 certificates with valid PKCS1, PKCS8, or Elliptic Curve private -keys. If a Secret does not contain a valid certificate, an error message will be logged, for -example: - -``` -tls-broken-cert.default.1 2 errors:; 1. K8sSecret secret tls-broken-cert.default tls.key cannot be parsed as PKCS1 or PKCS8: asn1: syntax error: data truncated; 2. K8sSecret secret tls-broken-cert.default tls.crt cannot be parsed as x.509: x509: malformed certificate -``` - -If you set the `AMBASSADOR_FORCE_SECRET_VALIDATION` environment variable, the invalid -Secret will be rejected, and a `Host` or `TLSContext` resource attempting to use an invalid -certificate will be disabled entirely. **Note** that in $productName$ $version$, this -includes disabling cleartext communication for such a `Host`. - -[TLS Certificates]: https://protonmail.com/blog/tls-ssl-certificate/ -[mTLS]: mtls -[client certificate authentication]: ../../../howtos/client-cert-validation/ -[TLS Secrets]: https://kubernetes.io/docs/concepts/configuration/secret/#tls-secrets - -## `Host` - -A `Host` represents a domain in $productName$ and defines how the domain manages TLS. For more information on the Host resource, see [The Host CRD reference documentation](../host-crd). - -**If no `Host`s are present**, $productName$ synthesizes a `Host` that -allows only cleartext routing. You will need to explictly define `Host`s to enable -TLS termination. - - - The examples below do not define a requestPolicy; however, most real-world - usage of $productName$ will require defining the requestPolicy.
-
- For more information, please refer to the Host documentation. - - -### Bring your own certificate - -The `Host` can read a certificate from a Kubernetes Secret and use that certificate -to terminate TLS on a domain. - -The following example shows the certificate contained in the Kubernetes Secret named -`host-secret` configured to have $productName$ terminate TLS on the `host.example.com` -domain: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: host-secret -``` - -By default, `tlsSecret` will only look for the named secret in the same namespace as the `Host`. -In the above example, the secret `host-secret` will need to exist within the `default` namespace -since that is the namespace of the `Host`. - -To reference a secret that is in a different namespace from the `Host`, the `namespace` field is required. -The below example will configure the `Host` to use the `host-secret` secret from the `example` namespace. - -```yaml ---- -apiVersion: getambassador.io/v2 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - acmeProvider: - authority: none - tlsSecret: - name: host-secret - namespace: example -``` - - - - The Kubernetes Secret named by 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. - - - -### Advanced TLS configuration with the `Host` - -You can specify TLS configuration directly in the `Host` via the `tls` field. This is the -recommended method to do more advanced TLS configuration for a single `Host`. - -For example, the configuration to enforce a minimum TLS version on the `Host` looks as follows: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: min-secret - tls: - min_tls_version: v1.2 -``` - - - - The Kubernetes Secret named by 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. - - - -The following fields are accepted in the `tls` field: -```yaml -tls: - cert_chain_file: # string - private_key_file: # string - ca_secret: # string - cacert_chain_file: # string - alpn_protocols: # string - cert_required: # bool - min_tls_version: # string - max_tls_version: # string - cipher_suites: # array of strings - ecdh_curves: # array of strings - sni: # string - crl_secret: # string -``` - -These fields have the same function as in the [`TLSContext`](#tlscontext) resource, -as described below. - -### `Host` and `TLSContext` - -You can link a `Host` to a [`TLSContext`](#tlscontext) instead of defining `tls` -settings in the `Host` itself. This is primarily useful for sharing settings between -multiple `Host`s. - -#### Link a `TLSContext` to the `Host` - - - It is invalid to use both the 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. - - -To link a [`TLSContext`](#tlscontext) with a `Host`, create a [`TLSContext`](#tlscontext) -with the desired configuration and link it to the `Host` by setting the `tlsContext.name` -field in the `Host`. For example, to enforce a minimum TLS version on the `Host` above, -create a `TLSContext` with any name with the following configuration: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: min-tls-context -spec: - hosts: - - host.example.com - secret: min-secret - min_tls_version: v1.2 -``` - -Next, link it to the `Host` via the `tlsContext` field as shown: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: min-secret - tlsContext: - name: min-tls-context -``` - - - - The `Host` and the `TLSContext` must name the same Kubernetes Secret; if not, - $productName$ will disable TLS for the `Host`. - - - - - - The Kubernetes Secret named by 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. - - - - - - The `Host`'s `hostname` and the `TLSContext`'s `hosts` must have compatible settings. If - they do not, requests may not be accepted. - - - -See [`TLSContext`](#tlscontext) below to read more on the description of these fields. - -#### Create a `TLSContext` with the name `{{AMBASSADORHOST}}-context` (DEPRECATED) - - - This implicit 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. - - -The `Host` will implicitly link to the `TLSContext` when a `TLSContext` exists with the following: - -- the name `{{NAME_OF_AMBASSADORHOST}}-context` -- `hosts` in the `TLSContext` set to the same value as `hostname` in the `Host`, and -- `secret` in the `TLSContext` set to the same value as `tlsSecret` in the `Host` - -**As noted above, this implicit linking is deprecated.** - -For example, another way to enforce a minimum TLS version on the `Host` above would -be to simply create the `TLSContext` with the name `example-host-context` and then not modify the `Host`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-host-context -spec: - hosts: - - host.example.com - secret: host-secret - min_tls_version: v1.2 -``` - - - - The `Host` and the `TLSContext` must name the same Kubernetes Secret; if not, - $productName$ will disable TLS for the `Host`. - - - - - - The Kubernetes Secret named by 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. - - - - - - The `Host`'s `hostname` and the `TLSContext`'s `hosts` must have compatible settings. If - they do not, requests may not be accepted. - - - -Full reference for all options available to the `TLSContext` can be found [below](#tlscontext). - -## TLSContext - -The `TLSContext` is used to configure advanced TLS options in $productName$. -Remember, a `TLSContext` must always be paired with a `Host`. - -A full schema of the `TLSContext` can be found below with descriptions of the -different configuration options. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-host-context -spec: - # 'hosts' defines the hosts for which this TLSContext is relevant. - # It ties into SNI. A TLSContext without "hosts" is useful only for - # originating TLS. - # type: array of strings - # - # hosts: [] - - # 'sni' defines the SNI string to use on originated connections. - # type: string - # - # sni: None - - # 'secret' defines a Kubernetes Secret that contains the TLS certificate we - # use for origination or termination. If not specified, $productName$ will look - # at the value of cert_chain_file and private_key_file. - # type: string - # - # secret: None - - # 'ca_secret' defines a Kubernetes Secret that contains the TLS certificate we - # use for verifying incoming TLS client certificates. - # type: string - # - # ca_secret: None - - # Tells $productName$ whether to interpret a "." in the secret name as a "." or - # a namespace identifier. - # type: boolean - # - # secret_namespacing: true - - # 'cert_required' can be set to true to _require_ TLS client certificate - # authentication. - # type: boolean - # - # cert_required: false - - # 'alpn_protocols' is used to enable the TLS ALPN protocol. It is required - # if you want to do GRPC over TLS; typically it will be set to "h2" for that - # case. - # type: string (comma-separated list) - # - # alpn_protocols: None - - # 'min_tls_version' sets the minimum acceptable TLS version: v1.0, v1.1, - # v1.2, or v1.3. It defaults to v1.0. - # min_tls_version: v1.0 - - # 'max_tls_version' sets the maximum acceptable TLS version: v1.0, v1.1, - # v1.2, or v1.3. It defaults to v1.3. - # max_tls_version: v1.3 - - # Tells $productName$ to load TLS certificates from a file in its container. - # type: string - # - # cert_chain_file: None - # private_key_file: None - # cacert_chain_file: None -``` - - - - `secret` and (if used) `ca_secret` must specify Kubernetes Secrets containing valid TLS - certificates. If `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and either Secret contains - an invalid certificate, $productName$ will reject the Secret, which will also completely - disable any `Host` using the `TLSContext`; see [**Certificates and Secrets**](#certificates-and-secrets) - above. - - - -### ALPN protocols - -The `alpn_protocols` setting configures the TLS ALPN protocol. To use gRPC over -TLS, set `alpn_protocols: h2`. If you need to support HTTP/2 upgrade from -HTTP/1, set `alpn_protocols: h2,http/1.1` in the configuration. - -#### HTTP/2 support - -The `alpn_protocols` setting is also required for HTTP/2 support. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls -spec: - secret: ambassador-certs - hosts: ["*"] - alpn_protocols: h2[, http/1.1] -``` -Without setting alpn_protocols as shown above, HTTP2 will not be available via -negotiation and will have to be explicitly requested by the client. - -If you leave off http/1.1, only HTTP2 connections will be supported. - -### TLS parameters - -The `min_tls_version` setting configures the minimum TLS protocol version that -$productName$ will use to establish a secure connection. When a client -using a lower version attempts to connect to the server, the handshake will -result in the following error: `tls: protocol version not supported`. - -The `max_tls_version` setting configures the maximum TLS protocol version that -$productName$ will use to establish a secure connection. When a client -using a higher version attempts to connect to the server, the handshake will -result in the following error: -`tls: server selected unsupported protocol version`. - -The `cipher_suites` setting configures the supported ciphers found below using the -[configuration parameters for BoringSSL](https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#Cipher-suite-configuration) when negotiating a TLS 1.0-1.2 connection. -This setting has no effect when negotiating a TLS 1.3 connection. When a client does not -support a matching cipher a handshake error will result. - -The `ecdh_curves` setting configures the supported ECDH curves when negotiating -a TLS connection. When a client does not support a matching ECDH a handshake -error will result. - -``` - - AES128-SHA - - AES256-SHA - - AES128-GCM-SHA256 - - AES256-GCM-SHA384 - - ECDHE-RSA-AES128-SHA - - ECDHE-RSA-AES256-SHA - - ECDHE-RSA-AES128-GCM-SHA256 - - ECDHE-RSA-AES256-GCM-SHA384 - - ECDHE-RSA-CHACHA20-POLY1305 - - ECDHE-ECDSA-AES128-SHA - - ECDHE-ECDSA-AES256-SHA - - ECDHE-ECDSA-AES128-GCM-SHA256 - - ECDHE-ECDSA-AES256-GCM-SHA384 - - ECDHE-ECDSA-CHACHA20-POLY1305 - - ECDHE-PSK-AES128-CBC-SHA - - ECDHE-PSK-AES256-CBC-SHA - - ECDHE-PSK-CHACHA20-POLY1305 - - PSK-AES128-CBC-SHA - - PSK-AES256-CBC-SHA - - DES-CBC3-SHA -``` - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls -spec: - hosts: ["*"] - secret: ambassador-certs - min_tls_version: v1.0 - max_tls_version: v1.3 - cipher_suites: - - "[ECDHE-ECDSA-AES128-GCM-SHA256|ECDHE-ECDSA-CHACHA20-POLY1305]" - - "[ECDHE-RSA-AES128-GCM-SHA256|ECDHE-RSA-CHACHA20-POLY1305]" - ecdh_curves: - - X25519 - - P-256 -``` - - -The `crl_secret` field allows you to reference a Kubernetes Secret that contains a certificate revocation list. -If specified, $productName$ will verify that the presented peer certificate has not been revoked by this CRL even if they are otherwise valid. This provides a way to reject certificates before they expire or if they become compromised. -The `crl_secret` field takes a PEM-formatted [Certificate Revocation List](https://en.wikipedia.org/wiki/Certificate_revocation_list) in a `crl.pem` entry. - -Note that if a CRL is provided for any certificate authority in a trust chain, a CRL must be provided for all certificate authorities in that chain. Failure to do so will result in verification failure for both revoked and unrevoked certificates from that chain. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls-crl -spec: - hosts: ["*"] - secret: ambassador-certs - min_tls_version: v1.0 - max_tls_version: v1.3 - crl_secret: 'ambassador-crl' ---- -apiVersion: v1 -kind: Secret -metadata: - name: ambassador-crl - namespace: ambassador -type: Opaque -data: - crl.pem: | - {BASE64 CRL CONTENTS} ---- -``` diff --git a/content/en/docs/3.5/topics/running/tls/mtls.md b/content/en/docs/3.5/topics/running/tls/mtls.md deleted file mode 100644 index 1b039cf8..00000000 --- a/content/en/docs/3.5/topics/running/tls/mtls.md +++ /dev/null @@ -1,88 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Mutual TLS (mTLS) - -Many organizations have security concerns that require all network traffic -throughout their cluster be encrypted. With traditional architectures, -this was not that complicated of a requirement since internal network traffic -was fairly minimal. With microservices, we are making many more requests over -the network that must all be authenticated and secured. - -In order for services to authenticate with each other, they will each need to -provide a certificate and key that the other trusts before establishing a -connection. This action of both the client and server providing and validating -certificates is referred to as mutual TLS. - -## mTLS with $productName$ - -Since $productName$ is a reverse proxy acting as the entry point to your cluster, -$productName$ is acting as the client as it proxies requests to services upstream. - -It is trivial to configure $productName$ to simply originate TLS connections as -the client to upstream services by setting -`service: https://{{UPSTREAM_SERVICE}}` in the `Mapping` configuration. -However, in order to do mTLS with services upstream, $productName$ must also -have certificates to authenticate itself with the service. - -To do this, we can use the `TLSContext` object to get certificates from a -Kubernetes `Secret` and use those to authenticate with the upstream service. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: upstream-context -spec: - hosts: [] - secret: upstream-certs -``` - -We use `hosts: []` for this `TLSContext` since we do not want to use it to terminate -TLS connections from the client. We are just using this to load certificates for -requests upstream. - - - - The Kubernetes Secret must contain a valid TLS certificate. If the environment - variable `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) in the TLS overview. - - - -After loading the certificates, we can tell $productName$ when to use them by -setting the `tls` parameter in a `Mapping`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: upstream-mapping -spec: - hostname: "*" - prefix: /upstream/ - service: upstream-service - tls: upstream-context -``` - -Now, when $productName$ proxies a request to `upstream-service`, it will provide -the certificates in the `upstream-certs` secret for authentication when -encrypting traffic. - -## Service mesh - -As you can imagine, when you have many services in your cluster all -authenticating with each other, managing all of those certificates can become a -very big challenge. - -For this reason, many organizations rely on a service mesh for their -service-to-service authentication and encryption. - -$productName$ integrates with multiple service meshes and makes it easy to -configure mTLS to upstream services for all of them. Click the links below to -see how to configure $productName$ to do mTLS with any of these service meshes: - -- [Consul Connect](../../../../howtos/consul/) - -- [Istio](../../../../howtos/istio/) diff --git a/content/en/docs/3.5/topics/running/tls/origination.md b/content/en/docs/3.5/topics/running/tls/origination.md deleted file mode 100644 index b15dd5f8..00000000 --- a/content/en/docs/3.5/topics/running/tls/origination.md +++ /dev/null @@ -1,82 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# TLS origination - -Sometimes you may want traffic from $productName$ to your services to be encrypted. For the cases where terminating TLS at the ingress is not enough, $productName$ can be configured to originate TLS connections to your upstream services. - -## Basic configuration - -Telling $productName$ to talk to your services over HTTPS is easily configured in the `Mapping` definition by setting `https://` in the `service` field. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: basic-tls -spec: - hostname: "*" - prefix: / - service: https://example-service -``` - -## Advanced configuration using a `TLSContext` - -If your upstream services require more than basic HTTPS support (for example, providing a client certificate or -setting the minimum TLS version support) you must create a `TLSContext` for $productName$ to use when -originating TLS. For example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls-context -spec: - secret: self-signed-cert - min_tls_version: v1.3 - sni: some-sni-hostname -``` - - - - The Kubernetes Secret named by `secret` must contain a valid TLS certificate. If the - environment variable `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and the Secret contains - an invalid certificate, $productName$ will reject the `TLSContext` and prevent its use; - see [**Certificates and Secrets**](../#certificates-and-secrets) in the TLS overview. - - - -Configure $productName$ to use this `TLSContext` for connections to upstream services by setting the `tls` attribute of a `Mapping`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-with-tls-context -spec: - hostname: "*" - prefix: / - service: https://example-service - tls: tls-context -``` - -The `example-service` service must now support TLS v1.3 for $productName$ to connect. - - - - The Kubernetes Secret named by `secret` must contain a valid TLS certificate. If the - environment variable `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and the Secret contains - an invalid certificate, $productName$ will reject the `TLSContext` and prevent its use; - see [**Certificates and Secrets**](../#certificates-and-secrets) in the TLS overview. - - - - - - A `TLSContext` requires a certificate be provided, even in cases where the upstream - service does not require it (for origination) and the `TLSContext` is not being used - to terminate TLS. In this case, simply generate and provide a self-signed certificate. - - diff --git a/content/en/docs/3.5/topics/running/tls/sni.md b/content/en/docs/3.5/topics/running/tls/sni.md deleted file mode 100644 index 92e4992f..00000000 --- a/content/en/docs/3.5/topics/running/tls/sni.md +++ /dev/null @@ -1,103 +0,0 @@ -# Server Name Indication (SNI) - -$productName$ supports serving multiple `Host`s behind a single IP address, each -with their own certificate. - -This is as easy to do as creating a `Host` for each domain or subdomain you -want $productName$ to serve, getting a certificate for each, and telling -$productName$ which `Host` the route should be created for. - -The example below configures two `Host`s and assigns routes to them. - -## Configuring a `Host` - -The `Host` resources lets you separate configuration for each distinct domain -and subdomain you plan on serving behind $productName$. - -Let's start by creating a simple `Host` and providing our own certificate in -the `host-cert` secret. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: host-cert -``` - -Now let's create a second `Host` for a different domain we want to serve behind -$productName$. This second `Host` uses $AESproductName$'s automatic TLS -to get a certificate from Let's Encrypt. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: host.foo.com - acmeProvider: - email: julian@example.com -``` - -We now have two `Host`s with two different certificates. - - - A minimum version of TLS 1.1 is required to properly use SNI. When setting up your TLS configuration, be sure you are not using TLS 1.0 or older. - - -## Configuring routes - -Now that we have two domains behind $productName$, we can create routes for either -or both of them. - -We do this by setting the `hostname` attribute of a `Mapping` to the domain the -`Mapping` should be created for. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin -spec: - prefix: /httpbin/ - service: httpbin.org:80 - host_rewrite: httpbin.org - hostname: host.example.com -``` - -The above creates a `/httpbin/` endpoint for `host.example.com`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mockbin -spec: - prefix: /foo/ - service: foo-service - hostname: host.foo.com -``` - -The above creates a `/foo/` endpoint for `host.foo.com`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: frontend -spec: - hostname: "*" - prefix: /bar/ - service: bar-endpoint -``` - -The above creates a `/bar/` endpoint for all `Host`s. diff --git a/content/en/docs/3.5/topics/using/authservice.md b/content/en/docs/3.5/topics/using/authservice.md deleted file mode 100644 index cfe3598b..00000000 --- a/content/en/docs/3.5/topics/using/authservice.md +++ /dev/null @@ -1,23 +0,0 @@ -# AuthService settings - -A Mapping can pass these settings along to an [AuthService](../../running/services/auth-service). This is helpful to allow these specific configurations to apply only to certain Mappings and not globally. - -## Bypass authentication - -An AuthService can be disabled for a specific Mapping with the `bypass_auth` attribute. This will tell $productName$ to allow all requests for that Mapping through without interacting with the external auth service. This could be helpful, for example, for a public API. - -```yaml -bypass_auth: true -``` - -## Context extensions - -The `auth_context_extensions` attribute will pass the given values along to the AuthService when authentication happens. The values are arbitrary key value pairs formatted as strings. - -```yaml -auth_context_extensions: - foo: bar - baz: zing -``` - -More information is available on [the Envoy documentation on external authentication](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto.html#extensions-filters-http-ext-authz-v3-checksettings). diff --git a/content/en/docs/3.5/topics/using/canary.md b/content/en/docs/3.5/topics/using/canary.md deleted file mode 100644 index f99de1a3..00000000 --- a/content/en/docs/3.5/topics/using/canary.md +++ /dev/null @@ -1,41 +0,0 @@ -# Canary releases - -Canary releasing is a deployment pattern where a small percentage of traffic is diverted to an early ("canary") release of a particular service. This technique lets you test a release on a small subset of users, mitigating the impact of any given bug. Canary releasing also allows you to quickly roll back to a known good version in the event of an unexpected error. Detailed monitoring of core service metrics is an essential part of canary releasing, as monitoring enables the rapid detection of problems in the canary release. - -## Canary releases in Kubernetes - -Kubernetes supports a basic canary release workflow using its core objects. In this workflow, a service owner can create a Kubernetes [service](https://kubernetes.io/docs/concepts/services-networking/service/). This service can then be pointed to multiple [deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/). Each deployment can be a different version. By specifying the number of `replicas` in a given deployment, you can control how much traffic goes between different versions. For example, you could set `replicas: 3` for `v1`, and `replicas: 1` for `v2`, to ensure that 25% of traffic goes to `v2`. This approach works but is fairly coarse-grained unless you have lots of replicas. Moreover, auto-scaling doesn't work well with this strategy. - -## Canary releases in $productName$ - -$productName$ supports fine-grained canary releases. $productName$ uses a weighted round-robin scheme to route traffic between multiple services. Full metrics are collected for all services, making it easy to compare the relative performance of the canary and production. - -### The weight attribute - -The `weight` attribute specifies how much traffic for a given resource will be routed using a given mapping. Its value is an integer percentage between 0 and 100. $productName$ will balance weights to make sure that, for every resource, the mappings for that resource will have weights adding to 100%. (In the simplest case, a single mapping is guaranteed to receive 100% of the traffic no matter whether it's assigned a `weight` or not.) - -Specifying a weight only makes sense if you have multiple mappings for the same resource, and typically you would _not_ assign a weight to the "default" mapping (the mapping expected to handle most traffic): letting $productName$ assign that mapping all the traffic not otherwise spoken for tends to make life easier when updating weights. - -Here's an example, which might appear during a canary deployment: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - prefix: /backend/ - service: quotev2 - weight: 10 -``` - -In this case, the quote-backend2 will receive 10% of the requests for `/backend/`, and $productName$ will assign the remaining 90% to the quote-backend. diff --git a/content/en/docs/3.5/topics/using/circuit-breakers.md b/content/en/docs/3.5/topics/using/circuit-breakers.md deleted file mode 100644 index 97b40f57..00000000 --- a/content/en/docs/3.5/topics/using/circuit-breakers.md +++ /dev/null @@ -1,116 +0,0 @@ -# Circuit breakers - -Circuit breakers are a powerful technique to improve resilience. By preventing additional connections or requests to an overloaded service, circuit breakers limit the ["blast radius"](https://www.ibm.com/garage/method/practices/manage/practice_limited_blast_radius/) of an overloaded service. By design, $productName$ circuit breakers are distributed, i.e., different $productName$ instances do not coordinate circuit breaker information. - -## Circuit breaker configuration - -A default circuit breaking configuration can be set for all -$productName$ resources in the [`ambassador -Module`](../../running/ambassador), or set to a different value on a -per-resource basis for [`Mappings`](../mappings), -[`TCPMappings`](../tcpmappings/), and -[`AuthServices`](../../running/services/auth-service/). - -The `circuit_breakers` attribute configures circuit breaking. The following fields are supported: - -```yaml -circuit_breakers: -- priority: - max_connections: - max_pending_requests: - max_requests: - max_retries: -``` - -|Key|Default value|Description| -|---|---|---| -|`priority`|`default`|Specifies the priority to which the circuit breaker settings apply to; it can be set to either `default` or `high`.| -|`max_connections`|`1024`|Specifies the maximum number of connections that $productName$ will make to the services. In practice, this is more applicable to HTTP/1.1 than HTTP/2.| -|`max_pending_requests`|`1024`|Specifies the maximum number of requests that will be queued while waiting for a connection. In practice, this is more applicable to HTTP/1.1 than HTTP/2.| -|`max_requests`|`1024`|Specifies the maximum number of parallel outstanding requests to an upstream service. In practice, this is more applicable to HTTP/2 than HTTP/1.1.| -|`max_retries`|`3`|Specifies the maximum number of parallel retries allowed to an upstream service.| - -The `max_*` fields can be reduced to shrink the "blast radius," or -increased to enable $productName$ to handle a larger number of -concurrent requests. - -## Examples - -Circuit breakers defined on a single `Mapping`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - circuit_breakers: - - max_connections: 2048 - max_pending_requests: 2048 -``` - -Circuit breakers defined on a single `AuthService`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: AuthService -metadata: - name: dancing-walrus -spec: - auth_service: http://dancing-walrus:8500 - proto: grpc - circuit_breakers: - - max_requests: 4096 -``` - -A global circuit breaker: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - circuit_breakers: - - max_connections: 2048 - max_pending_requests: 2048 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote -``` - -## Circuit breakers and automatic retries - -Circuit breakers are best used in conjunction with [automatic retries](../retries). Here are some examples: - -* You've configured automatic retries for failed requests to a service. Your service is under heavy load, and starting to time out on servicing requests. In this case, automatic retries can exacerbate your problem, increasing the total request volume by 2x or more. By aggressively circuit breaking, you can mitigate failure in this scenario. -* To circuit break when services are slow, you can combine circuit breakers with retries. Reduce the time out for retries, and then set a circuit breaker that detects many retries. In this setup, if your service doesn't respond quickly, a flood of retries will occur, which can then trip the circuit breaker. - -Note that setting circuit breaker thresholds requires careful monitoring and experimentation. We recommend you start with conservative values for circuit breakers and adjust them over time. - -## More about circuit breakers - -Responses from a broken circuit contain the `x-envoy-overloaded` header. - -The following are the default values for circuit breaking if nothing is specified: - -```yaml -circuit_breakers: -- priority: default - max_connections: 1024 - max_pending_requests: 1024 - max_requests: 1024 - max_retries: 3 -``` - -Circuit breaker metrics are exposed in StatsD. For more information about the specific statistics, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/circuit_breaking.html). diff --git a/content/en/docs/3.5/topics/using/cors.md b/content/en/docs/3.5/topics/using/cors.md deleted file mode 100644 index 315e4694..00000000 --- a/content/en/docs/3.5/topics/using/cors.md +++ /dev/null @@ -1,155 +0,0 @@ -# Cross-Origin Resource Sharing (CORS) - -Cross-Origin resource sharing lets users request resources (e.g., images, fonts, videos) from domains outside the original domain. - -CORS configuration can be set for all $productName$ mappings in the [`ambassador Module`](../../running/ambassador), or set per [`Mapping`](../mappings). - -When the CORS attribute is set at either the `Mapping` or `Module` level, $productName$ will intercept the pre-flight `OPTIONS` request and respond with the appropriate CORS headers. This means you will not need to implement any logic in your upstreams to handle these CORS `OPTIONS` requests. - -The flow of the request will look similar to the following: -``` -Client $productName$ Upstream - | OPTIONS | | - | —————————————————> | | - | CORS_RESP | | - | <————————————————— | | - | GET /foo/ | | - | —————————————————> | ————————————> | - | | RESP | - | <————————————————————————————————— | -``` -## The `cors` attribute - -The `cors` attribute enables the CORS filter. The following settings are supported: - -- `origins`: Specifies a list of allowed domains for the `Access-Control-Allow-Origin` header. To allow all origins, use the wildcard `"*"` value. Format can be either of: - - comma-separated list, e.g. - ```yaml - origins: http://foo.example,http://bar.example - ``` - - YAML array, e.g. - ```yaml - origins: - - http://foo.example - - http://bar.example - ``` - -- `methods`: if present, specifies a list of allowed methods for the `Access-Control-Allow-Methods` header. Format can be either of: - - comma-separated list, e.g. - ```yaml - methods: POST, GET, OPTIONS - ``` - - YAML array, e.g. - ```yaml - methods: - - GET - - POST - - OPTIONS - ``` - -- `headers`: if present, specifies a list of allowed headers for the `Access-Control-Allow-Headers` header. Format can be either of: - - comma-separated list, e.g. - ```yaml - headers: Content-Type - ``` - - YAML array, e.g. - ```yaml - headers: - - Content-Type - ``` - -- `credentials`: if present with a true value (boolean), will send a `true` value for the `Access-Control-Allow-Credentials` header. - -- `exposed_headers`: if present, specifies a list of allowed headers for the `Access-Control-Expose-Headers` header. Format can be either of: - - comma-separated list, e.g. - ```yaml - exposed_headers: X-Custom-Header - ``` - - YAML array, e.g. - ```yaml - exposed_headers: - - X-Custom-Header - ``` - -- `max_age`: if present, indicated how long the results of the preflight request can be cached, in seconds. This value must be a string. - -## Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cors -spec: - prefix: /cors/ - service: cors-example - cors: - origins: http://foo.example,http://bar.example - methods: POST, GET, OPTIONS - headers: Content-Type - credentials: true - exposed_headers: X-Custom-Header - max_age: "86400" -``` - -## AuthService and Cross-Origin Resource Sharing - -When you use external authorization, each incoming request is authenticated before routing to its destination, including pre-flight `OPTIONS` requests. - -By default, many [`AuthService`](../../running/services/auth-service) implementations will deny these requests. If this is the case, you will need to add some logic to your `AuthService` to accept all CORS headers. - -For example, a possible configuration for Spring Boot 2.0.1: - -```java -@EnableWebSecurity -class SecurityConfig extends WebSecurityConfigurerAdapter { - - public void configure(final HttpSecurity http) throws Exception { - http - .cors().configurationSource(new PermissiveCorsConfigurationSource()).and() - .csrf().disable() - .authorizeRequests() - .antMatchers("**").permitAll(); - } - - private static class PermissiveCorsConfigurationSource implements CorsConfigurationSource { - /** - * Return a {@link CorsConfiguration} based on the incoming request. - * - * @param request - * @return the associated {@link CorsConfiguration}, or {@code null} if none - */ - @Override - public CorsConfiguration getCorsConfiguration(final HttpServletRequest request) { - final CorsConfiguration configuration = new CorsConfiguration(); - configuration.setAllowCredentials(true); - configuration.setAllowedHeaders(Collections.singletonList("*")); - configuration.setAllowedMethods(Collections.singletonList("*")); - configuration.setAllowedOrigins(Collections.singletonList("*")); - return configuration; - } - } -} -``` - -This is okay since CORS is being handled by $productName$ after authentication. - -The flow of this request will look similar to the following: - -``` -Client $productName$ Auth Upstream - | OPTIONS | | | - | —————————————————> | ————————————> | | - | | CORS_ACCEPT_* | | - | CORS_RESP |<——————————————| | - | <——————————————————| | | - | GET /foo/ | | | - | —————————————————> | ————————————> | | - | | AUTH_RESP | | - | | <———————————— | | - | | AUTH_ALLOW | | - | | ————————————————————————————> | - | | | RESP | - | <————————————————————————————————————————————————— | - ``` diff --git a/content/en/docs/3.5/topics/using/defaults.md b/content/en/docs/3.5/topics/using/defaults.md deleted file mode 100644 index d08a84d8..00000000 --- a/content/en/docs/3.5/topics/using/defaults.md +++ /dev/null @@ -1,32 +0,0 @@ -# Using `ambassador` `Module` defaults - -## The defaults element - -If present, the `ambassador Module` can define a set of defaults that will automatically be applied to certain resources: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - class1: # This is a class. Different resource types will look in different classes. - key1: value1 # Within a class, you can set different keys. - key2: value2 - ... - class2: - ... - top_key1: value1 # If a key isn't found in a resource's class, the system will look in the - top_key2: value2 # toplevel defaults dictionary for it. -``` - -### Mapping - -Currently, only the `Mapping` resource uses the `defaults` mechanism. `Mapping` looks first for defaultable resources in the `httpmapping` class, including: - -- [`add_request_headers`](../../using/headers/add-request-headers) -- [`add_response_headers`](../../using/headers/add-response-headers) -- [`remove_request_headers`](../../using/headers/remove-request-headers) -- [`remove_response_headers`](../../using/headers/remove-response-headers) diff --git a/content/en/docs/3.5/topics/using/gateway-api.md b/content/en/docs/3.5/topics/using/gateway-api.md deleted file mode 100644 index 5e92cd0d..00000000 --- a/content/en/docs/3.5/topics/using/gateway-api.md +++ /dev/null @@ -1,19 +0,0 @@ -# Gateway API - -## Using the Gateway API - -$productName$ now supports a limited subset of the new `v1alpha1` [Gateway API](https://gateway-api.sigs.k8s.io/). -Note that the Gateway API is not supported when `AMBASSADOR_LEGACY_MODE` is set. - -Support is currently limited to the following fields, however this will expand in future releases: - - - `Gateway.spec.listeners.port` - - `HTTPRoute.spec.rules.matches.path.type` (`Exact`, `Prefix`, and `RegularExpression`) - - `HTTPRoute.spec.rules.matches.path.value` - - `HTTPRoute.spec.rules.matches.header.type` (`Exact` and `RegularExpression`) - - `HTTPRoute.spec.rules.matches.header.values` - - `HTTPRoute.spec.rules.forwardTo.serviceName` - - `HTTPRoute.spec.rules.forwardTo.port` - - `HTTPRoute.spec.rules.forwardTo.weight` - -Please see the [specification](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/) for more details. diff --git a/content/en/docs/3.5/topics/using/headers/add-request-headers.md b/content/en/docs/3.5/topics/using/headers/add-request-headers.md deleted file mode 100644 index c6ad4956..00000000 --- a/content/en/docs/3.5/topics/using/headers/add-request-headers.md +++ /dev/null @@ -1,77 +0,0 @@ -# Add request headers - -$productName$ can add a dictionary of HTTP headers that can be added to each request that is passed to a service. - -## The `add_request_headers` attribute - -The `add_request_headers` attribute is a dictionary of `header`: `value` pairs. The `value` can be a `string`, `bool` or `object`. When it is an `object`, the object should have a `value` property, which is the actual header value, and the remaining attributes are additional envoy properties. - -Envoy dynamic values `%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%` and `%PROTOCOL%` are supported, in addition to static values. - -`add_request_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -### Mapping example - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: "*" - prefix: /backend/ - add_request_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-static-2: - value: This the test header #same as above "x-test-static header" - x-test-object: - value: This the value - append: False #True by default - service: quote - ``` - -will add the protocol, client IP, and a static header to `/backend/`. - -### Defaults example - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - add_request_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-static-2: - value: This the test header #same as above "x-test-static header" - x-test-object: - value: This the value - append: False #True by default ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - hostname: "*" - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - hostname: "*" - prefix: /backend2/ - service: quote -``` - -This example will add the same headers for both mappings. diff --git a/content/en/docs/3.5/topics/using/headers/add-response-headers.md b/content/en/docs/3.5/topics/using/headers/add-response-headers.md deleted file mode 100644 index 236ace61..00000000 --- a/content/en/docs/3.5/topics/using/headers/add-response-headers.md +++ /dev/null @@ -1,73 +0,0 @@ -# Add response headers - -$productName$ can add a dictionary of HTTP headers that can be added to each response that is returned to the client. - -## The `add_response_headers` attribute - -The `add_response_headers` attribute is a dictionary of `header`: `value` pairs. The `value` can be a `string`, `bool` or `object`. When it is an `object`, the object should have a `value` property, which is the actual header value, and the remaining attributes are additional envoy properties. - -Envoy dynamic values `%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%` and `%PROTOCOL%` are supported, in addition to static values. - -`add_response_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -### Mapping example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - add_response_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-object: - append: False - value: this is from object header config - service: quote -``` - -will add the protocol, client IP, and a static header to the response returned to the client. - -### Defaults example - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - add_response_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-object: - append: False - value: this is from object header config ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - hostname: "*" - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - hostname: "*" - prefix: /backend2/ - service: quote -``` - -This example will add the same headers for both mappings. diff --git a/content/en/docs/3.5/topics/using/headers/headers.md b/content/en/docs/3.5/topics/using/headers/headers.md deleted file mode 100644 index 126653b0..00000000 --- a/content/en/docs/3.5/topics/using/headers/headers.md +++ /dev/null @@ -1,76 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Header-based routing - -$productName$ can route to target services based on HTTP headers with the `headers` and `regex_headers` specifications. Multiple mappings with different annotations can be applied to construct more complex routing rules. - -## The `headers` annotation - -The `headers` attribute is a dictionary of `header`: `value` pairs. $productName$ will only allow requests that match the specified `header`: `value` pairs to reach the target service. - -### Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - headers: - x-quote-mode: backend - x-random-header: datawire -``` - -will allow requests to /backend/ to succeed only if the x-quote-mode header has the value backend and the x-random-header has the value `datawire`. - - - 1.x versions of the Ambassador Edge Stack could test for the existence of a header using x-sample-header:true. Since 2.0, the same functionality is achieved by using regex_headers. - - -## Regex headers - -You can also set the `value` of a regex header to `".*"` to test for the existence of a header. - -### Conditional example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-mode -spec: - prefix: /backend/ - service: quote-mode - regex_headers: - x-quote-mode: ".*" - ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-regular -spec: - prefix: /backend/ - service: quote-regular -``` - -will send requests that contain the x-quote-mode header to the quote-mode target, while routing all other requests to the quote-regular target. - -The following mapping will route mobile requests from Android and iPhones to a mobile service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - regex_headers: - user-agent: ".*(iPhone|(a|A)ndroid).*" - prefix: /backend/ - service: quote -``` diff --git a/content/en/docs/3.5/topics/using/headers/host.md b/content/en/docs/3.5/topics/using/headers/host.md deleted file mode 100644 index 5a8dd02c..00000000 --- a/content/en/docs/3.5/topics/using/headers/host.md +++ /dev/null @@ -1,76 +0,0 @@ -# Host headers - -$productName$ supports several different methods for managing the HTTP `Host` header. - -## Using `host` and `host_regex` - -A mapping that specifies the `host` attribute will take effect _only_ if the HTTP `Host` header matches the value in the `host` attribute. If `host_regex` is `true`, the `host` value is taken to be a regular expression. Otherwise, an exact string match is required. - -You may have multiple mappings listing the same resource but different `host` attributes to effect `Host`-based routing. An example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote1 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend-2 -spec: - prefix: /backend/ - host: quote.datawire.io - service: quote2 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend-3 -spec: - prefix: /backend/ - host: "^quote[2-9]\\.datawire\\.io$" - host_regex: true - service: quote3 -``` - -will map requests for `/` to - -- the `quote2` service if the `Host` header is `quote.datawire.io`; -- the `quote3` service if the `Host` header matches `^quote[2-9]\\.datawire\\.io$`; and to -- the `quote1` service otherwise. - -Note that enclosing regular expressions in quotes can be important to prevent backslashes from being doubled. - -## Using `host_rewrite` - -By default, the `Host` header is not altered when talking to the service -- whatever `Host` header the client gave to $productName$ will be presented to the service. For many microservices, this will be fine, but if you use $productName$ to route to services that use the `Host` header for routing, it's likely to fail (legacy monoliths are particularly susceptible to this, as well as external services). You can use `host_rewrite` to force the `Host` header to whatever value that such target services need. - -An example: the default $productName$ configuration includes the following mapping for `httpbin.org`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin -spec: - prefix: /httpbin/ - service: httpbin.org:80 - host_rewrite: httpbin.org -``` - -As it happens, `httpbin.org` is virtually hosted, and it simply _will not_ function without a `Host` header of `httpbin.org`, which means that the `host_rewrite` attribute is necessary here. - -## `host` and `method` - -Internally: - -- the `host` attribute becomes a `header` match on the `:authority` header; and -- the `method` attribute becomes a `header` match on the `:method` header. - -You will see these headers in the diagnostic service if you use the `method` or `host` attributes. diff --git a/content/en/docs/3.5/topics/using/headers/remove-request-headers.md b/content/en/docs/3.5/topics/using/headers/remove-request-headers.md deleted file mode 100644 index 62603756..00000000 --- a/content/en/docs/3.5/topics/using/headers/remove-request-headers.md +++ /dev/null @@ -1,57 +0,0 @@ -# Remove request headers - -$productName$ can remove a list of HTTP headers that would be sent to the upstream from the request. - -## The `remove_request_headers` attribute - -The `remove_request_headers` attribute takes a list of keys used to match to the header. - -`remove_request_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -## Mapping example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - remove_request_headers: - - authorization - service: quote -``` - -will drop the header with key `authorization`. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - remove_request_headers: - - authorization ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - prefix: /backend2/ - service: quote -``` - -This is the same as the mapping example, but the headers will be removed for both mappings. diff --git a/content/en/docs/3.5/topics/using/headers/remove-response-headers.md b/content/en/docs/3.5/topics/using/headers/remove-response-headers.md deleted file mode 100644 index 16b18569..00000000 --- a/content/en/docs/3.5/topics/using/headers/remove-response-headers.md +++ /dev/null @@ -1,57 +0,0 @@ -# Remove response headers - -$productName$ can remove a list of HTTP headers that would be sent to the client in the response (e.g. default `x-envoy-upstream-service-time`). - -## The `remove_response_headers` attribute - -The `remove_response_headers` attribute takes a list of keys used to match to the header. - -`remove_request_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -## Mapping example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - remove_response_headers: - - x-envoy-upstream-service-time - service: quote -``` - -will drop the header with key `x-envoy-upstream-service-time`. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - remove_response_headers: - - x-envoy-upstream-service-time ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - prefix: /backend2/ - service: quote -``` - -This is the same as the mapping example, but the headers will be removed for both mappings. diff --git a/content/en/docs/3.5/topics/using/index.md b/content/en/docs/3.5/topics/using/index.md deleted file mode 100644 index d4f09a83..00000000 --- a/content/en/docs/3.5/topics/using/index.md +++ /dev/null @@ -1,32 +0,0 @@ -# Using $productName$ - -Application development teams use $productName$ to manage edge policies associated with a specific service. This section of the documentation covers core $productName$ elements that are typically used by the application development team. - -* [Introduction to Mappings](intro-mappings) The `Mapping` resource is the core resource used by every application development team. -* Mapping Configuration: - * [Automatic Retries](retries) - * [Canary Releases](canary) - * [Circuit Breakers](circuit-breakers) - * [Cross Origin Resource Sharing](cors) - * HTTP Headers - * [Header-based Routing](headers/headers) - * [Host Header](headers/host) - * [Adding Request Headers](headers/add-request-headers) - * [Adding Response Headers](headers/add-response-headers) - * [Removing Request Headers](headers/remove-request-headers) - * [Remove Response Headers](headers/remove-response-headers) - * [Query Parameter Based Routing](query-parameters) - * [Keepalive](keepalive) - * Protocols - * [TCP](tcpmappings) - * gRPC, HTTP/1.0, gRPC-Web, WebSockets - * [RegEx-based Routing](prefix-regex) - * [Redirects](redirects) - * [Rewrites](rewrites) - * [Timeouts](timeouts) - * [Traffic Shadowing](shadowing) -* [Advanced Mapping Configuration](mappings) -* Rate Limiting - * [Introduction to Rate Limits](rate-limits/) -* [Developer Portal](../../tutorials/dev-portal-tutorial) -* [Gateway API](gateway-api) diff --git a/content/en/docs/3.5/topics/using/intro-mappings.md b/content/en/docs/3.5/topics/using/intro-mappings.md deleted file mode 100644 index 51656052..00000000 --- a/content/en/docs/3.5/topics/using/intro-mappings.md +++ /dev/null @@ -1,148 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Introduction to the Mapping resource - -$productName$ is designed around a [declarative, self-service management model](../../concepts/gitops-continuous-delivery). The core resource used to support application development teams who need to manage the edge with $productName$ is the `Mapping` resource. - - - Remember that Listener and Host resources are -  required for a functioning $productName$ installation that can route traffic!
- Learn more about Listener.
- Learn more about Host. - - -## Quick example - -At its core a `Mapping` resource maps a `resource` to a `service`: - -| Required attribute | Description | -| :------------------------ | :------------------------ | -| `name` | is a string identifying the `Mapping` (e.g. in diagnostics) | -| [`prefix`](#resources) | is the URL prefix identifying your [resource](#resources) | -| [`service`](#services) | is the name of the [service](#services) handling the resource; must include the namespace (e.g. `myservice.othernamespace`) if the service is in a different namespace than $productName$ | - -These resources are defined as Kubernetes Custom Resource Definitions. Here's a simple example that maps all requests to `/httpbin/` to the `httpbin.org` web service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin-mapping -spec: - prefix: /httpbin/ - service: http://httpbin.org -``` - -## Applying a Mapping resource - -A `Mapping` resource can be managed using the same workflow as any other Kubernetes resources (e.g., `service`, `deployment`). For example, if the above `Mapping` is saved into a file called `httpbin-mapping.yaml`, the following command will apply the configuration directly to $productName$: - -``` -kubectl apply -f httpbin-mapping.yaml -``` - -For production use, the general recommended best practice is to store the file in a version control system and apply the changes with a continuous deployment pipeline. For more detail, see [the Ambassador Operating Model](../../concepts/gitops-continuous-delivery). - -## Extending Mappings - -`Mapping` resources support a rich set of annotations to customize the specific routing behavior. Here's an example service for implementing the CQRS pattern (using HTTP): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-get -spec: - prefix: /cqrs/ - method: GET - service: getcqrs ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-put -spec: - prefix: /cqrs/ - method: PUT - service: putcqrs -``` - -More detail on each of the available annotations are discussed in subsequent sections. - -## Resources - -To $productName$, a `resource` is a group of one or more URLs that all share a common prefix in the URL path. For example: - -``` -https://ambassador.example.com/resource1/foo -https://ambassador.example.com/resource1/bar -https://ambassador.example.com/resource1/baz/zing -https://ambassador.example.com/resource1/baz/zung -``` - -all share the `/resource1/` path prefix, so it can be considered a single resource. On the other hand: - -``` -https://ambassador.example.com/resource1/foo -https://ambassador.example.com/resource2/bar -https://ambassador.example.com/resource3/baz/zing -https://ambassador.example.com/resource4/baz/zung -``` - -share only the prefix `/` -- you _could_ tell $productName$ to treat them as a single resource, but it's probably not terribly useful. - -Note that the length of the prefix doesn't matter: if you want to use prefixes like `/v1/this/is/my/very/long/resource/name/`, go right ahead, $productName$ can handle it. - -Also note that $productName$ does not actually require the prefix to start and end with `/` -- however, in practice, it's a good idea. Specifying a prefix of - -``` -/man -``` - -would match all of the following: - -``` -https://ambassador.example.com/man/foo -https://ambassador.example.com/mankind -https://ambassador.example.com/man-it-is/really-hot-today -https://ambassador.example.com/manohmanohman -``` - -which is probably not what was intended. - -## Services - -$productName$ routes traffic to a `service`. A `service` is defined as: - -``` -[scheme://]service[.namespace][:port] -``` - -Where everything except for the `service` is optional. - -- `scheme` can be either `http` or `https`; if not present, the default is `http`. -- `service` is the name of a service (typically the service name in Kubernetes or Consul); it is not allowed to contain the `.` character. -- `namespace` is the namespace in which the service is running. Starting with $productName$ 1.0.0, if not supplied, it defaults to the namespace in which the Mapping resource is defined. The default behavior can be configured using the [`ambassador` Module](../../running/ambassador). When using a Consul resolver, `namespace` is not allowed. -- `port` is the port to which a request should be sent. If not specified, it defaults to `80` when the scheme is `http` or `443` when the scheme is `https`. Note that the [resolver](../../running/resolvers) may return a port in which case the `port` setting is ignored. - -Note that while using `service.namespace.svc.cluster.local` may work for Kubernetes resolvers, the preferred syntax is `service.namespace`. - -## Best practices for configuration - -$productName$'s configuration is assembled from multiple YAML blocks which are managed by independent application teams. This implies: - -- $productName$'s configuration should be under version control. - - While you can always read back the $productName$'s configuration from Kubernetes or its diagnostic service, the $productName$ will not do versioning for you. - -- Be aware that the $productName$ tries to not start with a broken configuration, but it's not perfect. - - Gross errors will result in $productName$ refusing to start, in which case `kubectl logs` will be helpful. However, it's always possible to e.g. map a resource to the wrong service, or use the wrong `rewrite` rules. $productName$ can't detect that on its own, although its diagnostic pages can help you figure it out. - -- Be careful of mapping collisions. - - If two different developers try to map `/user/` to something, this can lead to unexpected behavior. $productName$'s canary-deployment logic means that it's more likely that traffic will be split between them than that it will throw an error -- again, the diagnostic service can help you here. - -**Note:** Unless specified, mapping attributes cannot be applied to any other resource type. diff --git a/content/en/docs/3.5/topics/using/keepalive.md b/content/en/docs/3.5/topics/using/keepalive.md deleted file mode 100644 index d75e96ba..00000000 --- a/content/en/docs/3.5/topics/using/keepalive.md +++ /dev/null @@ -1,70 +0,0 @@ -# Keepalive - -Keepalive option indicates whether `SO_KEEPALIVE` on the socket should be enabled. - -## Keepalive configuration - -Keepalive configuration can be set for all $productName$ mappings in the [`ambassador Module`](../../running/ambassador) or set per [`Mapping`](../mappings). - -The `keepalive` attribute configures keepalive. The following fields are supported: - -```yaml -keepalive: - idle_time: - interval: - probes: -``` - -### `idle_time` - -(Default: `7200`) The number of seconds a connection needs to be idle before keep-alive probes start being sent. - -### `interval` - -(Default: `75`) The number of seconds between keep-alive probes. - -### `probes` - -(Default: `9`) is the maximum number of keepalive probes to send without response before deciding the connection is dead. - -## Examples - -Keepalive probes defined on a single mapping: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - keepalive: - idle_time: 100 - interval: 10 - probes: 9 -``` - -A global keepalive configuration: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - keepalive: - idle_time: 100 - interval: 10 - probes: 9 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote -``` diff --git a/content/en/docs/3.5/topics/using/mappings.md b/content/en/docs/3.5/topics/using/mappings.md deleted file mode 100644 index f930fc62..00000000 --- a/content/en/docs/3.5/topics/using/mappings.md +++ /dev/null @@ -1,189 +0,0 @@ -# Advanced Mapping configuration - -$productName$ is designed so that the author of a given Kubernetes service can easily and flexibly configure how traffic gets routed to the service. The core abstraction used to support service authors is a mapping, which maps a target backend service to a given host or prefix. For Layer 7 protocols such as HTTP, gRPC, or WebSockets, the `Mapping` resource is used. For TCP, the `TCPMapping` resource is used. - -$productName$ _must_ have one or more mappings defined to provide access to any services at all. The name of the mapping must be unique. - -## System-wide defaults for Mappings - -Certain aspects of mappings can be set system-wide using the `defaults` element of the `ambassador Module`: -see [using defaults](../../using/defaults) for more information. The `Mapping` element will look first in -the `httpmapping` default class. - -## Mapping evaluation order - -$productName$ sorts mappings such that those that are more highly constrained are evaluated before those less highly constrained. The prefix length, the request method, constraint headers, and query parameters are all taken into account. - -If absolutely necessary, you can manually set a `precedence` on the mapping (see below). In general, you should not need to use this feature unless you're using the `regex_headers` or `host_regex` matching features. If there's any question about how $productName$ is ordering rules, the diagnostic service is a good first place to look: the order in which mappings appear in the diagnostic service is the order in which they are evaluated. - -## Optional fallback Mapping - -$productName$ will respond with a `404 Not Found` to any request for which no mapping exists. If desired, you can define a fallback "catch-all" mapping so all unmatched requests will be sent to an upstream service. - -For example, defining a mapping with only a `/` prefix will catch all requests previously unhandled and forward them to an external service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: catch-all -spec: - prefix: / - service: https://www.getambassador.io -``` - -### Using `precedence` - -$productName$ sorts mappings such that those that are more highly constrained are evaluated before those less highly constrained. The prefix length, the request method, and the constraint headers are all taken into account. These mechanisms, however, may not be sufficient to guarantee the correct ordering when regular expressions or highly complex constraints are in play. - -For those situations, a `Mapping` can explicitly specify the `precedence`. A `Mapping` with no `precedence` is assumed to have a `precedence` of 0; the higher the `precedence` value, the earlier the `Mapping` is attempted. - -If multiple `Mapping`s have the same `precedence`, $productName$'s normal sorting determines the ordering within the `precedence`; however, there is no way that $productName$ can ever sort a `Mapping` with a lower `precedence` ahead of one at a higher `precedence`. - -### Using `tls` - -To originate TLS, use a `service` with an `https://` prefix. By itself, this will cause $productName$ to originate TLS without presenting a client certificate to the upstream service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-no-cert -spec: - prefix: /prefix/ - service: https://upstream/ -``` - -If you do need to supply a client certificate, you will also need to set `tls` to the name of a defined TLS context. The client certificate given in that context will be presented to the upstream service. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-with-cert -spec: - prefix: /prefix/ - service: https://upstream/ - tls: upstream-cert-context -``` - -(If `tls` is present, $productName$ will originate TLS even if the `service` does not have an `https://` prefix.) - -### Using `cluster_tag` - -If the `cluster_tag` attribute is present, its value will be prepended to cluster names generated from -the `Mapping`. This provides a simple mechanism for customizing the `cluster` name when working with metrics. - -## Using `dns_type` - -If the `dns_type` attribute is present, its value will determine how the DNS is used when locating the upstream service. Valid values are: - -- `strict_dns` (the default): The DNS result is assumed to define the exact membership of the cluster. For example, if DNS returns three IP addresses, the cluster is assumed to have three distinct upstream hosts. If a successful DNS query returns no hosts, the cluster is assumed to be empty. `strict_dns` makes sense for situations like a Kubernetes service, where DNS resolution is fast and returns a relatively small number of IP addresses. - -- `logical_dns`: Instead of assuming that the DNS result defines the full membership of the cluster, every new connection simply uses the first IP address returned by DNS. `logical_dns` makes sense for a service with a large number of IP addresses using round-robin DNS for upstream load balancing: typically each DNS query returns a different first result, and it is not necessarily possible to know the full membership of the cluster. With `logical_dns`, no attempt is made to garbage-collect connections: they will stay open until the upstream closes them. - -If `dns_type` is not given, `strict_dns` is the default, as this is the most conservative choice. When interacting with large web services with many IP addresses, switching to `logical_dns` may be a better choice. For more on the different types of DNS, see the [`strict_dns` Envoy documentation] or the [`logical_dns` Envoy documentation]. - -[`strict_dns` Envoy documentation]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/service_discovery#strict-dns -[`logical_dns` Envoy documentation]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/service_discovery#logical-dns - - -## Namespaces and Mappings - -If `AMBASSADOR_NAMESPACE` is correctly set, $productName$ can map to services in other namespaces by taking advantage of Kubernetes DNS: - -- `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. - -### Linkerd interoperability (`add_linkerd_headers`) - -When using Linkerd, requests going to an upstream service need to include the `l5d-dst-override` header to ensure that Linkerd will route them correctly. Setting `add_linkerd_headers` does this automatically, based on the `service` attribute in the `Mapping`. - -If `add_linkerd_headers` is not specified for a given `Mapping`, the default is taken from the `ambassador`[Module](../../running/ambassador). The overall default is `false`: you must explicitly enable `add_linkerd_headers` for $productName$ to add the header for you (although you can always add it yourself with `add_request_headers`, of course). - -### "Upgrading" to non-HTTP protocols (`allow_upgrade`) - -HTTP has [a mechanism][upgrade-mechanism] where the client can say -`Connection: upgrade` / `Upgrade: PROTOCOL` to switch ("upgrade") from -the current HTTP version to a different one, or even a different -protocol entirely. $productName$ itself understands and can handle the -different HTTP versions, but for other protocols you need to tell -$productName$ to get out of the way, and let the client speak that -protocol directly with your upstream service. You can do this by -setting the `allow_upgrade` field to a case-insensitive list of -protocol names $productName$ will allow switching to from HTTP. After -the upgrade, $productName$ does not interpret the traffic, and behaves -similarly to how it does for `TCPMapping`s. - -[upgrade-mechanism]: https://tools.ietf.org/html/rfc7230#section-6.7 - -This "upgrade" mechanism is a useful way of adding HTTP-based -authentication and access control to another protocol that might not -support authentication; for this reason the designers of the WebSocket -protocol made this "upgrade" mechanism the *only* way of initiating a -WebSocket connection. In a Mapping for an upstream service that -supports WebSockets, you would write - -```yaml -allow_upgrade: -- websocket -``` - -The Kubernetes apiserver itself uses this "upgrade" mechanism to -perform HTTP authentication before switching to SPDY for endpoint used -by `kubectl exec`; if you wanted to use $productName$ to expose the -Kubernetes apiserver such that `kubectl exec` functions, you would -write - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: apiserver -spec: - hostname: "*" - service: https://kubernetes.default - prefix: / - allow_upgrade: - - spdy/3.1 -``` - -There is a deprecated setting `use_websocket`; setting `use_websocket: -true` is equivalent to setting `allow_upgrade: ["websocket"]`. - -## DNS configuration for Mappings - -`respect_dns_ttl` can be set to `true` to force the DNS refresh rate for this `Mapping` to be set to the record’s TTL obtained from DNS resolution. -- Allowed values: `true` or `false` -- Default: `false` - - -`dns_type` can be used to configure the service discovery type between Strict DNS and Logical DNS. You can -- Allowed values: - - `strict_dns`: Ambassador will continuously and asynchronously resolve the specified DNS targets. - - `logical_dns`: Similar to `strict_dns`, but only uses the first IP address returned when a new connection needs to be initiated and Connections are never drained. More optimal for large scale web services that must be accessed via DNS. -- Default: `strict_dns` - - -For more information on the differences between dns types, see [the Envoy documentation for service discovery](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/service_discovery.html). - -> **Note:** When the [endpoint resolver](../../running/resolvers/#the-kubernetes-endpoint-resolver) is used in a `Mapping`, `dns_type` will be ignored in favor of the endpoint resolver's service discovery. - - - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: dnsoverwrite -spec: - service: quote - prefix: /backend/ - dns_type: logical_dns - respect_dns_ttl: true -``` diff --git a/content/en/docs/3.5/topics/using/method.md b/content/en/docs/3.5/topics/using/method.md deleted file mode 100644 index 94185dcd..00000000 --- a/content/en/docs/3.5/topics/using/method.md +++ /dev/null @@ -1,26 +0,0 @@ -# Method-based routing - -$productName$ supports routing based on the HTTP method and regular expression. - -## Using `method` - -The `method` annotation specifies the specific HTTP method for a mapping. The value of the `method` annotation must be in all upper case. - -For example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: get -spec: - hostname: "*" - prefix: /backend/get_only/ - method: GET - service: quote -``` - -## Using `method_regex` - -When `method_regex` is set to `true`, the value of the `method` annotation will be interpreted as a regular expression. diff --git a/content/en/docs/3.5/topics/using/prefix-regex.md b/content/en/docs/3.5/topics/using/prefix-regex.md deleted file mode 100644 index 04a6e4b8..00000000 --- a/content/en/docs/3.5/topics/using/prefix-regex.md +++ /dev/null @@ -1,25 +0,0 @@ -# Prefix regex - -## Using `prefix` and `prefix_regex` - -When the `prefix_regex` attribute is set to `true`, $productName$ configures a [regex route](https://www.envoyproxy.io/docs/envoy/v1.5.0/api-v1/route_config/route#route) instead of a prefix route in Envoy. **This means the entire path must match the regex specified, not only the prefix.** - -## Example with a version in the URL - -If the version is a path parameter and the resources are served by different services, then - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: qotm -spec: - prefix: "/(v1|v2)/qotm/.*" - prefix_regex: true - service: qotm -``` - -will map requests to both `/v1` and `/v2` to the `qotm` service. - -Note that enclosing regular expressions in quotes can be important to prevent backslashes from being doubled. diff --git a/content/en/docs/3.5/topics/using/query-parameters.md b/content/en/docs/3.5/topics/using/query-parameters.md deleted file mode 100644 index 0bd5eb13..00000000 --- a/content/en/docs/3.5/topics/using/query-parameters.md +++ /dev/null @@ -1,70 +0,0 @@ -# Query parameter-based routing - -$productName$ can route to target services based on HTTP query parameters with the `query_parameters` and `regex_query_parameters` specifications. Multiple mappings with different annotations can be applied to construct more complex routing rules. - -## The `query_parameters` annotation - -The `query_parameters` attribute is a dictionary of `query_parameter`: `value` pairs. $productName$ will only allow requests that match the specified `query_parameter`: `value` pairs to reach the target service. - -You can also set the `value` of a query parameter to `true` to test for the existence of a query parameter. - -### A basic example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - query_parameters: - quote-mode: backend - random-query-parameter: datawire -``` - -This will allow requests to /backend/ to succeed only if the `quote-mode` query parameter has the value `backend` and the `random-query-parameter` has the value `datawire`. - -### A conditional example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-mode -spec: - prefix: /backend/ - service: quote-mode - query_parameters: - quote-mode: true - ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-regular -spec: - prefix: /backend/ - service: quote-regular -``` - -This will send requests that contain the `quote-mode` query parameter to the `quote-mode` target, while routing all other requests to the `quote-regular` target. - -## `regex_query_parameters` - -The following mapping will route requests with the `quote-mode` header that contain values that match the regex. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - regex_query_parameters: - quote-mode: "^[a-z].*" - prefix: /backend/ - service: quote -``` diff --git a/content/en/docs/3.5/topics/using/rate-limits/index.md b/content/en/docs/3.5/topics/using/rate-limits/index.md deleted file mode 100644 index b65f8c5d..00000000 --- a/content/en/docs/3.5/topics/using/rate-limits/index.md +++ /dev/null @@ -1,199 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Basic rate limiting - -Rate limiting in $productName$ is composed of two parts: - -* The [`RateLimitService`](../../running/services/rate-limit-service) resource tells $productName$ what external service - to use for rate limiting. - - If $productName$ cannot contact the rate limit service, it will allow the request to be processed as if there were no rate limit service configuration. - -* _Labels_ that get attached to requests. A label is basic metadata that - is used by the `RateLimitService` to decide which limits to apply to - the request. - - - These labels require Mapping resources with apiVersion - getambassador.io/v2 or newer — if you're updating an old installation, check the - apiVersion! - - -Labels are grouped according to _domain_ and _group_: - -```yaml -labels: - "domain1": - - "group1": - - "my_label_specifier_1" - - "my_label_specifier_2" - - "group2": - - "my_label_specifier_3" - - "my_label_specifier_4" - "domain2": - - ... -``` - -The names of domains and groups are not interpreted by $productName$ in any way: -they are solely there to help configuration authors remember the different groupings. -Note that **at present, rate limiting supports just one domain**: the name of the -domain must be configured in the [`RateLimitService`](../../running/services/rate-limit-service). - - - -## Attaching labels to requests - -There are two ways of setting labels on a request: - -1. You can set labels on an individual [`Mapping`](../mappings). These labels - will only apply to requests that use that `Mapping`. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Mapping - metadata: - name: foo-mapping - spec: - hostname: "*" - prefix: /foo/ - service: foo - labels: - "domain1": - - "group1": - - "my_label_specifier_1" - - "my_label_specifier_2" - - "group2": - - "my_label_specifier_3" - - "my_label_specifier_4" - "domain2": - - ... - ``` - -2. You can set global labels in the [`ambassador` `Module`](../../running/ambassador). - These labels will apply to _every_ request that goes through $productName$. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - spec: - config: - default_labels: - "domain1": - defaults: - - "my_label_specifier_a" - - "my_label_specifier_b" - "domain2": - defaults: - - "my_label_specifier_c" - - "my_label_specifier_d" - ``` - - If a `Mapping` and the defaults both give label groups for the same domain, the - default labels are prepended to each label group from the `Mapping`. If the `Mapping` - does not give any labels for that domain, the global labels are placed into a new - label group named "default" for that domain. - -Each label group is a list of labels; each label is a key/value pair. Since the label -group is a list rather than a map: -- it is possible to have multiple labels with the same key, and -- the order of labels matters. - -> Note: The terminology used by the Envoy documentation differs from -> the terminology used by $productName$: -> -> | $productName$ | Envoy | -> |-----------------|-------------------| -> | label group | descriptor | -> | label | descriptor entry | -> | label specifier | rate limit action | - -The `Mapping`s' listing of the groups of specifiers have names for the -groups; the group names are useful for humans dealing with the YAML, -but are ignored by $productName$, all $productName$ cares about are the -*contents* of the groupings of label specifiers. - -There are 5 types of label specifiers in $productName$: - - - -1. `source_cluster` - - ```yaml - source_cluster: - key: source_cluster - ``` - - Sets the label `source_cluster=«Envoy source cluster name»"`. The Envoy - source cluster name is the name of the Envoy cluster that the request came - in on. - - The syntax of this label currently _requires_ `source_cluster: {}`. - -2. `destination_cluster` - - ```yaml - destination_cluster: - key: destination_cluster - ``` - - Sets the label `destination_cluster=«Envoy destination cluster name»"`. The Envoy - destination cluster name is the name of the Envoy cluster to which the `Mapping` - routes the request. You can get the name for a cluster from the - [diagnostics service](../../running/diagnostics). - - The syntax of this label currently _requires_ `destination_cluster: {}`. - -3. `remote_address` - - ```yaml - remote_address: - key: remote_address - ``` - - Sets the label `remote_address=«IP address of the client»"`. The IP address of - the client will be taken from the `X-Forwarded-For` header, to correctly manage - situations with L7 proxies. This requires that $productName$ be correctly - [configured to communicate](../../../howtos/configure-communications). - - The syntax of this label currently _requires_ `remote_address: {}`. - -4. `request_headers` - - ```yaml - request_headers: - header_name: "header-name" - key: mykey - ``` - - If a header named `header-name` is present, set the label `mykey=«value of the header»`. - If no header named `header-name` is present, **the entire label group is dropped**. - -5. `generic_key` - - ```yaml - generic_key: - key: mykey - value: myvalue - ``` - - Sets the label `«mykey»=«myval»`. Note that supplying a `key` is supported only - with the Envoy V3 API. - -## Rate limiting requests based on their labels - -This is determined by your `RateLimitService` implementation. See the -[Basic Rate Limiting tutorial](../../../howtos/rate-limiting-tutorial) for an -example `RateLimitService` implementation for $productName$. - -If you'd rather not write your own `RateLimitService` implementation, -$AESproductName$ provides a `RateLimitService` implementation that is -configured by a `RateLimit` custom resource. See the -[$AESproductName$ RateLimit Reference](/docs/edge-stack/latest/topics/using/rate-limits/rate-limits/) -for more information. diff --git a/content/en/docs/3.5/topics/using/redirects.md b/content/en/docs/3.5/topics/using/redirects.md deleted file mode 100644 index f55c467d..00000000 --- a/content/en/docs/3.5/topics/using/redirects.md +++ /dev/null @@ -1,142 +0,0 @@ -# Redirects - -$productName$ can perform 3xx redirects on `Mapping`s to a different host, with various options to redirect the path and to return a different 3xx response code instead of the default 301. - -## Schema - -| Name | Type | Description | -| --- | --- | --- | -| `spec.host_redirect` | Boolean | This is *required* to be set to `true` to use any type of redirect, otherwise the request will be proxied instead of redirected. | -| `spec.path_redirect` | String | Optional, changes the path for the redirect. | -| `spec.prefix_redirect` | String | Optional, matches the `prefix` value and replaces it with the `prefix_redirect` value. | -| `spec.regex_redirect` | String | Optional, uses regex to match and replace the `prefix` value. | -| `spec.redirect_response_code` | Integer | Optional, changes the response code from the default 301, valid values are 301, 302, 303, 307, and 308. | -| `spec.config. x_forwarded_proto_redirect` | Boolean | Redirect only the originating HTTP requests to HTTPS, allowing the originating HTTPS requests to pass through. | -| `spec.config. use_remote_address` | Boolean | Required to be set to `false` to use the `x_forwarded_proto_redirect` feature. | - -## Examples - -### Basic redirect - -To effect any type of HTTP `Redirect`, the `Mapping` *must* set `host_redirect` to `true`, with `service` set to the host to which the client should be redirected: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - prefix: /redirect/ - service: httpbin.org - host_redirect: true - hostname: '*' -``` - -Using this `Mapping`, a request to `http://$AMBASSADOR_URL/redirect/` will be redirected to `http://httpbin.org/redirect/`. - -> As always with $productName$, the trailing `/` on any URL with a -`Mapping` is required! - -### Path redirect - -The `Mapping` may optionally also set additional properties to customize the behavior of the HTTP redirect response. - -To also change the path portion of the URL during the redirect, set `path_redirect`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - hostname: '*' - prefix: /redirect/ - service: httpbin.org - host_redirect: true - path_redirect: /ip -``` - -Here, a request to `http://$AMBASSADOR_URL/redirect/` will be redirected to `http://httpbin.org/ip/`. - -### Prefix redirect - -To change only a prefix of the path portion of the URL, set `prefix_redirect`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - hostname: '*' - prefix: /redirect/path/ - service: httpbin.org - host_redirect: true - prefix_redirect: /ip -``` - -Now, a request to `http://$AMBASSADOR_URL/redirect/path/` will be redirected to `http://httpbin.org/ip/`. The prefix `/redirect/path/` was matched and replaced with `/ip/`. - -### Regex redirect - -`regex_redirect` matches a regular expression to replace instead of a fixed prefix. -[See more information about using regex with $productName$](../rewrites/#regex_rewrite). - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - prefix: /foo/ - service: httpbin.org - host_redirect: true - regex_redirect: - pattern: '/foo/([0-9]*)/list' - substitution: '/bar/\1' -``` -A request to `http://$AMBASSADOR_URL/foo/12345/list` will be redirected to -`http://$AMBASSADOR_URL/bar/12345`. - -### Redirect response code - -To change the HTTP response code return by $productName$, set `redirect_reponse_code`. If this is not set, 301 is returned by default. Valid values include 301, 302, 303, 307, and 308. This -can be used with any type of redirect. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - prefix: /ip/ - service: httpbin.org - host_redirect: true - redirect_response_code: 302 -``` - -A request to `http://$AMBASSADOR_URL/ip/` will result in an HTTP 302 redirect to `http://httpbin.org/ip`. - -### X-FORWARDED-PROTO redirect - -In cases when TLS is being terminated at an external layer 7 load balancer, then you would want to redirect only the originating HTTP requests to HTTPS, and let the originating HTTPS requests pass through. - -This distinction between an originating HTTP request and an originating HTTPS request is done based on the `X-FORWARDED-PROTO` header that the external layer 7 load balancer adds to every request it forwards after TLS termination. - -To enable this `X-FORWARDED-PROTO` based HTTP to HTTPS redirection, add a `x_forwarded_proto_redirect: true` field to `ambassador Module`'s configuration. Note that when this feature is enabled `use_remote_address` MUST be set to false. - -An example configuration is as follows - - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - x_forwarded_proto_redirect: true - use_remote_address: false -``` - -Note: Setting `x_forwarded_proto_redirect: true` will impact all your $productName$ mappings. Every HTTP request to $productName$ will only be allowed to pass if it has an `X-FORWARDED-PROTO: https` header. diff --git a/content/en/docs/3.5/topics/using/retries.md b/content/en/docs/3.5/topics/using/retries.md deleted file mode 100644 index d018ab59..00000000 --- a/content/en/docs/3.5/topics/using/retries.md +++ /dev/null @@ -1,84 +0,0 @@ -# Automatic retries - -Sometimes requests fail. When these requests fail for transient issues, $productName$ can automatically retry the request. - -Retry policy can be set for all $productName$ mappings in the [`ambassador Module`](../../running/ambassador), or set per [`Mapping`](../mappings). Generally speaking, you should set `retry_policy` on a per mapping basis. Global retries can easily result in unexpected cascade failures. - -> Note that when setting `retry_policy`, adjusting `max_retries` in the [circuit breaker](https://www.getambassador.io/docs/edge-stack/pre-release/topics/using/circuit-breakers/) configuration should also be considered in order to account for all desired retries. - -## Configuring retries - -The `retry_policy` attribute configures automatic retries. The following fields are supported: - -```yaml -retry_policy: - retry_on: - num_retries: - per_try_timeout: -``` - -### `retry_on` - -(Required) Specifies the condition under which $productName$ retries a failed request. - -| Value | Description | -| --- | --- | -|`5xx`| Retries if the upstream service responds with any 5xx code or does not respond at all -|`gateway-error`| Similar to a `5xx` but only applies to a 502, 503, or 504 response -|`connect-failure`| Retries on a connection failure to the upstream service (included in `5xx`) -|`retriable-4xx`| Retries on a retriable 4xx response (currently only 409) -|`refused-stream`| Retires if the upstream service sends a REFUSED_STREAM error (included in `5xx`) -|`retriable-status-codes`| Retries based on status codes set in the `x-envoy-retriable-status-codes` header. If that header isn't set, $productName$ will not retry the request. - - For more details on each of these values, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/v1.9.0/configuration/http_filters/router_filter#x-envoy-retry-on). - -### `num_retries` - -(Default: 1) Specifies the number of retries to execute for a failed request. - -### `per_try_timeout` - -(Default: global request timeout) Specify the timeout for each retry. Must be in seconds or nanoseconds, e.g., `1s`, `1500ns`. - -## Examples - -A per mapping retry policy: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - retry_policy: - retry_on: "5xx" - num_retries: 10 -``` - -A global retry policy (not recommended): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - retry_policy: - retry_on: "retriable-4xx" - num_retries: 4 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - hostname: '*' -``` diff --git a/content/en/docs/3.5/topics/using/rewrites.md b/content/en/docs/3.5/topics/using/rewrites.md deleted file mode 100644 index 44d0a961..00000000 --- a/content/en/docs/3.5/topics/using/rewrites.md +++ /dev/null @@ -1,100 +0,0 @@ -# Rewrites - -Once $productName$ uses a prefix to identify the service to which a given request should be passed, it can rewrite the URL before handing it off to the service. - -There are two approaches for rewriting: `rewrite` for simpler scenarios and `regex_rewrite` for more advanced rewriting. - -**Please note that** only one of these two can be configured for a mapping **at the same time**. As a result $productName$ ignores `rewrite` when `regex_rewrite` is provided. - -## `rewrite` - -By default, the `prefix` is rewritten to `/`, so e.g., if we map `/backend-api/` to the service `service1`, then - - -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/content/en/docs/3.5/topics/using/shadowing.md b/content/en/docs/3.5/topics/using/shadowing.md deleted file mode 100644 index dd95fbba..00000000 --- a/content/en/docs/3.5/topics/using/shadowing.md +++ /dev/null @@ -1,78 +0,0 @@ -# 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. - -![Shadowing](../../images/shadowing.png) - -## 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/content/en/docs/3.5/topics/using/tcpmappings.md b/content/en/docs/3.5/topics/using/tcpmappings.md deleted file mode 100644 index f246e799..00000000 --- a/content/en/docs/3.5/topics/using/tcpmappings.md +++ /dev/null @@ -1,300 +0,0 @@ -# `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/content/en/docs/3.5/topics/using/timeouts.md b/content/en/docs/3.5/topics/using/timeouts.md deleted file mode 100644 index ae004102..00000000 --- a/content/en/docs/3.5/topics/using/timeouts.md +++ /dev/null @@ -1,66 +0,0 @@ -# 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/content/en/docs/3.5/tutorials/dev-portal-tutorial.md b/content/en/docs/3.5/tutorials/dev-portal-tutorial.md deleted file mode 100644 index d3c0d0a8..00000000 --- a/content/en/docs/3.5/tutorials/dev-portal-tutorial.md +++ /dev/null @@ -1,29 +0,0 @@ -# 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:///docs/` to see the -publicly visible Developer Portal. Make sure you include the trailing `/`. -This is a fully customizable portal that you can share with third parties who -need information about your APIs. diff --git a/content/en/docs/3.5/tutorials/getting-started.md b/content/en/docs/3.5/tutorials/getting-started.md deleted file mode 100644 index 1fb11cec..00000000 --- a/content/en/docs/3.5/tutorials/getting-started.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: "Getting Started with $productName$" -description: "Learn how to install $productName$ with either Helm or kubectl to get started routing traffic from the edge of your Kubernetes cluster to your services..." ---- - -import Alert from '@material-ui/lab/Alert'; -import GettingStartedEmissary21Tabs from './gs-tabs' - -# $productName$ quick start - -
-

Contents

- -- [1. Installation](#1-installation) - - [Connecting your installation to Ambassador Cloud](#connecting-your-installation-to-ambassador-cloud) -- [2. Routing traffic from the edge](#2-routing-traffic-from-the-edge) -- [What's next?](#img-classos-logo-srcimageslogopng-whats-next) - -
- -## 1. Installation - -We'll start by installing $productName$ into your cluster. - -**We recommend using Helm** but there are other options below to choose from. - - - -### Connecting your installation to Ambassador Cloud - -Now is a great moment to connect your new installation to Ambassador Cloud in order to fully leverage the power of $productName$ and the Developer Control Plane (DCP). - -1. Log in to [Ambassador Cloud](https://app.getambassador.io/cloud/services/) with GitHub, GitLab or Google and select your team account. - -2. At the top, click **Add Services** then click **Connection Instructions** in the "Connect your installation" section. - -3. Follow the prompts to name the cluster and click **Generate a Cloud Token**. - -4. Follow the prompts to install the cloud token into your cluster. - -5. When the token installation completes, your services will be listed in the DCP. - -Success! At this point, you have installed $productName$. Now let's get some traffic flowing to your services. - -## 2. Routing traffic from the edge - -$productName$ uses Kubernetes Custom Resource Definitions (CRDs) to declaratively define its desired state. The workflow you are going to build uses a simple demo app, a **`Listener` CRD**, and a **`Mapping` CRD**. The `Listener` CRD tells $productName$ what port to listen on, and the `Mapping` CRD tells $productName$ how to route incoming requests by host and URL path from the edge of your cluster to Kubernetes services. - -1. Start by creating a `Listener` resource for HTTP on port 8080: - - ``` - kubectl apply -f - < - This 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.
-
- Learn more about Listener.
- Learn more about Host. - - -2. Apply the YAML for the "Quote" service. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/quickstart/qotm.yaml - ``` - - The Service and Deployment are created in your default namespace. You can use 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](#connecting-your-installation-to-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` - - ![](../images/mapping-editor.png) - - 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 - <Victory! You have created your first $productName$ 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/content/en/docs/3.5/tutorials/gs-tabs.js b/content/en/docs/3.5/tutorials/gs-tabs.js deleted file mode 100644 index eb392504..00000000 --- a/content/en/docs/3.5/tutorials/gs-tabs.js +++ /dev/null @@ -1,131 +0,0 @@ -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 ( - - ); -} - -TabPanel.propTypes = { - children: PropTypes.node, - index: PropTypes.any.isRequired, - value: PropTypes.any.isRequired, -}; - -function a11yProps(index) { - return { - id: `simple-tab-${index}`, - 'aria-controls': `simple-tabpanel-${index}`, - }; -} - -const useStyles = makeStyles((theme) => ({ - root: { - flexGrow: 1, - backgroundColor: 'transparent', - }, -})); - -export default function GettingStartedEmissary21Tabs(props) { - const version = props.version; - const classes = useStyles(); - const [value, setValue] = React.useState(0); - - const handleChange = (event, newValue) => { - setValue(newValue); - }; - - return ( -
- - - } - label="Helm 3" - {...a11yProps(0)} - style={{ minWidth: '10%', textTransform: 'none' }} - /> - } - label="Kubernetes YAML" - {...a11yProps(1)} - style={{ minWidth: '10%', textTransform: 'none' }} - /> - - - - {/*Helm 3 install instructions*/} - - - {'# Add the Repo:' + - '\n' + - 'helm repo add datawire https://app.getambassador.io' + - '\n' + - 'helm repo update' + - '\n \n' + - '# Create Namespace and Install:' + - '\n' + - 'kubectl create namespace emissary && \\' + - '\n' + - `kubectl apply -f https://app.getambassador.io/yaml/emissary/${version}/emissary-crds.yaml` + - '\n' + - 'kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system' + - '\n' + - 'helm install emissary-ingress --namespace emissary datawire/emissary-ingress && \\' + - '\n' + - 'kubectl -n emissary wait --for condition=available --timeout=90s deploy -lapp.kubernetes.io/instance=emissary-ingress' + - '\n'} - - - - - {/*YAML install instructions*/} - - - {'kubectl create namespace emissary && \\' + - '\n' + - `kubectl apply -f https://app.getambassador.io/yaml/emissary/${version}/emissary-crds.yaml && \\` + - '\n' + - 'kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system' + - '\n' + - `kubectl apply -f https://app.getambassador.io/yaml/emissary/${version}/emissary-emissaryns.yaml && \\` + - '\n' + - 'kubectl -n emissary wait --for condition=available --timeout=90s deploy -lproduct=aes' + - '\n'} - - -
- ); -} diff --git a/content/en/docs/3.5/tutorials/gs-tabs2.js b/content/en/docs/3.5/tutorials/gs-tabs2.js deleted file mode 100644 index bfd95047..00000000 --- a/content/en/docs/3.5/tutorials/gs-tabs2.js +++ /dev/null @@ -1,174 +0,0 @@ -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'; - -function TabPanel(props) { - const { children, value, index, ...other } = props; - - return ( - - ); -} - -TabPanel.propTypes = { - children: PropTypes.node, - index: PropTypes.any.isRequired, - value: PropTypes.any.isRequired, -}; - -function a11yProps(index) { - return { - id: `simple-tab-${index}`, - 'aria-controls': `simple-tabpanel-${index}`, - }; -} - -const useStyles = makeStyles((theme) => ({ - root: { - flexGrow: 1, - backgroundColor: 'transparent', - }, -})); - -export default function SimpleTabs() { - const classes = useStyles(); - const [value, setValue] = React.useState(0); - - const handleChange = (event, newValue) => { - setValue(newValue); - }; - - return ( -
- - - - - - - - - - {/*Helm 3 token install instructions*/} - Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Helm. The slideout contains instructions with a - unique cloud-connect-token that is used to connect your - cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'helm upgrade ambassador --namespace ambassador datawire/ambassador \\' + - '\n' + - ' --set agent.cloudConnectToken=$TOKEN && \\' + - '\n' + - 'kubectl -n ambassador wait --for condition=available --timeout=90s deploy -lproduct=aes'} - - - - - {/*Helm 2 token install instructions*/} - Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Helm. The slideout contains instructions with a - unique cloud-connect-token that is used to connect your - cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'helm upgrade --namespace ambassador ambassador datawire/ambassador \\' + - '\n' + - ' --set crds.create=false --set agent.cloudConnectToken=$TOKEN && \\' + - '\n' + - 'kubectl -n ambassador wait --for condition=available --timeout=90s deploy -lproduct=aes'} - - - - - {/*YAML token install instructions*/} - Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Kubernetes YAML. The slideout contains instructions - with a unique cloud-connect-token that is used to connect - your cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'kubectl create configmap -n ambassador ambassador-agent-cloud-token \\' + - '\n' + - ' --from-literal=CLOUD_CONNECT_TOKEN=$TOKEN'} - - - - - {/*edgectl token install instructions*/} - Connecting $productName$ that was installed via edgectl is - identical to the Kubernetes YAML procedure. -
- Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Kubernetes YAML. The slideout contains instructions - with a unique cloud-connect-token that is used to connect - your cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'kubectl create configmap -n ambassador ambassador-agent-cloud-token \\' + - '\n' + - ' --from-literal=CLOUD_CONNECT_TOKEN=$TOKEN'} - - -
- ); -} diff --git a/content/en/docs/3.5/tutorials/quickstart-demo.md b/content/en/docs/3.5/tutorials/quickstart-demo.md deleted file mode 100644 index 70cbce8b..00000000 --- a/content/en/docs/3.5/tutorials/quickstart-demo.md +++ /dev/null @@ -1,176 +0,0 @@ -# $productName$ Tutorial - -In this article, you will explore some of the key features of $productName$ by walking through an example workflow and exploring the -Edge Policy Console. - -## Prerequisites - -You must have [$productName$ installed](../getting-started/) in your -Kubernetes cluster. - -## Routing Traffic from the Edge - -Like any other Kubernetes object, Custom Resource Definitions (CRDs) are used to -declaratively define $productName$’s desired state. The workflow you are going to -build uses a sample deployment and the `Mapping` CRD, which is the core resource -that you will use with $productName$ to manage your edge. It enables you to route -requests by host and URL path from the edge of your cluster to Kubernetes services. - -1. Copy the configuration below and save it to a file named `quote.yaml` so that -you can deploy these resources to your cluster. This basic configuration creates -the `quote` deployment and a service to expose that deployment on port 80. - - ```yaml - --- - apiVersion: apps/v1 - kind: Deployment - metadata: - name: quote - namespace: ambassador - spec: - replicas: 1 - selector: - matchLabels: - app: quote - strategy: - type: RollingUpdate - template: - metadata: - labels: - app: quote - spec: - containers: - - name: backend - image: docker.io/datawire/quote:$quoteVersion$ - ports: - - name: http - containerPort: 8080 - --- - apiVersion: v1 - kind: Service - metadata: - name: quote - namespace: ambassador - spec: - ports: - - name: http - port: 80 - targetPort: 8080 - selector: - app: quote - ``` - -1. Apply the configuration to the cluster with the command `kubectl apply -f quote.yaml`. - -1. Copy the configuration below and save it to a file called `quote-backend.yaml` -so that you can create a `Mapping` on your cluster. This `Mapping` tells $productName$ to route all traffic inbound to the `/backend/` path, on any host that can be used to reach $productName$, to the `quote` service. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Mapping - metadata: - name: quote-backend - namespace: ambassador - spec: - hostname: "*" - prefix: /backend/ - service: quote - ``` - -1. Apply the configuration to the cluster with the command -`kubectl apply -f quote-backend.yaml` - -1. Store the $productName$ `LoadBalancer` address to a local environment variable. -You will use this variable to test accessing your pod. - - ``` - export AMBASSADOR_LB_ENDPOINT=$(kubectl -n ambassador get svc ambassador -o "go-template={{range .status.loadBalancer.ingress}}{{or .ip .hostname}}{{end}}") - ``` - -1. Test the configuration by accessing the service through the $productName$ load -balancer. - - ``` - $ curl -Lk "https://$AMBASSADOR_LB_ENDPOINT/backend/" - { - "server": "idle-cranberry-8tbb6iks", - "quote": "Non-locality is the driver of truth. By summoning, we vibrate.", - "time": "2019-12-11T20:10:16.525471212Z" - } - ``` - -Success, you have created your first $productName$ `Mapping`, routing a -request from your cluster's edge to a service! - -Since the `Mapping` you just created controls how requests are routed, -changing the `Mapping` will immediately change the routing. To see this -in action, use `kubectl` to edit the `Mapping`: - -1. Run `kubectl edit Mapping quote-backend`. - -1. Change `prefix: /backend/` to `prefix: /quoteme/`. - -1. Save the file and let `kubectl` update your `Mapping`. - -1. Run `kubectl get Mappings --namespace ambassador`. You will see the -`quote-backend` `Mapping` has the updated prefix listed. Try to access the -endpoint again via `curl` with the updated prefix. - - ``` - $ kubectl get Mappings --namespace ambassador - NAME PREFIX SERVICE STATE REASON - quote-backend /quoteme/ quote - - $ curl -Lk "https://${AMBASSADOR_LB_ENDPOINT}/quoteme/" - { - "server": "snippy-apple-ci10n7qe", - "quote": "A principal idea is omnipresent, much like candy.", - "time": "2020-11-18T17:15:42.095153306Z" - } - ``` - -1. Change the prefix back to `/backend/` so that you can later use the `Mapping` -with other tutorials. - -## 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. In the Edge Policy Console, navigate to the **APIs** tab. You'll see the -OpenAPI documentation there for the "Quote Service API." Click **GET** to -expand out the documentation. - -1. Navigate to `https:///docs/` to see the -publicly visible Developer Portal. Make sure you include the trailing `/`. -This is a fully customizable portal that you can share with third parties who -need information about your APIs. - -## Next Steps - -Further explore some of the concepts you learned about in this article: -* [`Mapping` resource](../../topics/using/intro-mappings/): routes traffic from -the edge of your cluster to a Kubernetes service -* [`Host` resource](../../topics/running/host-crd/): sets the hostname by which -$productName$ will be accessed and secured with TLS certificates -* [Developer Portal](../../tutorials/dev-portal-tutorial/): -publishes an API catalog and OpenAPI documentation - -$productName$ has a comprehensive range of [features](/features/) to -support the requirements of any edge microservice. - -Learn more about [how developers use $productName$](../../topics/using/) to manage -edge policies. - -Learn more about [how site reliability engineers and operators run $productName$](../../topics/running/) -in production environments. - -To learn how $productName$ works, use cases, best practices, and more, check out -the [Quick Start](../getting-started) or read the [$productName$ Story](../../about/why-ambassador). - -For a custom configuration, you can install $productName$ -[manually](../../topics/install/yaml-install). diff --git a/content/en/docs/3.5/versions.yml b/content/en/docs/3.5/versions.yml deleted file mode 100644 index 117bd244..00000000 --- a/content/en/docs/3.5/versions.yml +++ /dev/null @@ -1,35 +0,0 @@ -# branch info -branch: release/v3.5 - -# self -version: 3.5.2 -productName: "Emissary-ingress" -productNamePlural: "Emissary-ingresses" -productNamespace: emissary -productDeploymentName: emissary-ingress -productHelmName: emissary-ingress - -# OSS (self) -ossVersion: 3.5.2 -ossDocsVersion: "3.5" -ossChartVersion: 8.5.2 -OSSproductName: "Emissary-ingress" -OSSproductNamePlural: "Emissary-ingresses" - -# AES (not self) -aesVersion: 3.5.2 -aesDocsVersion: "3.5" -aesChartVersion: 8.5.2 -AESproductName: "Ambassador Edge Stack" -AESproductNamePlural: "Ambassador Edge Stacks" - -# other products -qotmVersion: 1.7 -quoteVersion: 0.5.0 - -# Most recent version from previous major versions -# This is mostly to ensure that the migration matrix stays up-to-date -versionTwoX: 2.5.1 -chartVersionTwoX: 7.6.1 -versionOneX: 1.14.4 -chartVersionOneX: 6.9.5 diff --git a/content/en/docs/3.6/topics/concepts/kubernetes-network-architecture.md b/content/en/docs/3.6/topics/concepts/kubernetes-network-architecture.md index ce2ada65..4f73290f 100644 --- a/content/en/docs/3.6/topics/concepts/kubernetes-network-architecture.md +++ b/content/en/docs/3.6/topics/concepts/kubernetes-network-architecture.md @@ -3,8 +3,6 @@ title: "Kubernetes Network Architecture" description: "This section of the documentation provides an overview of the Kubernetes network architecture" --- -# 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. diff --git a/content/en/docs/3.6/topics/concepts/microservices-api-gateways.md b/content/en/docs/3.6/topics/concepts/microservices-api-gateways.md index 46415c42..923d0491 100644 --- a/content/en/docs/3.6/topics/concepts/microservices-api-gateways.md +++ b/content/en/docs/3.6/topics/concepts/microservices-api-gateways.md @@ -3,8 +3,6 @@ title: "Microservices & API gateways" description: "This section of the documentation provides an overview of microserverse and API Gateways" --- -# Microservices API gateways - A microservices API gateway is an API gateway designed to accelerate the development workflow of independent services teams. A microservices API gateway provides all the functionality for a team to independently publish, monitor, and update a microservice. This focus on accelerating the development workflow is distinct from the purpose of traditional API gateways, which focus on the challenges of managing APIs. Over the past decade, organizations have worked to expose internal systems through well-defined APIs. The challenge of safely exposing hundreds or thousands of APIs to end-users (both internal and external) led to the emergence of API gateways. Over time, API gateways have become centralized, mission critical pieces of infrastructure that control access to these APIs. diff --git a/content/en/docs/3.6/topics/running/_index.md b/content/en/docs/3.6/topics/running/_index.md index 5a140ccb..dc876341 100644 --- a/content/en/docs/3.6/topics/running/_index.md +++ b/content/en/docs/3.6/topics/running/_index.md @@ -3,8 +3,6 @@ title: "Running" description: "This section of the documentation provides instructions on running Emissary in a production environment" --- -# Running Emissary in production - This section of the documentation is designed for operators and site reliability engineers who are managing the deployment of Emissary. Learn more below: * *Global Configuration:* The [Ambassador module](ambassador) is used to set system-wide configuration. diff --git a/content/en/docs/3.6/tutorials/getting-started.md b/content/en/docs/3.6/tutorials/getting-started.md index 6971739e..2ece11c3 100644 --- a/content/en/docs/3.6/tutorials/getting-started.md +++ b/content/en/docs/3.6/tutorials/getting-started.md @@ -3,11 +3,6 @@ title: "Getting Started with Emissary" description: "Learn how to install Emissary with either Helm or kubectl to get started routing traffic from the edge of your Kubernetes cluster to your services..." --- -import Alert from '@material-ui/lab/Alert'; -import GettingStartedEmissary21Tabs from './gs-tabs' - -# Emissary quick start -

Contents

diff --git a/content/en/docs/pre-release/about/aes-emissary-eol.md b/content/en/docs/pre-release/about/aes-emissary-eol.md deleted file mode 100644 index 6afc3142..00000000 --- a/content/en/docs/pre-release/about/aes-emissary-eol.md +++ /dev/null @@ -1,56 +0,0 @@ -# $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/content/en/docs/pre-release/about/alternatives.md b/content/en/docs/pre-release/about/alternatives.md deleted file mode 100644 index bafec087..00000000 --- a/content/en/docs/pre-release/about/alternatives.md +++ /dev/null @@ -1,19 +0,0 @@ -# $productName$ vs. other software - -Alternatives to $productName$ fall into three basic categories: - -* Hosted API gateways, such as the [Amazon API gateway](https://aws.amazon.com/api-gateway/). -* Traditional API gateways, such as [Kong](https://konghq.org/). -* L7 proxies, such as [Traefik](https://traefik.io/), [NGINX](http://nginx.org/), [HAProxy](http://www.haproxy.org/), or [Envoy](https://www.envoyproxy.io), or Ingress controllers built on these proxies. - -Both hosted API gateways and traditional API gateways are: - -* Not self-service. The management interfaces on traditional API gateways are not designed for developer self-service, and provide limited safety and usability for developers. -* Not Kubernetes-native. They're typically configured using REST APIs, making it challenging to adopt cloud-native patterns such as GitOps and declarative configuration. -* [Designed for API management, rather than designed for microservices](../../topics/concepts/microservices-api-gateways). - -A Layer 7 proxy can be used as an API gateway, but typically requires additional bespoke development to support microservices use cases. In fact, many API gateways package the additional features needed for an API gateway on top of an L7 proxy. $productName$ uses Envoy, while Kong uses NGINX. If you're interested in deploying Envoy directly, we've written an [introductory tutorial](https://www.datawire.io/guide/traffic/getting-started-lyft-envoy-microservices-resilience/). - -## Istio - -[Istio](https://istio.io) is an open-source service mesh, built on Envoy. A service mesh is designed to manage East/West traffic (traffic between servers and your data center), while an API gateway manages North/South traffic (in and out of your data center). Documentation on how to deploy $productName$ with Istio is [here](../../howtos/istio). In general, we've found that North/South traffic is quite different from East/West traffic (i.e., you don't control the client in the North/South use case). diff --git a/content/en/docs/pre-release/about/changes-2.x.md b/content/en/docs/pre-release/about/changes-2.x.md deleted file mode 100644 index 4c412486..00000000 --- a/content/en/docs/pre-release/about/changes-2.x.md +++ /dev/null @@ -1,238 +0,0 @@ -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. - - - $productName$ 2.X supports only API versions getambassador.io/v2 - and getambassador.io/v3alpha1. If you are using any resources with - older API versions, you will need to upgrade them. - - -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 [structural CRDs](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. - - - Learn more about Listener.
- Learn more about Host. - - -### 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. - - - Learn more about Host. - - -### `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. - - - Learn more about Host.
- Learn more about Mapping. - - -### 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. - - - Learn more about Host. - - -### `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). - - - Learn more about Host.
- Learn more about TLSContext. - - -### `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). - - - Learn more about Mapping. - - -### `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. - - - Learn more about Mapping. - - -## 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). In $productName$ -$version$, you may switch back to Envoy V2 by setting the `AMBASSADOR_ENVOY_API_VERSION` -environment variable to "V2"; in $productName$ 2.2.0, support for the Envoy V2 API (and -the `AMBASSADOR_ENVOY_API_VERSION` environment variable) will be removed. - -### 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. - - - Learn more about Listener. - - -### `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/content/en/docs/pre-release/about/changes-3.y.md b/content/en/docs/pre-release/about/changes-3.y.md deleted file mode 100644 index 91105d28..00000000 --- a/content/en/docs/pre-release/about/changes-3.y.md +++ /dev/null @@ -1,52 +0,0 @@ -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 AuthServices 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, -``` - - - Learn more about Envoy Proxy changes. - - -## 2. Envoy V2 Protocol Support Removed - -With the upgrade to Envoy **1.22**, the V2 Envoy Transport Protocol is no longer supported. -$productName$ 3.X **only** supports [V3 Envoy API](https://www.envoyproxy.io/docs/envoy/latest/api-v3/api). - - -The environment variable AMBASSADOR_ENVOY_API_VERSION has been removed and will no longer have the affect -of changing the transport protocol. - - - -The setting of 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. - diff --git a/content/en/docs/pre-release/about/faq.md b/content/en/docs/pre-release/about/faq.md deleted file mode 100644 index 513c75c5..00000000 --- a/content/en/docs/pre-release/about/faq.md +++ /dev/null @@ -1,79 +0,0 @@ -# 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. -* 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! The core functionality of the $AESproductName$ is free and has no limits whatsoever. If you wish to use one of our additional, proprietary features such as Single Sign-On, you can get a free community license for up to 5 requests per second by registering your connected $AESproductName$ installation in [Ambassador Cloud](https://app.getambassador.io/cloud/). Please contact [sales](/contact-us/) if you need more than 5 RPS. - -For more details on core unlimited features and premium features, see the [editions page](/editions). - -### 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? - -[//]: # (+FIX+ Check for OSS) - -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$? - -[//]: # (+FIX+ Check for OSS) - -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 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/content/en/docs/pre-release/about/features-and-benefits.md b/content/en/docs/pre-release/about/features-and-benefits.md deleted file mode 100644 index a25d7752..00000000 --- a/content/en/docs/pre-release/about/features-and-benefits.md +++ /dev/null @@ -1,43 +0,0 @@ -# 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 - -[//]: # (+FIX+ Forge is no more) - -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 - -[//]: # (+FIX+ we've come to realize that it's better to scale vertically) - -$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 using a custom authentication service. When configured, the $productName$ will check with your external authentication service prior to routing an incoming request. For more information, see the [authentication guide](../../topics/running/services/auth-service). - -## 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/content/en/docs/pre-release/about/known-issues.md b/content/en/docs/pre-release/about/known-issues.md deleted file mode 100644 index 6b89c65a..00000000 --- a/content/en/docs/pre-release/about/known-issues.md +++ /dev/null @@ -1,9 +0,0 @@ -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. diff --git a/content/en/docs/pre-release/about/support.md b/content/en/docs/pre-release/about/support.md deleted file mode 100644 index 11927f95..00000000 --- a/content/en/docs/pre-release/about/support.md +++ /dev/null @@ -1,27 +0,0 @@ -# Need help? - -If you need help deploying $productName$ at your organization, there are several different options available to you. - -## Support tiers - -### $productName$ community support - -When running $OSSproductName$, or $AESproductName$ with free community licenses, [join our Slack channel](http://a8r.io/slack) to talk with other users in the community and get your questions answered. - -If you can’t find an answer there, [contact us](/contact-us) to learn more about the support options available with $AESproductName$ Enterprise. - -### $AESproductName$ Enterprise - -With $AESproductName$ Enterprise, you have access to deployment and production support. To learn more, [contact sales](/contact-us). - -**Deployment and Update Support**: $AESproductName$ can accelerate your migration to Kubernetes, or your upgrade between versions of $AESproductName$. Deployment support helps you with the $AESproductName$ and Kubernetes migration, before you move to production. - -**Production Support**: We offer two types of production support contracts for users deploying the $AESproductName$ in production. We offer both business hour (8am - 5pm EST, M-F) and 24x7 Sev 1 support for the $AESproductName$. 24x7 Sev 1 support includes custom hotfix support for production outages if necessary. - -## File a Github Issue - -If you see a bug you want to fix, see room for documentation improvements, or have something else you want to change, you can [file an issue on github](https://github.com/datawire/ambassador/issues/new). - -## Pricing - -[Contact us](/contact-us) to learn how we can help, and for detailed pricing information. diff --git a/content/en/docs/pre-release/about/why-ambassador.md b/content/en/docs/pre-release/about/why-ambassador.md deleted file mode 100644 index 0d343983..00000000 --- a/content/en/docs/pre-release/about/why-ambassador.md +++ /dev/null @@ -1,54 +0,0 @@ -# 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 an open-source, Kubernetes-native [microservices API gateway](../../topics/concepts/microservices-api-gateways) built on 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/content/en/docs/pre-release/community.md b/content/en/docs/pre-release/community.md deleted file mode 100644 index 2b578891..00000000 --- a/content/en/docs/pre-release/community.md +++ /dev/null @@ -1,12 +0,0 @@ -# Community - -## Contributor's guide -Please review our [contributor's guide](https://github.com/emissary-ingress/emissary/blob/master/DevDocumentation/DEVELOPING.md) -on GitHub to learn how you can help make Emissary-ingress better. - -## Changelog -Our [changelog](https://github.com/emissary-ingress/emissary/blob/master/CHANGELOG.md) -describes new features, bug fixes, and updates to each version of Emissary-ingress. - -## Meetings -Check out our community [meeting schedule](https://github.com/emissary-ingress/emissary/blob/master/Community/MEETING_SCHEDULE.md) for opportunities to interact with Emissary-ingress developers. diff --git a/content/en/docs/pre-release/doc-links.yml b/content/en/docs/pre-release/doc-links.yml deleted file mode 100644 index 58b81ad9..00000000 --- a/content/en/docs/pre-release/doc-links.yml +++ /dev/null @@ -1,229 +0,0 @@ -- 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: $productName$ 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: 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/basic-auth - - title: Rate limiting - items: - - title: Rate limiting service - link: /topics/running/services/rate-limit-service/ - - title: Basic rate limiting - link: /topics/using/rate-limits/ - - 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: Distrbuted 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: 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: 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: Diagnostics - link: /topics/running/diagnostics -- 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: Licenses - link: licenses diff --git a/content/en/docs/pre-release/features-icons/basic-authentication.svg b/content/en/docs/pre-release/features-icons/basic-authentication.svg deleted file mode 100644 index 2bd19edf..00000000 --- a/content/en/docs/pre-release/features-icons/basic-authentication.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_897228_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/pre-release/features-icons/canary-release.svg b/content/en/docs/pre-release/features-icons/canary-release.svg deleted file mode 100644 index f8de57d9..00000000 --- a/content/en/docs/pre-release/features-icons/canary-release.svg +++ /dev/null @@ -1,27 +0,0 @@ - - - - Group 25 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - diff --git a/content/en/docs/pre-release/features-icons/cors.svg b/content/en/docs/pre-release/features-icons/cors.svg deleted file mode 100644 index e559d924..00000000 --- a/content/en/docs/pre-release/features-icons/cors.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_111967_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/pre-release/features-icons/datadog.png b/content/en/docs/pre-release/features-icons/datadog.png deleted file mode 100644 index eea05f8c..00000000 Binary files a/content/en/docs/pre-release/features-icons/datadog.png and /dev/null differ diff --git a/content/en/docs/pre-release/features-icons/datadog.svg b/content/en/docs/pre-release/features-icons/datadog.svg deleted file mode 100644 index e46e8118..00000000 --- a/content/en/docs/pre-release/features-icons/datadog.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Screen Shot 2018-04-05 at 8.22.25 AM - Created with Sketch. - - - - - - - diff --git a/content/en/docs/pre-release/features-icons/diagnostics.svg b/content/en/docs/pre-release/features-icons/diagnostics.svg deleted file mode 100644 index 940e1bc2..00000000 --- a/content/en/docs/pre-release/features-icons/diagnostics.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_196445_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/pre-release/features-icons/distributed-tracing.png b/content/en/docs/pre-release/features-icons/distributed-tracing.png deleted file mode 100644 index 6b69e28c..00000000 Binary files a/content/en/docs/pre-release/features-icons/distributed-tracing.png and /dev/null differ diff --git a/content/en/docs/pre-release/features-icons/grpc.png b/content/en/docs/pre-release/features-icons/grpc.png deleted file mode 100644 index b2f5a0d9..00000000 Binary files a/content/en/docs/pre-release/features-icons/grpc.png and /dev/null differ diff --git a/content/en/docs/pre-release/features-icons/prometheus.svg b/content/en/docs/pre-release/features-icons/prometheus.svg deleted file mode 100644 index d5252a66..00000000 --- a/content/en/docs/pre-release/features-icons/prometheus.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - prometheus_logo_grey - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/pre-release/features-icons/rate-limiting.svg b/content/en/docs/pre-release/features-icons/rate-limiting.svg deleted file mode 100644 index f1b6eacb..00000000 --- a/content/en/docs/pre-release/features-icons/rate-limiting.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - Group 10 - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/pre-release/features-icons/regex-routing.svg b/content/en/docs/pre-release/features-icons/regex-routing.svg deleted file mode 100644 index 113b53b5..00000000 --- a/content/en/docs/pre-release/features-icons/regex-routing.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_699774_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/pre-release/features-icons/request-transformers.svg b/content/en/docs/pre-release/features-icons/request-transformers.svg deleted file mode 100644 index 0b13e2dc..00000000 --- a/content/en/docs/pre-release/features-icons/request-transformers.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_96239_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/pre-release/features-icons/shadowing.svg b/content/en/docs/pre-release/features-icons/shadowing.svg deleted file mode 100644 index 9e85eee1..00000000 --- a/content/en/docs/pre-release/features-icons/shadowing.svg +++ /dev/null @@ -1,15 +0,0 @@ - - - - shadow - Created with Sketch. - - - - - - - - - - diff --git a/content/en/docs/pre-release/features-icons/statsd.png b/content/en/docs/pre-release/features-icons/statsd.png deleted file mode 100644 index 28374438..00000000 Binary files a/content/en/docs/pre-release/features-icons/statsd.png and /dev/null differ diff --git a/content/en/docs/pre-release/features-icons/statsd.svg b/content/en/docs/pre-release/features-icons/statsd.svg deleted file mode 100644 index cabc90db..00000000 --- a/content/en/docs/pre-release/features-icons/statsd.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - 88eb31f74479e422e4e9abfc6c2b00ee - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/pre-release/features-icons/third-party-auth.svg b/content/en/docs/pre-release/features-icons/third-party-auth.svg deleted file mode 100644 index 5359a24a..00000000 --- a/content/en/docs/pre-release/features-icons/third-party-auth.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_511233_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/pre-release/features-icons/timeouts.svg b/content/en/docs/pre-release/features-icons/timeouts.svg deleted file mode 100644 index 47f63056..00000000 --- a/content/en/docs/pre-release/features-icons/timeouts.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_587034_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/pre-release/features-icons/tls-termination.svg b/content/en/docs/pre-release/features-icons/tls-termination.svg deleted file mode 100644 index 6a631a96..00000000 --- a/content/en/docs/pre-release/features-icons/tls-termination.svg +++ /dev/null @@ -1,17 +0,0 @@ - - - - noun_63544_cc - Created with Sketch. - - - - - - - - - - - - diff --git a/content/en/docs/pre-release/features-icons/url-rewrite.svg b/content/en/docs/pre-release/features-icons/url-rewrite.svg deleted file mode 100644 index 023e2e05..00000000 --- a/content/en/docs/pre-release/features-icons/url-rewrite.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1295942_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/pre-release/features-icons/websockets.svg b/content/en/docs/pre-release/features-icons/websockets.svg deleted file mode 100644 index af17b9c0..00000000 --- a/content/en/docs/pre-release/features-icons/websockets.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - noun_50814_cc - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/pre-release/howtos/active-health-checking.md b/content/en/docs/pre-release/howtos/active-health-checking.md deleted file mode 100644 index fb5decdd..00000000 --- a/content/en/docs/pre-release/howtos/active-health-checking.md +++ /dev/null @@ -1,78 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Active Health Checking - -$productName$ provides support for active health checking of upstreams via the `Mapping` resource. Active health checking will configure Envoy to make requests to the upstream at a configurable interval. If the upstream does not respond with an expected status code then the upstream will be marked as unhealthy and Envoy will no longer route requests to that upstream until they respond successfully to the health check. - -This feature can only be used with the [endpoint resolver](../../topics/running/resolvers#the-kubernetes-endpoint-resolver). This is necessary because the endpoint resolver allows Envoy to be aware of each individual pod in a deployment as opposed to the [kubernetes service resolver](../../topics/running/resolvers#the-kubernetes-service-resolver) where Envoy is only aware of the upstream as a single endpoint. When envoy is aware of the multiple pods in a deployment then it will allow the active health checks to mark an individual pod as unhealthy while the remaining pods are able to serve requests. - - -Active health checking configuration wil only function with the endpoint resolver. If configuration for active health checking is provided on a Mapping that does not use the endpoint resolver then the health checking configuration will be ignored. - - -## Active Health Checking Configuration - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: "example-mapping" - namespace: "example-namespace" -spec: - hostname: "*" - prefix: /example/ - service: quote - health_checks: list[object] # optional - - unhealthy_threshold: int # optional (default: 2) - healthy_threshold: int # optional (default: 1) - interval: duration # optional (default: 5s) - timeout: duration # optional (default: 3s) - health_check: object # required - http: - path: string # required - hostname: string # optional - remove_request_headers: list[string] # optional - add_request_headers: list[object] # optional - - example-header-1: - append: bool # optional (default: true) - value: string # required - expected_statuses: list[object] # optional - - max: int (100-599) # required (only when using expected_statuses) - min: int (100-599) # required (only when using expected_statuses) - - - health_check: object # required - grpc: - authority: string # optional - upstream_name: string # required -... -``` - -### `health_checks` configuration - -`health_checks` Configures a list of health checks to be run for the `Mapping` and provides several config options for how the health check requests should be run. - -- `unhealthy_threshold`: The number of unexpected responses for an upstream pod to be marked as unhealthy. Regardless of the configuration of `unhealthy_threshold`, a single `503` response will mark the upstream as unhealthy until it passes the required number of health checks. This field is optional and defaults to `2`. -- `healthy_threshold`: The number of expected responses for an unhealthy upstream pod to be marked as healthy and resume handling traffic. This field is optional and defaults to `1`. -- `interval`: Specifies the interval for how frequently the health check request should be made. It is divided amongst the pods in a deployment. For example, an `interval` of `1s` on a deployment of 5 pods would result in each pod receiving a health check request about every 5 seconds. This field is optional and defaults to `5s` when not configured. -- `timeout`: Configures the timeout for the health check requests to an upstream. If a health check request fails the timeout it will be considred a failed check and count towards the `unhealthy_threshold`. This field is optional and defaults to `3s`. -- `health_check`: This field is required and provides the configuration for how the health check requests should be made. Either `grpc` or `http` may be configured for this field depending on whether an HTTP or gRPC health check is desired. - -### HTTP `health_check` Configuration - -`health_check.http` configures HTTP health checks to the upstream. - -- `path`: This field is required and configures the path on the upstream service that the health checks request should be made to. -- `hostname`: Configures the value of the host header in the health check request. This field is optional and defaults to using the name of the Envoy cluster this health check is associated with. -- `expected_statuses`: Configures a range of response statuses from Min to Max (both inclusive). If the upstream returns any status in this range then it will be considered a passed health check. Thies field is optional and by default only `5xx` responses count as a failed health check and contribute towards the `unhealthy_threshold`. - - `max`: End of the statuses to include. Must be between 100 and 599 (inclusive). - - `min`: Start of the statuses to include. Must be between 100 and 599 (inclusive). -- `remove_request_headers`: Configures a list of HTTP headers that should be removed from each health check request sent to the upstream. -- `request_headers_to_add`: Configures a list of HTTP headers that should be added to each health check request sent to the upstream. - -### gRPC `health_check` Configuration - -`health_check.grpc` configures gRPC health checks to the upstream. Only two fields are configurable for gRPC health checks. - -- `authority`: Configures the value of the :authority header in the gRPC health check request. This field is optional and if left empty the upstream name will be used. -- `upstream_name`: This field is required and configures the UpstreamName name parameter which will be sent to gRPC service in the health check message. diff --git a/content/en/docs/pre-release/howtos/basic-auth.md b/content/en/docs/pre-release/howtos/basic-auth.md deleted file mode 100644 index 70ce27ce..00000000 --- a/content/en/docs/pre-release/howtos/basic-auth.md +++ /dev/null @@ -1,191 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Basic authentication (for $productName$) - -[//]: # (+FIX+ link to "authentication and authorization" concept) - - - This guide applies to $OSSproductName$, use of this guide with $AESproductName$ is not supported. $AESproductName$ does authentication using the Filter resource instead of the AuthService resource as described below. - - -$productName$ can authenticate incoming requests before routing them to a backing -service. In this tutorial, we'll configure $productName$ to use an external third -party authentication service. We're assuming also that you are running the -quote application in your cluster as described in the -[$productName$ tutorial](../../tutorials/quickstart-demo/). - -## Before you get started - -This tutorial assumes you have already followed the $productName$ [Installation](../../topics/install/) guide. If you haven't done that already, you should do so now. - -Once complete, you'll have a Kubernetes cluster running $productName$. Let's walk through adding authentication to this setup. - -## 1. Deploy the authentication service - -$productName$ delegates the actual authentication logic to a third party authentication service. We've written a [simple authentication service](https://github.com/datawire/ambassador-auth-service) that: - -- listens for requests on port 3000; -- expects all URLs to begin with `/extauth/`; -- performs HTTP Basic Auth for all URLs starting with `/backend/get-quote/` (other URLs are always permitted); -- accepts only user `username`, password `password`; and -- makes sure that the `x-qotm-session` header is present, generating a new one if needed. - -$productName$ routes _all_ requests through the authentication service: it relies on the auth service to distinguish between requests that need authentication and those that do not. If $productName$ cannot contact the auth service, it will return a 503 for the request; as such, **it is very important to have the auth service running before configuring $productName$ to use it.** - -Here's the YAML we'll start with: - -```yaml ---- -apiVersion: v1 -kind: Service -metadata: - name: example-auth -spec: - type: ClusterIP - selector: - app: example-auth - ports: - - port: 3000 - name: http-example-auth - targetPort: http-api ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: example-auth -spec: - replicas: 1 - strategy: - type: RollingUpdate - selector: - matchLabels: - app: example-auth - template: - metadata: - labels: - app: example-auth - spec: - containers: - - name: example-auth - image: docker.io/datawire/ambassador-auth-service:2.0.0 - imagePullPolicy: Always - ports: - - name: http-api - containerPort: 3000 - resources: - limits: - cpu: "0.1" - memory: 100Mi -``` - -Note that the cluster does not yet contain any $productName$ AuthService definition. This is intentional: we want the service running before we tell $productName$ about it. - -The YAML above is published at getambassador.io, so if you like, you can just do - -``` -kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/demo/demo-auth.yaml -``` - -to spin everything up. (Of course, you can also use a local file, if you prefer.) - -Wait for the pod to be running before continuing. The output of `kubectl get pods` should look something like - -``` -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -example-auth-6c5855b98d-24clp 1/1 Running 0 4m -``` -Note that the `READY` field says `1/1` which means the pod is up and running. - -## 2. Configure $productName$ authentication - -Once the auth service is running, we need to tell $productName$ about it. The easiest way to do that is point it to the `example-auth` service with the following: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: AuthService -metadata: - name: authentication -spec: - auth_service: "example-auth:3000" - path_prefix: "/extauth" - allowed_request_headers: - - "x-qotm-session" - allowed_authorization_headers: - - "x-qotm-session" -``` - -This configuration tells $productName$ about the auth service, notably that it needs the `/extauth` prefix, and that it's OK for it to pass back the `x-qotm-session` header. Note that `path_prefix` and `allowed_*_headers` are optional. - -If the auth service uses a framework like [Gorilla Toolkit](http://www.gorillatoolkit.org) which enforces strict slashes as HTTP path separators, it is possible to end up with an infinite redirect where the auth service's framework redirects any request with non-conformant slashing. This would arise if the above example had `path_prefix: "/extauth/"`, the auth service would see a request for `/extauth//backend/get-quote/` which would then be redirected to `/extauth/backend/get-quote/` rather than actually be handled by the authentication handler. For this reason, remember that the full path of the incoming request including the leading slash, will be appended to `path_prefix` regardless of non-conformant slashing. - -You can apply this file from getambassador.io with - -``` -kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/demo/demo-auth-enable.yaml -``` - -or, again, apply it from a local file if you prefer. - -Note that the cluster does not yet contain any $productName$ AuthService definition. - -## 3. Test authentication - -If we `curl` to a protected URL: - -``` -$ curl -Lv $AMBASSADORURL/backend/get-quote/ -``` - -We get a 401 since we haven't authenticated. - -``` -* TCP_NODELAY set -* Connected to 54.165.128.189 (54.165.128.189) port 32281 (#0) -> GET /backend/get-quote/ HTTP/1.1 -> Host: 54.165.128.189:32281 -> User-Agent: curl/7.63.0 -> Accept: */* -> -< HTTP/1.1 401 Unauthorized -< www-authenticate: Basic realm="Ambassador Realm" -< content-length: 0 -< date: Thu, 23 May 2019 15:24:55 GMT -< server: envoy -< -* Connection #0 to host 54.165.128.189 left intact -``` - -If we authenticate to the service, we will get a quote successfully: - -``` -$ curl -Lv -u username:password $AMBASSADORURL/backend/get-quote/ - -* TCP_NODELAY set -* Connected to 54.165.128.189 (54.165.128.189) port 32281 (#0) -* Server auth using Basic with user 'username' -> GET /backend/get-quote/ HTTP/1.1 -> Host: 54.165.128.189:32281 -> Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= -> User-Agent: curl/7.63.0 -> Accept: */* -> -< HTTP/1.1 200 OK -< content-type: application/json -< date: Thu, 23 May 2019 15:25:06 GMT -< content-length: 172 -< x-envoy-upstream-service-time: 0 -< server: envoy -< -{ - "server": "humble-blueberry-o2v493st", - "quote": "Nihilism gambles with lives, happiness, and even destiny itself!", - "time": "2019-05-23T15:25:06.544417902Z" -* Connection #0 to host 54.165.128.189 left intact -} -``` - -## More - -For more details about configuring authentication, see the [`External` filter](/docs/edge-stack/latest/topics/using/filters/) documentation. diff --git a/content/en/docs/pre-release/howtos/cert-manager.md b/content/en/docs/pre-release/howtos/cert-manager.md deleted file mode 100644 index d742decd..00000000 --- a/content/en/docs/pre-release/howtos/cert-manager.md +++ /dev/null @@ -1,230 +0,0 @@ -# Using cert-manager - -[//]: # (+FIX+ link to "TLS and certificates" concept) - -$AESproductName$ has simple and easy built-in support for automatically [using ACME] with the -`http-01` challenge to create and renew TLS certificates. However, this support is not available -in $OSSproductName$, and it is limited to the ACME `http-01` challenge type. If you're running -$OSSproductName$, or if you require more flexible certificate management (such as using ACME's -`dns-01` challenge, or using a non-ACME certificate source), external certificate management -tools are also supported. - -[using ACME]: ../../topics/running/host-crd - -One such tool is Jetstack's [cert-manager](https://github.com/jetstack/cert-manager), which is a general-purpose tool -for managing certificates in Kubernetes. Cert-manager will automatically create and renew TLS certificates and store -them as Kubernetes secrets for easy use in a cluster. $productName$ will automatically watch for secret -changes and reload certificates upon renewal. - -> **Note:** This document assumes cert-manager v0.15 or greater. This document has been updated to use CRD standards -> specified in v0.15. [Legacy CRD support](https://cert-manager.io/docs/installation/upgrading/upgrading-0.14-0.15/) -> was removed in cert-manager v0.15, see their [upgrading](https://cert-manager.io/docs/installation/upgrading/) -> document for more info. - -## Install cert-manager - -There are many different ways to [install cert-manager](https://cert-manager.io/docs/installation/). For simplicity, we will use Helm. - -1. Create the cert-manager CRDs. - ``` - kubectl apply -f https://github.com/jetstack/cert-manager/releases/latest/download/cert-manager.crds.yaml - ``` - -2. Add the `jetstack` Helm repository. - ``` - helm repo add jetstack https://charts.jetstack.io && helm repo update - ``` - -3. Install cert-manager. - - ``` - kubectl create ns cert-manager - helm install cert-manager --namespace cert-manager jetstack/cert-manager - ``` - -## Issuing certificates - -cert-manager issues certificates from a CA such as [Let's Encrypt](https://letsencrypt.org/). It does this using the ACME protocol which supports various challenge mechanisms for verifying ownership of the domain. - -### Issuer - -An `Issuer` or `ClusterIssuer` identifies which Certificate Authority cert-manager will use to issue a certificate. `Issuer` is a namespaced resource allowing you to use different CAs in each namespace, a `ClusterIssuer` is used to issue certificates in any namespace. Configuration depends on which ACME [challenge](#challenge) you are using. - -### Certificate - -A [Certificate](https://cert-manager.io/docs/concepts/certificate/) is a namespaced resource that references an `Issuer` or `ClusterIssuer` for issuing certificates. `Certificate`s define the DNS name(s) a key and certificate should be issued for, as well as the secret to store those files (e.g. `ambassador-certs`). Configuration depends on which ACME [challenge](#challenge) you are using. - -By duplicating issuers, certificates, and secrets one can support multiple domains with [SNI](../../topics/running/tls/sni). - -## Challenge - -cert-manager supports two kinds of ACME challenges that verify domain ownership in different ways: HTTP-01 and DNS-01. - -### DNS-01 challenge - -The DNS-01 challenge verifies domain ownership by proving you have control over its DNS records. Issuer configuration will depend on your [DNS provider](https://cert-manager.io/docs/configuration/acme/dns01/#supported-dns01-providers). This example uses [AWS Route53](https://cert-manager.io/docs/configuration/acme/dns01/route53/). - -1. Create the IAM policy specified in the cert-manager [AWS Route53](https://cert-manager.io/docs/configuration/acme/dns01/route53/) documentation. - -2. Note the `accessKeyID` and create a `secret` named `prod-route53-credentials-secret` in the cert-manager namespace that has a key value: `secret-access-key` from your AWS IaM credentials. - -3. Create and apply a `ClusterIssuer`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: ClusterIssuer - metadata: - name: letsencrypt-prod - spec: - acme: - email: email@example.com - server: https://acme-v02.api.letsencrypt.org/directory - privateKeySecretRef: - name: letsencrypt-prod - solvers: - - selector: - dnsZones: - - "myzone.route53.com" - dns01: - route53: - region: us-east-1 - accessKeyID: {accessKeyID} - hostedZoneID: {Hosted Zone ID} # optional, allows you to reduce the scope of permissions in Amazon IAM - secretAccessKeySecretRef: - name: prod-route53-credentials-secret - key: secret-access-key - ``` - -4. Create and apply a `Certificate`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: Certificate - metadata: - name: myzone.route53.com - # cert-manager will put the resulting Secret in the same Kubernetes - # namespace as the Certificate. You should create the certificate in - # whichever namespace you want to configure a Host. - spec: - secretName: ambassador-certs - issuerRef: - name: letsencrypt-prod - kind: ClusterIssuer - commonName: myzone.route53.com - dnsNames: - - myzone.route53.com - ``` - -5. Verify the secret is created. - - ``` - $ kubectl get secrets -n ambassador - NAME TYPE DATA AGE - ambassador-certs kubernetes.io/tls 2 1h - ``` - -### HTTP-01 challenge - -The HTTP-01 challenge verifies ownership of the domain by sending a request for a specific file on that domain. cert-manager accomplishes this by sending a request to a temporary pod with the prefix `/.well-known/acme-challenge/`. To perform this challenge: - -1. Create and apply a `ClusterIssuer`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: ClusterIssuer - metadata: - name: letsencrypt-prod - spec: - acme: - email: email@example.com - server: https://acme-v02.api.letsencrypt.org/directory - privateKeySecretRef: - name: letsencrypt-prod - solvers: - - http01: - ingress: - class: nginx - selector: {} - ``` - -2. Create and apply a `Certificate`. - - ```yaml - --- - apiVersion: cert-manager.io/v1alpha2 - kind: Certificate - metadata: - name: ambassador-certs - # cert-manager will put the resulting Secret in the same Kubernetes - # namespace as the Certificate. You should create the certificate in - # whichever namespace you want to configure a Host. - namespace: ambassador - spec: - secretName: ambassador-certs - issuerRef: - name: letsencrypt-prod - kind: ClusterIssuer - dnsNames: - - example.com - ``` - -3. Apply both the `ClusterIssuer` and `Certificate` - - After applying both of these YAML manifests, you will notice that cert-manager has spun up a temporary pod named `cm-acme-http-solver-xxxx` but no certificate has been issued. Check the cert-manager logs and you will see a log message that looks like this: - - ``` - $ kubectl logs cert-manager-756d6d885d-v7gmg - ... - Preparing certificate default/ambassador-certs with issuer - Calling GetOrder - Calling GetAuthorization - Calling HTTP01ChallengeResponse - Cleaning up old/expired challenges for Certificate default/ambassador-certs - Calling GetChallenge - wrong status code '404' - Looking up Ingresses for selector certmanager.k8s.io/acme-http-domain=161156668,certmanager.k8s.io/acme-http-token=1100680922 - Error preparing issuer for certificate default/ambassador-certs: http-01 self check failed for domain "example.com - ``` - -4. Create a Mapping for the `/.well-known/acme-challenge/` route. - - cert-manager uses an `Ingress` to issue the challenge to `/.well-known/acme-challenge/` that is incompatible with Ambassador. We will need to create a `Mapping` so the cert-manager can reach the temporary pod. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Mapping - metadata: - name: acme-challenge-mapping - spec: - hostname: "*" - prefix: /.well-known/acme-challenge/ - rewrite: "" - service: acme-challenge-service - - --- - apiVersion: v1 - kind: Service - metadata: - name: acme-challenge-service - spec: - ports: - - port: 80 - targetPort: 8089 - selector: - acme.cert-manager.io/http01-solver: "true" - ``` - - Apply the YAML and wait a couple of minutes. cert-manager will retry the challenge and issue the certificate. - -5. Verify the secret is created: - - ``` - $ kubectl get secrets - NAME TYPE DATA AGE - ambassador-certs kubernetes.io/tls 2 1h - ambassador-token-846d5 kubernetes.io/service-account-token 3 2h - ``` diff --git a/content/en/docs/pre-release/howtos/client-cert-validation.md b/content/en/docs/pre-release/howtos/client-cert-validation.md deleted file mode 100644 index 10fe639d..00000000 --- a/content/en/docs/pre-release/howtos/client-cert-validation.md +++ /dev/null @@ -1,110 +0,0 @@ -# Client certificate validation - -[//]: # (+FIX+ link to "TLS and client certs" concept) - -Sometimes, for additional security or authentication purposes, you will want -the server to validate who the client is before establishing an encrypted -connection. - -To support this, $productName$ can be configured to use a provided CA certificate -to validate certificates sent from your clients. This allows for client-side -mTLS where both $productName$ and the client provide and validate each other's -certificates. - -## Prerequisites - -- [openssl](https://www.openssl.org/source/) For creating client certificates -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [$productName$](../../tutorials/getting-started) -- [cURL](https://curl.haxx.se/download.html) - - -## Configuration - -1. Create a certificate and key. - - This can be done with a single command with `openssl`: - - ``` - openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 - ``` - - Enter a passcode for PEM files and fill in the certificate information. - Since this certificate will only be shared between a client and $productName$, - the Common Name must be set to something. Everything else can be left blank. - - **Note:** If using MacOS, - [you must](https://curl.haxx.se/mail/archive-2014-10/0053.html) - add the certificate and key as a PKCS encoded file to your Keychain. To do - this: - - 1. Encode `cert.pem` and `key.pem` created above in PKCS format - - ``` - openssl pkcs12 -inkey key.pem -in cert.pem -export -out certificate.p12 - ``` - - 2. Open "Keychain Access" on your system and select "File"->"Import Items..." - - 3. Navigate to your working directory and select the `certificate.p12` file - we just created above. - -2. Create a secret to hold the client CA certificate. - - ``` - kubectl create secret generic client-cacert --from-file=tls.crt=cert.pem - ``` - -3. Configure $productName$ to use this certificate for client certificate validation. - - First create a `Host` to manage your domain: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Host - metadata: - name: example-host - spec: - hostname: host.example.com - acmeProvider: - email: julian@example.com - ``` - - Then create a `TLSContext` to configure advanced TLS options like client - certificate validation: - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: TLSContext - metadata: - name: example-host-context - spec: - hosts: - - host.example.com - secret: host.example.com - ca_secret: client-cacert - cert_required: false # Optional: Configures $productName$ to reject the request if the client does not provide a certificate. Default: false - ``` - - **Note**: Client certificate validation requires $productName$ be configured to terminate TLS - - $productName$ is now be configured to validate certificates that the client provides. - -4. Test that $productName$ is validating the client certificates with `curl` - - **Linux**: - ``` - curl -v --cert cert.pem --key key.pem https://host.example.com/ - ``` - - **MacOS**: - ``` - curl -v --cert certificate.p12:[password] https://host.example.com/ - ``` - - Looking through the verbose output, you can see we are sending a client - certificate and $productName$ is validating it. - - If you need further proof, simply create a new set of certificates and - try sending the curl with those. You will see $productName$ deny the request. diff --git a/content/en/docs/pre-release/howtos/configure-communications.md b/content/en/docs/pre-release/howtos/configure-communications.md deleted file mode 100644 index 1ac09d2c..00000000 --- a/content/en/docs/pre-release/howtos/configure-communications.md +++ /dev/null @@ -1,763 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -Configuring $productName$ Communications -======================================== - -For $productName$ to do its job of managing network communications for your services, it first needs to know how its own communications should be set up. This is handled by a combination of resources: the `Listener`, the `Host`, and the `TLSContext`. - -- `Listener`: defines where, and how, $productName$ should listen for requests from the network. -- `Host`: defines which hostnames $productName$ should care about, and how to handle different kinds of requests for those hosts. `Host`s can be associated with one or more `Listener`s. -- `TLSContext`: defines whether, and how, $productName$ will manage TLS certificates and options. `TLSContext`s can be associated with one or more `Host`s. - -Once the basic communications setup is in place, $productName$ `Mapping`s and `TCPMapping`s can be associated with `Host`s to actually do routing. - - - Remember that Listener and Host resources are  - required for a functioning $productName$ installation that can route traffic!
- Learn more about Listener.
- Learn more about Host. - - - - Remember than $productName$ does not make sure that a wildcard Host exists! If the - wildcard behavior is needed, a Host with a hostname of "*" - must be defined by the user. - - - - Several different resources work together to configure communications. A working knowledge of all of them - can be very useful:
- Learn more about Listener.
- Learn more about Host.
- Learn more about Mapping.
- Learn more about TCPMapping.
- Learn more about TLSContext. - - -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]: ../../topics/running/tls -[certificates]: ../../topics/running/tls#certificates-and-secrets -[check the logs]: ../../topics/running/debugging#review-logs - -Examples / Cookbook -------------------- - -### Basic HTTP and HTTPS - -A useful configuration is to support either HTTP or HTTPS, in this case on either port 8080 or port 8443. This -tends to make it as easy as possible to communicate with the services behind the $productName$ instance. It uses -two `Listener`s and at least one `Host`. - - -#### `Listener`s: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: http-listener -spec: - port: 8080 - protocol: HTTPS # NOT A TYPO, see below - securityModel: XFP - hostBinding: - namespace: - from: SELF # See below ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: - namespace: - from: SELF # See below -``` - -- Both `Listener`s use `protocol: HTTPS` to allow Envoy to inspect incoming connections, determine - whether or not TLS is in play, and set `X-Forwarded-Proto` appropriately. The `securityModel` then specifies - that `X-Forwarded-Proto` will determine whether requests will be considered secure or insecure. - -- The `hostBinding` shown here will allow any `Host` in the same namespace as the `Listener`s - to be associated with both `Listener`s; in turn, that will allow access to that `Host`'s - `Mapping`s from either port. For greater control, use a `selector` instead. - -- Note that the `Listener`s do not specify anything about TLS certificates. The `Host` - handles that; see below. - - - Learn more about Listener - - -#### `Host` - -This example will assume that we expect to be reachable as `foo.example.com`, and that the `foo.example.com` -certificate is stored in the Kubernetes `Secret` named `foo-secret`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: "foo.example.com" - tlsSecret: - name: foo-secret - requestPolicy: - insecure: - action: Redirect -``` - -- The `tlsSecret` specifies the certificate in use for TLS termination. -- The `requestPolicy` specifies routing HTTPS and redirecting HTTP to HTTPS. -- Since the `Host` does not specify a `selector`, only `Mapping`s with a `hostname` that matches - `foo.example.com` will be associated with this `Host`. -- **Note well** that simply defining a `TLSContext` is not sufficient to terminate TLS: you must define either - a `Host` or an `Ingress`. -- Note that if no `Host` is present, but a TLS secret named `fallback-secret` is available, the system will - currently define a `Host` using `fallback-secret`. **This behavior is subject to change.** - - - Learn more about Host - - -### HTTP-Only - -Another straightforward configuration is to support only HTTP, in this case on port 8080. This uses a single -`Listener` and a single `Host`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: http-listener -spec: - port: 8080 - protocol: HTTP - securityModel: INSECURE - hostBinding: - namespace: - from: SELF # See below ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: "foo.example.com" - requestPolicy: - insecure: - action: Route -``` - -- Here, we listen only on port 8080, and only for HTTP. HTTPS will be rejected. -- Since requests are only allowed using HTTP, we declare all requests `INSECURE` by definition. -- The `Host` specifies routing HTTP, rather than redirecting it. - - - - Learn more about Listener
- Learn more about Host - - -### TLS using ACME ($AESproductName$ only) - -This scenario uses ACME to get certificates for `foo.example.com` and `bar.example.com`. HTTPS traffic to either -host is routed; HTTP traffic to `foo.example.com` will be redirected to HTTPS, but HTTP traffic to `bar.example.com` -will be rejected outright. - -Since this example uses ACME, **it is only supported in $AESproductName$**. - -For demonstration purposes, we show this example listening for HTTPS on port 9999, using `X-Forwarded-Proto`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener-9999 -spec: - port: 9999 - protocol: HTTPS - securityModel: XFP - hostBinding: # Edit as needed - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - acmeProvider: - email: julian@example.com ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - acmeProvider: - email: julian@example.com - requestPolicy: - insecure: - action: Reject -``` - -(`Mapping`s are not shown.) - -- Our `Listener`s will accept HTTPS and HTTP on port 9999, and the protocol used will dictate whether - the requests are secure (HTTPS) or insecure (HTTP). -- `foo-host` defaults to ACME with Let's Encrypt, since `acmeProvider.authority` is not provided. -- `foo-host` defaults to redirecting insecure requests, since the default for `requestPolicy.insecure.action` is `Redirect`. -- `bar-host` uses Let's Encrypt as well, but it will reject insecure requests. - -**If you use ACME for multiple Hosts, add a wildcard Host too.** -This is required to manage a known issue. This issue will be resolved in a future Ambassador Edge Stack release. - - - Learn more about Listener
- Learn more about Host - - -### Multiple TLS Certificates - -This scenario uses TLS without ACME. Each of our two `Host`s uses a distinct TLS certificate. HTTPS -traffic to either`foo.example.com` or `bar.example.com` is routed, but this time `foo.example.com` will redirect -HTTP requests, while `bar.example.com` will route them. - -Since this example does not use ACME, it is supported in $productName$ as well as $AESproductName$. - -For demonstration purposes, we show this example listening for HTTPS on port 4848, using `X-Forwarded-Proto`. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: foo-example-secret -data: - tls.crt: -certificate PEM- - tls.key: -secret key PEM- ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: bar-example-secret -data: - tls.crt: -certificate PEM- - tls.key: -secret key PEM- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener-4848 -spec: - port: 4848 - protocol: HTTPS - securityModel: XFP - hostBinding: # Edit as needed - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - tlsSecret: - name: foo-example-secret ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - tlsSecret: - name: bar-example-secret - requestPolicy: - insecure: - action: Route -``` - -- `foo-host` and `bar-host` simply reference the `tlsSecret` to use for termination. - - If the secret involved contains a wildcard cert, or a cert with multiple SAN, both `Host`s could - reference the same `tlsSecret`. -- `foo-host` relies on the default insecure routing action of `Redirect`. -- `bar-host` must explicitly specify routing HTTP. - - - - Learn more about Listener
- Learn more about Host - - -### Using a `TLSContext` - -If you need to share other TLS settings between two `Host`s, you can reference a `TLSContext` as well as -the `tlsSecret`. This is the same as the previous example, but we use a `TLSContext` to set `ALPN` information, -and we assume that the `Secret` contains a wildcard cert. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: wildcard-example-secret -data: - tls.crt: -wildcard here- - tls.key: -wildcard here- ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-context -spec: - secret: wildcard-example-secret - alpn_protocols: [h2, istio] ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: https-listener-4848 -spec: - port: 4848 - protocol: HTTPS - securityModel: XFP - hostBinding: # Edit as needed - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - tlsContext: - name: example-context - tlsSecret: - name: wildcard-example-secret ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - tlsContext: - name: example-context - tlsSecret: - name: wildcard-example-secret - requestPolicy: - insecure: - action: Route -``` - -- Note that specifying the `tlsSecret` is still necessary, even when `tlsContext` is specified. - - - - Learn more about Listener
- Learn more about Host - - -### ACME With a TLSContext ($AESproductName$ Only) - -In $AESproductName$, you can use a `TLSContext` with ACME as well. This example is the same as "TLS using ACME", -but we use a `TLSContext` to set `ALPN` information. Again, ACME is only supported in $AESproductName$. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-context -spec: - secret: example-acme-secret - alpn_protocols: [h2, istio] ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com - acmeProvider: - email: julian@example.com - tlsContext: - name: example-context - tlsSecret: - name: example-acme-secret -``` - -- Note that we don't provide the `Secret`: the ACME client will create it for us. - - - - Learn more about Listener
- Learn more about Host - - -### Using an L7 Load Balancer to Terminate TLS - -In this scenario, a layer 7 load balancer ahead of $productName$ will terminate TLS, so $productName$ will always see HTTP with a known good `X-Forwarded-Protocol`. We'll use that to route HTTPS and redirect HTTP. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: lb-listener -spec: - port: 8443 - protocol: HTTP - securityModel: XFP - l7Depth: 1 - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: "foo.example.com" - requestPolicy: - insecure: - action: Redirect -``` - -- We set `l7Depth` to 1 to indicate that there's a single trusted L7 load balancer ahead of us. -- We specifically set this Listener to HTTP-only, but we stick with port 8443 just because we expect people setting up TLS at all to expect to use port 8443. (There's nothing special about the port number, pick whatever you like.) -- Our `Host` does not specify a `tlsSecret`, so $productName$ will not try to terminate TLS. -- Since the `Listener` still pays attention to `X-Forwarded-Proto`, both secure and insecure requests - are possible, and we use the `Host` to route HTTPS and redirect HTTP. - - - - Learn more about Listener
- Learn more about Host - - -### Using a Split L4 Load Balancer to Terminate TLS - -Here, we assume that $productName$ is behind a load balancer setup that handles TLS at layer 4: - -- Incoming cleartext traffic is forwarded to $productName$ on port 8080. -- Incoming TLS traffic is terminated at the load balancer, then forwarded to $productName$ _as cleartext_ on port 8443. -- This might involve multiple L4 load balancers, but the actual number doesn't matter. -- The actual port numbers we use don't matter either, as long as $productName$ and the load balancer(s) agree on which port is for which traffic. - -We're going to route HTTPS for both `foo.example.com` and `bar.example.com`, redirect HTTP for `foo.example.com`, and reject HTTP for `bar.example.com`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: split-lb-one-listener -spec: - protocol: HTTP - port: 8080 - securityModel: INSECURE - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: split-lb-two-listener -spec: - protocol: HTTP - port: 8443 - securityModel: SECURE - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: foo.example.com ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host -spec: - hostname: bar.example.com - requestPolicy: - insecure: - action: Reject -``` - -- Since L4 load balancers cannot set `X-Forwarded-Protocol`, we don't use it at all here: instead, we dictate that 8080 and 8443 both speak cleartext HTTP, but everything arriving at port 8080 is insecure and everything at port 8443 is secure. - - - - Learn more about Listener
- Learn more about Host - - -### Listening on Multiple Ports - -There's no reason you need to use ports 8080 and 8443, or that you're limited to two ports. Here we'll use ports 9001 and 9002 for HTTP, and port 4001 for HTTPS. We'll route traffic irrespective of protocol. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-9001 -spec: - protocol: HTTP - port: 9001 - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-9002 -spec: - protocol: HTTP - port: 9002 - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-4001 -spec: - protocol: HTTPS - port: 4001 - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: route-host -spec: - requestPolicy: - insecure: - action: Route -``` - -- We can use `X-Forwarded-Proto` for all our `Listener`s: the HTTP-only `Listener`s will set it correctly. -- Each `Listener` can specify only one port, but there's no hardcoded limit on the number of `Listener`s you can have. - - - - Learn more about Listener
- Learn more about Host - - -### Using Labels to Associate `Host`s and `Listener`s - -In the examples above, the `Listener`s all associate with any `Host` in their namespace. In this -example, we will use Kubernetes labels to control the association instead. - -Here, we'll listen for HTTP to `foo.example.com` on port 8888, and for either HTTP or HTTPS to `bar.example.com` on -port 9999 (where we'll redirect HTTP to HTTPS). Traffic to `baz.example.com` will work on both ports, and we'll route -HTTP for it rather than redirecting. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-8888 -spec: - protocol: HTTP - port: 8888 - securityModel: XFP - hostBinding: - selector: - matchLabels: - tenant: foo ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-9999 -spec: - protocol: HTTPS - port: 9999 - securityModel: XFP - hostBinding: - selector: - matchLabels: - tenant: bar ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: bar-secret -data: - tls.crt: -wildcard here- - tls.key: -wildcard here- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host - labels: - tenant: foo -spec: - hostname: foo.example.com - requestPolicy: - insecure: - action: Route ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: bar-host - labels: - tenant: bar -spec: - hostname: bar.example.com - tlsSecret: - name: bar-secret ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: baz-host - labels: - tenant: foo - tenant: bar -spec: - hostname: baz.example.com - tlsSecret: - name: bar-secret - requestPolicy: - insecure: - action: Route -``` - -- Note the `labels` on each `Host`, which the `hostBinding` on the `Listener` can reference. - - Note also that only label selectors are supported at the moment. - - - - Learn more about Listener
- Learn more about Host - - -### Wildcard `Host`s and `Mapping`s - -In a `Mapping`, the `host` is now treated as a glob rather than an exact match, with the goal of vastly reducing the need for `host_regex`. (The `hostname` in a `Host` has always been treated as a glob). - -- **Note that only prefix and suffix matches are supported**, so `*.example.com` and `foo.*` are both fine, but `foo.*.com` will not work -- you'll need to use `host_regex` if you really need that. (This is an Envoy limitation.) - -In this example, we'll accept both HTTP and HTTPS, but: - -- Cleartext traffic to any host in `lowsec.example.com` will be routed. -- Cleartext traffic to any host in `normal.example.com` will be redirected. -- Any other cleartext traffic will be rejected. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: example-secret -data: - tls.crt: -wildcard for *.example.com here- - tls.key: -wildcard for *.example.com here- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-8443 -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: # This may well need editing for your case! - namespace: - from: SELF ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: lowsec-host -spec: - hostname: "*.lowsec.example.com" - tlsSecret: - name: example-secret - requestPolicy: - insecure: - action: Route ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: normal-host -spec: - hostname: "*.normal.example.com" - tlsSecret: - name: example-secret - requestPolicy: # We could leave this out since - insecure: # redirecting is the default, but - action: Redirect # it's spelled out for clarity. ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: catchall-host -spec: - hostname: "*.example.com" - tlsSecret: - name: example-secret - requestPolicy: - insecure: - action: Reject -``` - -- We'll listen for HTTP or HTTPS on port 8443. -- The three `Host`s apply different insecure routing actions depending on the hostname. -- You could also do this with `host_regex`, but using `host` with globs will give better performance. - - Being able to _not_ associate a given `Mapping` with a given `Host` when the `Mapping`'s - `host` doesn't match helps a lot when you have many `Host`s. - - Reliably determining if a regex (for the `Mapping`) matches a glob (for the `Host`) isn't really possible, so we can't prune `host_regex` `Mapping`s at all. - - - Learn more about Listener
- Learn more about Host - diff --git a/content/en/docs/pre-release/howtos/consul.md b/content/en/docs/pre-release/howtos/consul.md deleted file mode 100644 index d75e35ce..00000000 --- a/content/en/docs/pre-release/howtos/consul.md +++ /dev/null @@ -1,564 +0,0 @@ - -import Alert from '@material-ui/lab/Alert'; - -# Consul integration - -
-

Contents

- -- [Consul integration](#consul-integration) - - [Architecture overview](#architecture-overview) - - [Installing Consul](#installing-consul) - - [Installing $productName$](#installing-consul) - - [Using Consul for service discovery](#using-consul-for-service-discovery) - - [Using Consul for authorization and encryption](#using-consul-for-authorization-and-encryption) - - [Environment variables](#environment-variables) - - [More information](#more-information) - -
- -[Consul](https://www.consul.io) is a widely used service mesh. -$productName$ natively supports service discovery and unauthenticated -communication to services in Consul. Additionally, the *Ambassador -Consul Connector* enables $productName$ to encrypt and authenticate -its communication via mTLS with services in Consul that make use of -[Consul's *Connect* feature](https://www.consul.io/docs/connect). - -## Architecture overview - -Using Consul with $productName$ is particularly useful when deploying -$productName$ in hybrid cloud environments where you deploy -applications on VMs and Kubernetes. In this environment, Consul -enables $productName$ to securely route over TLS to any application -regardless of where it is deployed. - -In this architecture, Consul serves as the source of truth for your -entire data center, tracking available endpoints, service -configuration, and secrets for TLS encryption. New applications and -services automatically register themselves with Consul using the -Consul agent or API. When you send a request through $productName$, -$productName$ sends the request to an endpoint based on the data in -Consul. - -![ambassador-consul](../images/consul-ambassador.png) - -This guide first instructs you on registering a service with Consul -and using $productName$ to dynamically route requests to that service -based on Consul's service discovery data, and subsequently instructs -you on using using the Ambassador Consul Connector to use Consul for -authorizing and encrypting requests. - -## Installing Consul - -If you already have Consul installed in your cluster, then go ahead -and skip to the next section. - -1. Before you install Consul, make sure to check the Consul - documentation for any setup steps specific to your platform. Below - you can find setup guides for some of the more popular Kubernetes - platforms. This step is primarily to ensure you have the proper - permissions to set up Consul. You can skip these guides if your - cluster is already configured to grant you the necessary - permissions. - - - [Microsoft Azure Kubernetes Service (AKS)](https://learn.hashicorp.com/tutorials/consul/kubernetes-aks-azure?utm_source=consul.io&utm_medium=docs) - - [Amazon Elastic Kubernetes Service (EKS)](https://learn.hashicorp.com/tutorials/consul/kubernetes-eks-aws?utm_source=consul.io&utm_medium=docs) - - [Google Kubernetes Engine (GKE)](https://learn.hashicorp.com/tutorials/consul/kubernetes-gke-google?utm_source=consul.io&utm_medium=docs) - - - - If you did not find your Kubernetes platform above, check the - [Consul documentation here](https://www.consul.io/docs/k8s) to see - if there are specific setup instructions for your platform. - - - -2. Add the Hashicorp repository for installing Consul with Helm. If - you do not have Helm installed, you can find an [installation guide - here](https://helm.sh/docs/intro/install/). - - ```shell - helm repo add hashicorp https://helm.releases.hashicorp.com - ``` - -3. Create a new `consul-values.yaml` YAML file for the Consul - installation values and copy the values below into that file. - - ```yaml - global: - datacenter: dc1 - - ui: - service: - type: 'LoadBalancer' - - syncCatalog: - enabled: true - - server: - replicas: 1 - bootstrapExpect: 1 - - connectInject: - enabled: true - ``` - - - - Note: you are free to change the value of the `datacenter` field in - the install values. This is the the name of your Consul - Datacenter. - - - -4. Install Consul with Helm using the `consul-values.yaml` values file - you just created. - - ```shell - helm install -f consul-values.yaml hashicorp hashicorp/consul - ``` - -## Installing $productName$ - -If you have not already installed $productName$ in to your cluster, -then go to the [quick start guide](../../tutorials/getting-started) -before continuing any further in this guide. - -## Using Consul for service discovery - -This section of the guide instructs you on configuring $productName$ -to look for services registered to Consul, registering a demo -application with Consul, and configuring $productName$ to route to -this application using endpoint data from Consul. - -In this tutorial, you deploy the application in Kubernetes. However, -this application can be deployed anywhere in your data center, such as -on a VM. - -1. Configure $productName$ to look for services registered to Consul - by creating the `ConsulResolver`. Use `kubectl` to apply the - following manifest: - - ```shell - kubectl apply -f < - - **Note:** If you changed the name of your `datacenter` in the - Consul install values, make sure to change it in the resolver above - to match the name of your datacenter. - - If you changed the name of the helm install from `hashicorp` to - another value, make sure to update the value of the `address` field - in your resolver to match it. - - If you are having trouble figuring out what your `address` field - should be, it follow this format: - `http://{consul_server_pod}.{consul_server_service}.{namespace}.svc.cluster.local:{consul_port}`. - The default Consul port should be `8500` unless you changed it. - - - - This tells $productName$ that Consul is a service discovery endpoint. - - You must set the resolver to your `ConsulResolver` on a - per-`Mapping` basis, otherwise for that `Mapping` $productName$ - uses the default resolver. That is, in order for a `Mapping` to - make use of a service registered in Consul, you need to add - `resolver: consul-dc1` to that `Mapping`. - - For more information about resolver configuration, see the - [resolver reference documentation](../../topics/running/resolvers). - (If you're using Consul deployed elsewhere in your data center, - make sure the `address` points to your Consul FQDN or IP address). - -2. Deploy the Quote demo application. Use `kubectl` to - apply the following manifest: - - ```shell - kubectl apply -f < - - The `SERVICE_NAME` environment variable in the `quote-consul` - `Deployment` specifies the service name for Consul. The default - value is set to "quote-consul", so you only need to include it if - you want to change the service name. - - - - The Quote application contains code to automatically - register itself with Consul, using the `CONSUL_IP` and `POD_IP` - environment variables specified within the `quote-consul` container - spec. - - When you apply this manifest, it registers the `Pod` in the - `quote-consul` `Deployment` as a Consul service with the name - `quote-consul` and the IP address of the `Pod`. - - - - The `"consul.hashicorp.com/connect-inject": "false"` annotation - tells Consul that for this `Deployment` you do not want to use the - sidecar proxy that is part of Consul's Connect feature. Without - Consul's sidecar, the service needs to include code to make a - request to Consul to register the service. The manifest includes - the environment variables `CONSUL_IP`, `POD_IP`, and `SERVICE_NAME` - to provide the Quote service with enough information - to build that request and send it to Consul. To see how this code - works, see our [our Git repo for the Quote - service](https://github.com/datawire/quote). - - - -3. Verify the `quote-consul` `Deployment`'s `Pod` has been registered - with Consul. You can verify this by accessing the Consul UI. - - First use `kubectl port-forward` to make the UI available on your - local workstation: - - ```shell - kubectl port-forward service/hashicorp-consul-ui 8500:80 - ``` - - Then, while the port-forward is running, go to - http://localhost:8500/ in a web browser. You should see a service - named `quote-consul`. - - After you have verified that you see the `quote-consul` service in - your web browser, you may kill the port-forward. - - - - Port forwarding not working for you? Make sure the service name - matches your Consul UI service by checking `kubectl get svc -A` - - - -4. Configure $productName$ to make use of this `quote-consul` service. - Use `kubectl` to apply the following manifest: - - ```shell - kubectl apply -f < - -**Congratulations!** You're successfully routing traffic to the Quote -application, the location of which is registered in -Consul. - - - -## Using Consul for authorization and encryption - -In this part of the guide, you'll install a different version of the -demo application that now uses Consul's *Connect* feature to authorize -its incoming connections using mTLS, and install *Ambassador Consul -Connector* to enable $productName$ to authenticate to such services. - -The following steps assume you've already set up Consul for service -discovery, as detailed above. - -1. The Ambassador Consul Connector retrieves the TLS certificate - issued by the Consul CA and stores it in a Kubernetes `Secret` for - $productName$ to use. Deploy the Ambassador Consul Connector with - `kubectl`: - - ```shell - kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/consul/ambassador-consul-connector.yaml - ``` - - This installs in to your cluster: - - - RBAC resources. - - The Ambassador Consul Connector service. - - A `TLSContext` named `ambassador-consul` to load the - `ambassador-consul-connect` `Secret` into $productName$. - -2. Deploy a new version of the demo application, and configure it to - inject the Consul Connect sidecar by setting - `"consul.hashicorp.com/connect-inject"` to `true`. Note that in - this version of the configuration, you do not have to configure - environment variables for the location of the Consul server. Use - `kubectl` to apply the following manifest: - - ```yaml - kubectl apply -f - < - - Note: Annotations are used to attach metadata to Kubernetes - objects. You can use annotations to link external information to - objects, working in a similar, yet different, fashion to labels. - For more information on annotations, refer to the [Annotating - Kubernetes Services for - Humans](https://kubernetes.io/blog/2021/04/20/annotating-k8s-for-humans/) - article, or get started with annotations in your own cluster with - the [Ambassador Cloud Quick start - guide](https://www.getambassador.io/docs/cloud/latest/service-catalog/quick-start/). - - - - This deploys a demo application `Deployment` called `quote-connect` - (different than the `quote-consul` `Deployment` in the previous - section) with the Consul Connect sidecar proxy. The Connect - sidecar registers the application with Consul, requires TLS to - access the application, and exposes other [Consul Service - Segmentation](https://www.consul.io/docs/connect) features. - - The annotation `consul.hashicorp.com/connect-inject` being set to - `true` in this `Deployment` tells Consul that you want this - `Deployment` to use the Consul Connect sidecar. The sidecar - proxies requests to the service that it is attached to. Keep this - in mind mind when debug requests to the service. - -4. Verify the `quote-connect` `Deployment`'s `Pod` has been registered - with Consul. You can verify this by accessing the Consul UI. - - First use `kubectl port-forward` to make the UI available on your - local workstation: - - ```shell - kubectl port-forward service/hashicorp-consul-ui 8500:80 - ``` - - Then, while the port-forward is running, open - http://localhost:8500/ in a web browser. You should see a service - named `quote-connect`. - - After you have verified that you see the `quote-connect` service in - your web browser, you may kill the port-forward. - -5. Create a `Mapping` to configure $productName$ route to the - `quote-connect` service in Consul. Use `kubectl` to apply the - following manifest: - - ```shell - kubectl apply -f < - -**Congratulations!** You successfully configured the service to work -with the Consul Connect sidecar. - - - -### Environment variables - -The Ambassador Consul Connector can be configured with the following -environment variables. The defaults are best for most use-cases. - -| Environment Variable | Description | Default | -|------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------| -| `_AMBASSADOR_ID` | Set 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`) | `""` | -| `_CONSUL_HOST` | Set the IP or DNS name of the target Consul HTTP API server | `127.0.0.1` | -| `_CONSUL_PORT` | Set the port number of the target Consul HTTP API server | `8500` | -| `_AMBASSADOR_TLS_SECRET_NAME` | Set the name of the Kubernetes `v1.Secret` created by this program that contains the Consul-generated TLS certificate. | `$AMBASSADOR_ID-consul-connect` | -| `_AMBASSADOR_TLS_SECRET_NAMESPACE` | Set the namespace of the Kubernetes `v1.Secret` created by this program. | (same Namespace as the Pod running this integration) | - -## More information - -For more about $productName$'s integration with Consul, read the -[service discovery configuration](../../topics/running/resolvers) -documentation. diff --git a/content/en/docs/pre-release/howtos/dist-tracing.md b/content/en/docs/pre-release/howtos/dist-tracing.md deleted file mode 100644 index aa62e5bf..00000000 --- a/content/en/docs/pre-release/howtos/dist-tracing.md +++ /dev/null @@ -1,27 +0,0 @@ -# Explore distributed tracing and Kubernetes monitoring - -The Kubernetes monitoring and distributed tracing landscape is hard to grasp. Although this conceptual approach to [observability is nothing new](https://blog.getambassador.io/distributed-tracing-with-java-microdonuts-kubernetes-and-the-ambassador-api-gateway-ace15b62a89e) — companies like New Relic revolutionized single-application performance monitoring (APM) over a decade ago — it took a few years and the [Dapper publication](https://research.google/pubs/pub36356/) for this idea to migrate to distributed applications. The importance of this technology is only increasing, as more and more of us are building deep systems. - -As the industry is slowly but surely maturing, standardization is underway. Standardization means proprietary vendor solutions and open source projects are able to collaborate, making our lives easier. For newcomers, understanding the plethora of options, concepts, specifications, and implementations available is still a daunting task: - -* How are Zipkin and Jaeger related? -* What is header propagation? -* Which headers format should I use? -* Who owns the initialization of a trace context? -* How are the data points collected? - -## Tracing the Future: OpenTelemetry - -The [OpenTelemetry project](https://opentelemetry.io/) was created with the intent of stopping the proliferation of API standards and libraries one might need to support for all their observability needs, effectively replacing the Zipkin-API, OpenCensus, OpenTracing and more competing implementations. - -> OpenTelemetry provides a single set of APIs, libraries, agents, and collector services to capture distributed traces and metrics from your application. You can analyze them using Prometheus, Jaeger, and other observability tools.
--[https://opentelemetry.io/](https://opentelemetry.io/) - -It’s at this point in the conversation that someone inevitably mentions that XKCD... - -![XKCD #927](../images/xkcd.png) - -OpenTelemetry ultimately supports multiple formats in its [OpenTelemetry-Collector](https://github.com/open-telemetry/opentelemetry-collector), easing the transition from one technology to another when installed as a middleware and translator to relay trace data to other collectors. Along with many of its long-awaited features, it supports multiple trace exporters for Jaeger, Zipkin and proprietary APIs. - -## Learn More -We also have guides to setup Edge Stack with [Datadog](../tracing-datadog/), [Zipkin](../tracing-zipkin/), and [Prometheus and Grafana](../prometheus). diff --git a/content/en/docs/pre-release/howtos/external-dns.md b/content/en/docs/pre-release/howtos/external-dns.md deleted file mode 100644 index f0f51dbb..00000000 --- a/content/en/docs/pre-release/howtos/external-dns.md +++ /dev/null @@ -1,130 +0,0 @@ -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 - -Start by checking the [ExternalDNS repo's deployment instructions](https://github.com/kubernetes-sigs/external-dns#deploying-to-a-cluster) to get information about the supported DNS providers and steps to setup ExternalDNS for your provider. Each DNS provider will have its own required steps as well as annotations, arguments, and permissions needed for the following configuration. - - -### Installation - -Configuration for a `ServiceAccount`, `ClusterRole`, and `ClusterRoleBinding` are necessary for the ExternalDNS deployment to support compatability 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 above for annotations and arguments for your DNS Provider. - - -1. Create a YAML file named `externaldns-config.yaml`, and copy the following configuration into it. - - - Ensure that the apiGroups include "getambassador.io" following "networking.k8s.io" and the resources include "hosts" after "ingresses". - - - ```yaml - --- - apiVersion: v1 - kind: ServiceAccount - metadata: - name: external-dns - annotations: - eks.amazonaws.com/role-arn: {ARN} # AWS ARN role - --- - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRole - metadata: - name: external-dns - rules: - - apiGroups: [""] - resources: ["services","endpoints","pods"] - verbs: ["get","watch","list"] - - apiGroups: ["extensions","networking.k8s.io", "getambassador.io"] - resources: ["ingresses", "hosts"] - verbs: ["get","watch","list"] - - apiGroups: [""] - resources: ["nodes"] - verbs: ["list","watch"] - --- - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRoleBinding - metadata: - name: external-dns-viewer - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: external-dns - subjects: - - kind: ServiceAccount - name: external-dns - namespace: default - --- - apiVersion: apps/v1 - kind: Deployment - metadata: - name: external-dns - spec: - strategy: - type: Recreate - selector: - matchLabels: - app: external-dns - template: - metadata: - labels: - app: external-dns - annotations: - iam.amazonaws.com/role: {ARN} # AWS ARN role - spec: - serviceAccountName: external-dns - containers: - - name: external-dns - image: registry.opensource.zalan.do/teapot/external-dns:latest - args: - - --source=ambassador-host - - --domain-filter=example.net # will make ExternalDNS see only the hosted zones matching provided domain, omit to process all available hosted zones - - --provider=aws - - --policy=upsert-only # would prevent ExternalDNS from deleting any records, omit to enable full synchronization - - --aws-zone-type=public # only look at public hosted zones (valid values are public, private or no value for both) - - --registry=txt - - --txt-owner-id= {Hosted Zone ID} # Insert Route53 Hosted Zone ID here - ``` - -2. Review the arguments section from the ExternalDNS deployment - - Configure or remove arguments to fit your needs. Additional arguments required for your DNS provider can be found by checking the [ExternalDNS repo's deployment instructions](https://github.com/kubernetes-sigs/external-dns#deploying-to-a-cluster). - - * `--source=ambassador-host` - required across all DNS providers to tell ExternalDNS to look for hostnames in the $productName$ `Host` configurations. - -3. Apply the above config with the following command to deploy ExternalDNS to your cluster and configure support for $productName$ - - ```shell - kubectl apply -f externaldns-ambassador.yaml - ``` - - - For the above example, ensure that you are using an EKS cluster, or register your cluster with AWS so that ExternalDNS can view and edit your AWS Hosted Zones. If you are using a cluster outside EKS and not registered with AWS you will see permissions errors from the ExternalDNS pod when attempting to list the Hosted Zones. - - -## Usage - -After applying the above configuration, ExternalDNS is ready to use. Configure a `Host` with the following annotation to allow ExternalDNS to get the IP address of your $productName$'s LoadBalancer and register it with your DNS provider. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: your-hostname - annotations: - external-dns.ambassador-service: $productDeploymentName$.$productNamespace$ -spec: - acmeProvider: - authority: none - hostname: your-hostname.example.com -``` - - -Victory! ExternalDNS is now running and configured to report $productName$'s IP and hostname with your DNS provider. diff --git a/content/en/docs/pre-release/howtos/filter-dev-guide.md b/content/en/docs/pre-release/howtos/filter-dev-guide.md deleted file mode 100644 index eefe8b6b..00000000 --- a/content/en/docs/pre-release/howtos/filter-dev-guide.md +++ /dev/null @@ -1,97 +0,0 @@ -# Developing custom filters for routing - -Sometimes you may want $AESproductName$ to manipulate an incoming request. Some example use cases: - -* Inspect an incoming request, and add a custom header that can then be used for routing -* Add custom Authorization headers -* Validate an incoming request fits an OpenAPI specification before passing the request to a target service - -$AESproductName$ supports these use cases by allowing you to execute custom logic in `Filters`. Filters are written in Golang, and managed by $AESproductName$. If you want to write a filter in a language other than Golang, $AESproductName$ also has an HTTP/gRPC interface for Filters called `External`. - -## Prerequisites - -`Plugin` `Filter`s are built as [Go plugins](https://golang.org/pkg/plugin/) and loaded directly into the $AESproductName$ container so they can run in-process with the rest of $AESproductName$. - -To build a `Plugin` `Filter` into the $AESproductName$ container you will need -- Linux or MacOS host (Windows Subsystem for Linux is ok) -- [Docker](https://docs.docker.com/install/) -- [rsync](https://rsync.samba.org/) - -The `Plugin` `Filter` is built by `make` which uses Docker to create a stable build environment in a container and `rsync` to copy files between the container and your host machine. - -See the [README](https://github.com/datawire/apro-example-plugin) for more information on how the `Plugin` works. - -## Creating and deploying filters - -We've created an example filter that you can customize for your particular use case. - -1. Start with the example filter: `git clone - https://github.com/datawire/apro-example-plugin/`. - -2. Make code changes to `param-plugin.go`. Note: If you're developing a non-trivial filter, see the rapid development section below for a faster way to develop and test your filter. - -3. Run `make DOCKER_REGISTRY=...`, setting `DOCKER_REGISTRY` to point - to a registry you have access to. This will generate a Docker image - named `$DOCKER_REGISTRY/amb-sidecar-plugin:VERSION`. - -4. Push the image to your Docker registry: `docker push $DOCKER_REGISTRY/amb-sidecar-plugin:VERSION`. - -5. Configure $AESproductName$ to use the plugin by creating a `Filter` - and `FilterPolicy` CRD, as per the [filter reference](/docs/edge-stack/latest/topics/using/filters/). - -6. Update the standard $AESproductName$ manifest to use your Docker - image instead of the standard sidecar. - - ```patch - value: '60' - - name: AMBASSADOR_INTERNAL_URL - value: https://127.0.0.1:8443 - - image: docker.io/datawire/aes:$version$ - + image: DOCKER_REGISTRY/aes-plugin:VERSION - imagePullPolicy: Always - livenessProbe: - httpGet: - ``` - -## Rapid development of a custom filter - -During development, you may want to sidestep the deployment process for a faster development loop. The `aes-plugin-runner` helps you rapidly develop $AESproductName$ filters locally. - -To install the runner, download the latest version: - -Mac 64-bit | -Linux 64-bit - -Note that the plugin runner must match the version of $AESproductName$ that you are running. Place the binary somewhere in your `$PATH`. - -Information about open-source code used in `aes-plugin-runner` can be found by running `aes-plugin-runner --version`. - -Now, you can quickly test and develop your filter. - -1. In your filter directory, type: `aes-plugin-runner :8080 ./param-plugin.so`. -2. Test the filter by running `curl`: - - ``` - $ curl -Lv localhost:8080?db=2 - * Rebuilt URL to: localhost:8080/?db=2 - * Trying ::1... - * TCP_NODELAY set - * Connected to localhost (::1) port 8080 (#0) - > GET /?db=2 HTTP/1.1 - > Host: localhost:8080 - > User-Agent: curl/7.54.0 - > Accept: */* - > - < HTTP/1.1 200 OK - < X-Dc: Even - < Date: Mon, 25 Feb 2019 19:58:38 GMT - < Content-Length: 0 - < - * Connection #0 to host localhost left intact - ``` - -Note in the example above the `X-Dc` header is added. This lets you inspect the changes the filter is making to your HTTP header. - -## Further reading - -For more details about configuring filters and the `plugin` interface, see the [filter reference](/docs/edge-stack/latest/topics/using/filters/). diff --git a/content/en/docs/pre-release/howtos/grpc.md b/content/en/docs/pre-release/howtos/grpc.md deleted file mode 100644 index 3967ddf7..00000000 --- a/content/en/docs/pre-release/howtos/grpc.md +++ /dev/null @@ -1,403 +0,0 @@ -# gRPC Connections - -$productName$ makes it easy to access your services from outside your application. This includes gRPC services, although a little bit of additional configuration is required: by default, Envoy connects to upstream services using HTTP/1.x and then upgrades to HTTP/2 whenever possible. However, gRPC is built on HTTP/2 and most gRPC servers do not speak HTTP/1.x at all. $productName$ must tell its underlying Envoy that your gRPC service only wants to speak to that HTTP/2, using the `grpc` attribute of a `Mapping`. - -## Writing a gRPC service for $productName$ - -There are many examples and walkthroughs on how to write gRPC applications so that is not what this article will aim to accomplish. If you do not yet have a service written you can find examples of gRPC services in all supported languages here: [gRPC Quickstart](https://grpc.io/docs/quickstart/) - -This document will use the [gRPC python helloworld example](https://github.com/grpc/grpc/tree/master/examples/python/helloworld) to demonstrate how to configure a gRPC service with $productName$. - -Follow the example up through [Run a gRPC application](https://grpc.io/docs/languages/python/quickstart/#run-a-grpc-application) to get started. - -### Dockerize - -After building our gRPC application and testing it locally, we need to package it as a Docker container and deploy it to Kubernetes. - -To run a gRPC application, we need to include the client/server and the protocol buffer definitions. - -For gRPC with python, we need to install `grpcio` and the common protos. - -```Dockerfile -FROM python:2.7 - -WORKDIR /grpc - -ENV PATH "$PATH:/grpc" - -COPY greeter_server.py /grpc -COPY helloworld_pb2.py /grpc -COPY helloworld_pb2_grpc.py /grpc - -RUN python -m pip install grpcio -RUN python -m pip install grpcio-tools googleapis-common-protos - -CMD ["python", "./greeter_server.py"] - -EXPOSE 50051 -``` - -Create the container and test it: - -``` -$ docker build -t /grpc_example -$ docker run -p 50051:50051 /grpc_example -``` - -Where `` is your Docker user or registry. - -Switch to another terminal and from the same directory, run the `greeter_client`. The output should be the same as running it outside of the container. - -``` -$ docker run -p 50051:50051 /grpc_example -Greeter client received: Hello, you! -``` - -Once you verify the container works, push it to your Docker registry: - -``` -$ docker push /grpc_example -``` - -### Mapping gRPC services - -$productName$ `Mapping`s are based on URL prefixes; for gRPC, the URL prefix is the full-service name, including the package path (`package.service`). These are defined in the `.proto` definition file. In the example [proto definition file](https://github.com/grpc/grpc/blob/master/examples/protos/helloworld.proto) we see: - -``` -package helloworld; - -// The greeting service definition. -service Greeter { ... } -``` - -so the URL `prefix` is `helloworld.Greeter` and the mapping would be: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py -spec: - hostname: "*" - grpc: True - prefix: /helloworld.Greeter/ - rewrite: /helloworld.Greeter/ - service: grpc-example -``` - -Note the `grpc: true` line - this is what tells Envoy to use HTTP/2 so the request can communicate with your backend service. Also note that you'll need `prefix` and `rewrite` the same here, since the gRPC service needs the package and service to be in the request to do the right thing. - -### Deploying to Kubernetes - -`grpc_example.yaml` - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - acmeProvider: - authority: none - requestPolicy: - insecure: - action: Route ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py -spec: - hostname: "*" - grpc: True - prefix: /helloworld.Greeter/ - rewrite: /helloworld.Greeter/ - service: grpc-example - ---- -apiVersion: v1 -kind: Service -metadata: - labels: - service: grpc-example - name: grpc-example -spec: - type: ClusterIP - ports: - - name: grpc-greet - port: 80 - targetPort: grpc-api - selector: - service: grpc-example ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: grpc-example -spec: - replicas: 1 - selector: - matchLabels: - service: grpc-example - template: - metadata: - labels: - service: grpc-example - spec: - containers: - - name: grpc-example - image: /grpc_example - ports: - - name: grpc-api - containerPort: 50051 - restartPolicy: Always -``` - -The Host is declared here because we are using gRPC without TLS. Since $productName$ terminates TLS by default, in the Host we add a `requestPolicy` which allows insecure connections. After adding the $productName$ mapping to the service, the rest of the Kubernetes deployment YAML file is pretty straightforward. We need to identify the container image to use, expose the `containerPort` to listen on the same port the Docker container is listening on, and map the service port (80) to the container port (50051). - -> For more information on insecure routing, please refer to the [`Host` documentation](../../topics/running/host-crd#secure-and-insecure-requests). - - -Once you have the YAML file and the correct Docker registry, deploy it to your cluster with `kubectl`. - -``` -$ kubectl apply -f grpc_example.yaml -``` - -### Testing the Deployment - -Make sure to test your Kubernetes deployment before making more advanced changes (like adding TLS). To test any service with $productName$, we will need the hostname of the running $productName$ service which you can get with: - -``` -$ kubectl get service ambassador -o wide -``` -Which should return something similar to: - -``` -NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE -ambassador 10.11.12.13 35.36.37.38 80:31656/TCP 1m -``` -where `EXTERNAL-IP` is the `$AMBASSADORHOST` and 80 is the `$PORT`. - -You will need to open the `greeter_client.py` and change `localhost:50051` to `$AMBASSADORHOST:$PORT` - -```diff -- with grpc.insecure_channel('localhost:50051') as channel: -+ with grpc.insecure_channel(‘$AMBASSADORHOST:$PORT’) as channel: - stub = helloworld_pb2_grpc.GreeterStub(channel) - response = stub.SayHello(helloworld_pb2.HelloRequest(name='you')) - print("Greeter client received: " + response.message) -``` - -After making that change, simply run the client again and you will see the gRPC service in your cluster respond: - -``` -$ python greeter_client.py -Greeter client received: Hello, you! -``` - -### gRPC and TLS - -There is some extra configuration required to connect to a gRPC service through $productName$ over an encrypted channel. Currently, the gRPC call is being sent over cleartext to $productName$ which proxies it to the gRPC application. - -![](../images/grpc-tls.png) - -If you want to add TLS encryption to your gRPC calls, first you need to tell $productName$ to add [ALPN protocols](../../topics/running/tls) which are required by HTTP/2 to do TLS. - -For example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls -spec: - hosts: - - "*" - secret: ambassador-cert - alpn_protocols: h2 -``` - -Next, you need to change the client code slightly and tell it to open a secure RPC channel with $productName$. - -```diff -- with grpc.insecure_channel(‘$AMBASSADORHOST:$PORT’) as channel: -+ with grpc.secure_channel(‘$AMBASSADORHOST:$PORT’, grpc.ssl_channel_credentials()) as channel: - stub = helloworld_pb2_grpc.GreeterStub(channel) - response = stub.SayHello(helloworld_pb2.HelloRequest(name='you')) - print("Greeter client received: " + response.message) -``` - -`grpc.ssl_channel_credentials(root_certificates=None, private_key=None, certificate_chain=None)`returns the root certificate that will be used to validate the certificate and public key sent by $productName$. The default values of `None` tells the gRPC runtime to grab the root certificate from the default location packaged with gRPC and ignore the private key and certificate chain fields. Generally, passing no arguments to the method that requests credentials gives the same behavior. Refer to the languages [API Reference](https://grpc.io/docs/) if this is not the case. - -$productName$ is now terminating TLS from the gRPC client and proxying the call to the application over cleartext. - -![](../images/gRPC-TLS-Ambassador.png) - -If you want to configure authentication in another language, [gRPC provides examples](https://grpc.io/docs/guides/auth.html) with proper syntax for other languages. - -#### Working with Host headers that include the port - -Some gRPC clients automatically include the port in the Host header. This is a problem when using TLS because the certificate will match `myurl.com` but the Host header will be `myurl.com:443`, resulting in the error `rpc error: code = Unimplemented desc =`. If you run into this issue, there are two ways to solve it depending on your use case, both using the Module resource. - -The first is to set the `strip_matching_host_port` [property](../../topics/running/ambassador#strip-matching-host-port) to `true`. However, this only works if the port in the header matches the port that Envoy listens on (8443 by default). In the default installation of $productName$, the public port is 443, which then maps internally to 8443, so this only works for custom installations where the public service port matches the port in the Listener resource. - -The second solution is to use the following [Lua script](../../topics/running/ambassador#lua-scripts), which always strips the port: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador - namespace: ambassador -spec: - config: - lua_scripts: | - function envoy_on_request(request_handle) - local authority = request_handle:headers():get(":authority") - if(string.find(authority, ":") ~= nil) - then - local authority_index = string.find(authority, ":") - local stripped_authority = string.sub(authority, 1, authority_index - 1) - request_handle:headers():replace(":authority", stripped_authority) - end - end -``` - -#### Originating TLS with gRPC service - -![](../images/gRPC-TLS-Originate.png) - -$productName$ can originate TLS with your gRPC service so the entire RPC channel is encrypted. To configure this, first get some TLS certificates and configure the server to open a secure channel with them. Using self-signed certs this can be done with OpenSSL and adding a couple of lines to the server code. - -```diff -def serve(): - server = grpc.server(futures.ThreadPoolExecutor(max_workers=10)) -+ with open('certs/server.key', 'rb') as f: -+ private_key = f.read() -+ with open('certs/server.crt', 'rb') as f: -+ cert_chain = f.read() -+ server_creds = grpc.ssl_server_credentials( ( (private_key, cert_chain), ) ) - helloworld_pb2_grpc.add_GreeterServicer_to_server(Greeter(), server) -- server.add_insecure_port('[::]:50052') -+ server.add_secure_port('[::]:50052', server_creds) - server.start() -``` - -Rebuild your docker container **making sure the certificates are included** and follow the same steps of testing and deploying to Kubernetes. You will need to make a small change to the client code to test locally. - -```diff -- with grpc.insecure_channel(‘localhost:$PORT’) as channel: -+ with grpc.secure_channel(‘localhost:$PORT’, grpc.ssl_channel_credentials(open('certs/server.crt', 'rb').read())) as channel: - stub = helloworld_pb2_grpc.GreeterStub(channel) - response = stub.SayHello(helloworld_pb2.HelloRequest(name='you')) - print("Greeter client received: " + response.message) -``` - -Once deployed we will need to tell $productName$ to originate TLS to the application. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py-tls -spec: - hostname: "*" - grpc: True - tls: upstream - prefix: /hello.Greeter/ - rewrite: /hello.Greeter/ - service: https://grpc-py - ---- -apiVersion: v1 -kind: Service -metadata: - labels: - service: grpc-py - name: grpc-py -spec: - type: ClusterIP - ports: - - name: grpc-greet - port: 443 - targetPort: grpc-api - selector: - service: grpc-py -``` - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: upstream -spec: - alpn_protocols: h2 - secret: ambassador-cert -``` - -We need to tell $productName$ to route to the `service:` over https and have the service listen on `443`. We also need to tell $productName$ to use ALPN protocols when originating TLS with the application, the same way we did with TLS termination. This is done by setting `alpn_protocols: ["h2"]` in a `TLSContext` telling the service to use that tls-context in the mapping by setting `tls: upstream`. - -Refer to the [TLS document](../../topics/running/tls/origination#advanced-configuration-using-a-tlscontext) for more information on TLS origination. - -### gRPC headers - -gRPC services use [HTTP/2 headers](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md). This means that some header-based routing rules will need to be rewritten to support HTTP/2 headers. For example, `host: subdomain.host.com` needs to be rewritten using the `headers: ` attribute with the `:authority` header: - -``` -headers: - :authority: subdomain.host.com -``` - -## Note - -### Ingress controllers - -Some [Kubernetes ingress controllers](https://kubernetes.io/docs/concepts/services-networking/ingress/) do not support HTTP/2 fully. As a result, if you are running $productName$ with an ingress controller in front, you may find that gRPC requests fail even with correct $productName$ configuration. - -A simple way around this is to use $productName$ with a `LoadBalancer` service, rather than an Ingress controller. You can also consider using [$productName$ as your Ingress Controller](../../topics/running/ingress-controller). - -### Mappings with hosts - -As with any `Mapping`, your gRPC service's `Mapping` may include a `host`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: grpc-py -spec: - hostname: "*" - grpc: true - prefix: /helloworld.Greeter/ - rewrite: /helloworld.Greeter/ - service: grpc-example - host: api.example.com -``` - -Some gRPC client libraries produce requests where the `host` or `:authority` header includes the port number. For example, a request to the above service might include `host: api.example.com:443` instead of just `host: api.example.com`. To avoid having $productName$ return a 404 (not found) response to these requests due to the mismatched host, you may want to set `strip_matching_host_port` in the [Ambassador module](../../topics/running/ambassador#strip-matching-host-port). - -Alternately, you may find it cleaner to make sure your gRPC client does not include the port in the `host` header. Here is an example using gRPC/Go. - -```go -hostname := "api.example.com" -port := "443" -config := &tls.Config{ServerName: hostname} -creds := credentials.NewTLS(config) -opts := []grpc.DialOption{ - grpc.WithTransportCredentials(creds), -// ... -} -conn, err := grpc.Dial(hostname+":"+port, opts...) -// ... -``` - -## gRPC-Web - -$productName$ also supports the [gRPC-Web](../../topics/running/ambassador#grpc) protocol for browser-based gRPC applications. diff --git a/content/en/docs/pre-release/howtos/http3-aks.md b/content/en/docs/pre-release/howtos/http3-aks.md deleted file mode 100644 index 2f9be012..00000000 --- a/content/en/docs/pre-release/howtos/http3-aks.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "$productName$ - HTTP/3 support for Azure Kubernetes Service (AKS)" -description: "How to configure HTTP/3 support for Azure Kubernetes Service (AKS). This guide shows how to setup the LoadBalancer service for AKS to support both TCP and UDP communications." ---- - -# Azure Kubernetes Service Engine HTTP/3 configuration - -This guide shows how to setup HTTP/3 support for Azure Kubernetes Service (AKS). The instructions provided in this page are a continuation of the [HTTP/3 in $productName$](../../topics/running/http3) documentation. - -## Configuring an external load balancer for AKS - -To configure an external load balancer for AKS, you need to: - -1. Reserve a public static IP address. -2. Create two `LoadBalancer` services, one for TCP and one for UDP. -3. Assign the public static IP address to the `loadBalancerIP` field. - -An example of the two load balancer services described above looks as follows: - -```yaml -# selectors and labels removed for clarity -apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$ - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - --- - apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$-udp - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http3 - port: 443 # Default support for HTTP/3 requires you to use 443 for the external client-facing port. - targetPort: 8443 - protocol: UDP - -``` - -In the above example, AKS generates two `LoadBalancer` services, one for UDP and the other for TCP. - - -You should verify that the Managed Identity or Serivce Principal has permissions to assign the IP address to the newly created LoadBalancer services. Refer to the Azure Docs - Managed Identity for more information. - diff --git a/content/en/docs/pre-release/howtos/http3-eks.md b/content/en/docs/pre-release/howtos/http3-eks.md deleted file mode 100644 index d09a1af5..00000000 --- a/content/en/docs/pre-release/howtos/http3-eks.md +++ /dev/null @@ -1,252 +0,0 @@ ---- -title: "HTTP/3 with Amazon Elastic Kubernetes Service (EKS) | $productName$" -description: "How to configure HTTP/3 support for Amazon Elastic Kubernetes Service (EKS). This guide shows how to setup the LoadBalancer service for EKS to support both TCP and UDP communications." ---- - -# Amazon Elastic Kubernetes Service HTTP/3 configuration - -This guide shows how to setup HTTP/3 support for Amazon Elastic Kubernetes Service (EKS) The instructions provided in this page are a continuation of the [HTTP/3 in $productName$](../../topics/running/http3) documentation. - -## Create a network load balancer (NLB) - - The virtual private cloud (VPC) for your load balancer needs one public subnet in each availability zone where you have targets. - - ```shell - SUBNET_IDS=( ) - - aws elbv2 create-load-balancer \ - --name ${CLUSTER_NAME}-nlb \ - --type network \ - --subnets ${SUBNET_IDS} - ``` - -## Create a NodePort service - -Now create a `NodePort` service for $productName$ installation with two entries. Use `port: 443` to include support for both TCP and UDP traffic. - ```yaml - # Selectors and labels removed for clarity. - apiVersion: v1 - kind: Service - metadata: - name: $productDeploymentName$-http3 - namespace: $productNamespace$ - spec: - type: NodePort - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - nodePort: 30080 - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - nodePort: 30443 - - name: http3 - port: 443 - targetPort: 8443 - protocol: UDP - nodePort: 30443 - ``` - -## Create target groups - -Run the following command with the variables for your VPC ID and cluster name: - - ```shell - VPC_ID= - CLUSTER_NAME= - - aws elbv2 create-target-group --name ${CLUSTER_NAME}-tcp-tg \ - --protocol TCP --port 30080 --vpc-id ${VPC_ID} \ - --health-check-protocol TCP \ - --health-check-port 30080 \ - --target-type instance - - aws elbv2 create-target-group --name ${CLUSTER_NAME}-tcp-udp-tg \ - --protocol TCP_UDP --port 30443 --vpc-id ${VPC_ID} \ - --health-check-protocol TCP \ - --health-check-port 30443 \ - --target-type instance - ``` - -## Register your instances - -Next, register your cluster's instance with the the instance IDs and Amazon Resource Names (ARN). - -To get your cluster's instance IDs, enter the following command: - ```shell - aws ec2 describe-instances \ - --filters Name=tag:eks:cluster-name,Values=${CLUSTER_NAME} \ - --output text - --query 'Reservations[*].Instances[*].InstanceId' \ - ``` - -To get your ARNs, enter the following command: - ```shell - TCP_TG_NAME=${CLUSTER_NAME}-tcp-tg-name - TCP_UDP_TG_NAME=${CLUSTER_NAME}-tcp-udp-tg-name - - aws elbv2 describe-target-groups \ - --query 'TargetGroups[?TargetGroupName==`'${TCP_TG_NAME}'`].TargetGroupArn' \ - --output text - aws elbv2 describe-target-groups \ - --query 'TargetGroups[?TargetGroupName==`'${TCP_UDP_TG_NAME}'`]. TargetGroupArn' \ - --output text - ``` - -Register the instances with the target groups and load balancer using the instance IDs and ARNs you retrieved. - ```shell - INSTANCE_IDS=( ) - REGION= - TG_NAME= - TCP_TG_ARN=arn:aws:elasticloadbalancing:${REGION}:079.....:targetgroup/${TG_NAME}/... - TCP_UDP_TG_ARN=arn:aws:elasticloadbalancing:${REGION}:079.....:targetgroup/${TG_NAME}/... - - aws elbv2 register-targets --target-group-arn ${TCP_TG_ARN} --targets ${INSTANCE_IDS} - aws elbv2 register-targets --target-group-arn ${TCP_UDP_TG_ARN} --targets ${INSTANCE_IDS} - ``` - -## Create listeners in AWS. - -Register your cluster's instance with the instance IDs and ARNs. - -To get the load balancer's ARN, enter the following command: - ```shell - aws elbv2 describe-load-balancers --name ${CLUSTER_NAME}-nlb \ - --query 'LoadBalancers[0].LoadBalancerArn' \ - --output text - ``` - -Create a TCP listener on port 80 that that forwards to the TargetGroup {TCP_TG_ARN}. - ```shell - aws elbv2 create-listener --load-balancer-arn ${LB_ARN} \ - --protocol TCP --port 80 \ - --default-actions Type=forward,TargetGroupArn=${TCP_TG_ARN} - ``` - - Create a TCP_UDP listener on port 443 that forwards to the TargetGroup {TCP_UDP_TG_ARN}. - ```shell - aws elbv2 create-listener --load-balancer-arn ${LB_ARN} \ - --protocol TCP_UDP --port 443 \ - --default-actions Type=forward,TargetGroupArn=${TCP_UDP_TG_ARN} - ``` - -## Update the security groups - -Now you need to update your security groups to receive traffic. This security group covers all node groups attached to the EKS cluster: - ```shell - aws eks describe-cluster --name ${CLUSTER_NAME} | grep clusterSecurityGroupId - ``` - -Now authorize the cluster security group to allow internet traffic: - ```shell - for x in ${CLUSTER_SG}; do \ - aws ec2 authorize-security-group-ingress --group-id $$x --protocol tcp --port 30080 --cidr 0.0.0.0/0; \ - aws ec2 authorize-security-group-ingress --group-id $$x --protocol tcp --port 30443 --cidr 0.0.0.0/0; \ - aws ec2 authorize-security-group-ingress --group-id $$x --protocol udp --port 30443 --cidr 0.0.0.0/0; \ - done - ``` - -## Get the DNS name for the load balancers - -Enter the following command to get the DNS name for your load balancers and create a CNAME record at your domain provider: - ```shell - aws elbv2 describe-load-balancers --name ${CLUSTER_NAME}-nlb \ - --query 'LoadBalancers[0].DNSName' \ - --output text - ``` - -## Create Listener resources - -Now you need to create the `Listener` resources for $productName$. The first `Listener` in the example below handles traffic for HTTP/1.1 and HTTP/2, while the second `Listener` handles all HTTP/3 traffic. - - ```yaml - kubectl apply -f - < - acmeProvider: - authority: none - tlsSecret: - name: tls-cert # The QUIC network protocol requires TLS with a valid certificate - tls: - min_tls_version: v1.3 - max_tls_version: v1.3 - alpn_protocols: h2,http/1.1 - EOF - ``` - -## Apply the quote service and a Mapping to test the HTTP/3 configuration. - -Finally, apply the quote service to a $productName$ `Mapping`. - - ```shell - kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$version$/quickstart/qotm.yaml - kubectl apply -f - </backend/ - ``` -Your domain now shows that it is being served with HTTP/3. diff --git a/content/en/docs/pre-release/howtos/http3-gke.md b/content/en/docs/pre-release/howtos/http3-gke.md deleted file mode 100644 index 677e89e3..00000000 --- a/content/en/docs/pre-release/howtos/http3-gke.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: "$productName$ - HTTP/3 support for Google Kubernetes Engine (GKE)" -description: "How to configure HTTP/3 support for Google Kubernetes Engine (GKE). This guide shows how to setup the LoadBalancer service for GKE to support both TCP and UDP communications." ---- - -# Google Kubernetes Service Engine HTTP/3 configuration - -This guide shows how to setup HTTP/3 support for Google Kubernetes Engine (GKE). The instructions provided in this page are a continuation of the [HTTP/3 in $productName$](../../topics/running/http3) documentation. - -## Configuring an external load balancer for GKE - -Currently, GKE only supports adding feature flags to `alpha` clusters, and doesn't support the creation of mixed protocol services of type `LoadBalancer`. To configure an external load balancer for GKE, you need to: - -1. Reserve a public static IP address. -2. Create two `LoadBalancer` services, one for TCP and one for UDP. -3. Assign the public static IP address to the `loadBalancerIP` field. - -An example of the two load balancer services described above looks as follows: - -```yaml -# selectors and labels removed for clarity -apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$ - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - --- - apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$-udp - namespace: $productNamespace$ -spec: - type: LoadBalancer - loadBalancerIP: xx.xx.xx.xx # Enter your public static IP address here. - ports: - - name: http3 - port: 443 # Default support for HTTP/3 requires you to use 443 for the external client-facing port. - targetPort: 8443 - protocol: UDP - -``` - -In the above example, GKE generates two `LoadBalancer` services, one for UDP and the other for TCP. diff --git a/content/en/docs/pre-release/howtos/index.md b/content/en/docs/pre-release/howtos/index.md deleted file mode 100644 index f16cdd46..00000000 --- a/content/en/docs/pre-release/howtos/index.md +++ /dev/null @@ -1,25 +0,0 @@ -# "How-to" guides - -These guides are designed to help users quickly accomplish common tasks. The guides assume a certain level of understanding of $productName$. Many of these guides are contributed by third parties; we welcome contributions via Pull Request at https://github.com/emissary-ingress/emissary. - -* Integrating with Service Mesh. $productName$ natively integrates with many service meshes. - * [HashiCorp Consul](consul) - * [Istio](istio) - * [Linkerd](linkerd2) -* Distributed tracing. $productName$ natively supports a number of distributed tracing systems to enable developers to visualize request flow in microservice and service-oriented architectures. - * [Datadog](tracing-datadog) - * [Zipkin](tracing-zipkin) -* Monitoring. $productName$ integrates with a number of different monitoring/metrics providers. - * [Prometheus](prometheus) -* [Developing Custom Filters](filter-dev-guide) -* Frameworks and Protocols. $productName$ supports a wide range of protocols and cloud-native frameworks. - * [gRPC](grpc) - * [Knative Serverless Framework](knative) - * [WebSockets](websockets) -* Security. $productName$ supports a number of strategies for securing Kubernetes services. - * [Protecting the Diagnostics Interface](protecting-diag-access) - * [HTTPS and TLS termination](tls-termination) - * [Certificate Manager](cert-manager) can be used to automatically obtain and renew TLS certificates; $AESproductName$ natively integrates this functionality. - * [Client Certificate Validation](client-cert-validation) - * [Basic Authentication](basic-auth) is a tutorial on how to use the external authentication API to code your own authentication service. - * [Basic Rate Limiting](rate-limiting-tutorial) diff --git a/content/en/docs/pre-release/howtos/istio.md b/content/en/docs/pre-release/howtos/istio.md deleted file mode 100644 index e26571b7..00000000 --- a/content/en/docs/pre-release/howtos/istio.md +++ /dev/null @@ -1,445 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Istio integration - -$productName$ and Istio: Edge Proxy and Service Mesh together in one. $productName$ is deployed at the edge of your network and routes incoming traffic to your internal services (aka "north-south" traffic). [Istio](https://istio.io/) is a service mesh for microservices, and is designed to add application-level Layer (L7) observability, routing, and resilience to service-to-service traffic (aka "east-west" traffic). Both Istio and $productName$ are built using [Envoy](https://www.envoyproxy.io). - -$productName$ and Istio can be deployed together on Kubernetes. In this configuration, $productName$ manages -traditional edge functions such as authentication, TLS termination, and edge routing. Istio mediates communication -from $productName$ to services, and communication between services. - -This allows the operator to have the best of both worlds: a high performance, modern edge service ($productName$) combined with a state-of-the-art service mesh (Istio). While Istio has introduced a [Gateway](https://istio.io/latest/docs/tasks/traffic-management/ingress/ingress-control/) abstraction, $productName$ still has a much broader feature set for edge routing than Istio. For more on this topic, see our blog post on [API Gateway vs Service Mesh](https://blog.getambassador.io/api-gateway-vs-service-mesh-104c01fa4784). - -This guide explains how to take advantage of both $productName$ and Istio to have complete control and observability over how requests are made in your cluster: - -- [Install Istio](#install-istio) and configure auto-injection -- [Install $productName$ with Istio integration](#install-edge) -- [Configure an mTLS `TLSContext`](#configure-an-mtls-tlscontext) -- [Route to services using mTLS](#route-to-services-using-mtls) - -If desired, you may also - -- [Enable strict mTLS](#enable-strict-mtls) -- [Configure Prometheus metrics collection](#configure-prometheus-metrics-collection) -- [Configure Istio distributed tracing](#configure-istio-distributed-tracing) - -To follow this guide, you need: - -- A Kubernetes cluster version 1.15 and above -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- Istio version 1.10 or higher - -## Install Istio - -Start by [installing Istio](https://istio.io/docs/setup/getting-started/). Any supported installation method for -Istio will work for use with $productName$. - -### Configure Istio Auto-Injection - -Istio functions by supplying a sidecar container running Envoy with every service in the mesh (including -$productName$). The sidecar is what enforces Istio policies for traffic to and from the service, notably -including mTLS encryption and certificate handling. As such, it is very important that the sidecar be -correctly supplied for every service in the mesh! - -While it is possible to manage sidecars by hand, it is far easier to allow Istio to automatically inject -the sidecar as necessary. To do this, set the `istio-injection` label on each Kubernetes Namespace for -which you want auto-injection: - -```yaml -kubectl label namespace $namespace istio-injection=enabled --overwrite -``` - - - The following example uses the `istio-injection` label to arrange for auto-injection in the - `$productNamespace$` Namespace below. You can manage sidecar injection by hand if you wish; what - is critical is that every service that participates in the Istio mesh have the Istio - sidecar. - - -## Install $productName$ with Istio Integration - -Properly integrating $productName$ with Istio provides support for: - -* [Mutual TLS (mTLS)](../../topics/running/tls/mtls/), with certificates managed by Istio, to allow end-to-end encryption -for east-west traffic; -* Automatic generation of Prometheus metrics for services; and -* Istio distributed tracing for end-to-end observability. - -The simplest way to enable everything is to install $productName$ using [Helm](https://helm.sh), though -you can use manual installation with YAML if you wish. - -### Installation with Helm (Recommended) - -To install with Helm, write the following YAML to a file called `istio-integration.yaml`: - -```yaml -# Listeners are required in $productName$ 2.0. -# This will create the two default Listeners for HTTP on port 8080 and HTTPS on port 8443. -createDefaultListeners: true - -# These are annotations that will be added to the $productName$ pods. -podAnnotations: - # These first two annotations tell Istio not to try to do port management for the - # $productName$ pod itself. Though these annotations are placed on the $productName$ - # pods, they are interpreted by Istio. - traffic.sidecar.istio.io/includeInboundPorts: "" # do not intercept any inbound ports - traffic.sidecar.istio.io/includeOutboundIPRanges: "" # do not intercept any outbound traffic - - # We use proxy.istio.io/config to tell the Istio proxy to write newly-generated mTLS certificates - # into /etc/istio-certs, which will be mounted below. Though this annotation is placed on the - # $productName$ pods, it is interpreted by Istio. - proxy.istio.io/config: | - proxyMetadata: - OUTPUT_CERTS: /etc/istio-certs - - # We use sidecar.istio.io/userVolumeMount to tell the Istio sidecars to mount the istio-certs - # volume at /etc/istio-certs, allowing the sidecars to see the generated certificates. Though - # this annotation is placed on the $productName$ pods, it is interpreted by Istio. - sidecar.istio.io/userVolumeMount: '[{"name": "istio-certs", "mountPath": "/etc/istio-certs"}]' - -# We define a single storage volume called "istio-certs". It starts out empty, and Istio -# uses it to communicate mTLS certs between the Istio proxy and the Istio sidecars (see the -# annotations above). -volumes: - - emptyDir: - medium: Memory - name: istio-certs - -# We also tell $productName$ to mount the "istio-certs" volume at /etc/istio-certs in the -# $productName$ pod. This gives $productName$ access to the mTLS certificates, too. -volumeMounts: - - name: istio-certs - mountPath: /etc/istio-certs/ - readOnly: true - -# Finally, we need to set some environment variables for $productName$. -env: - # AMBASSADOR_ISTIO_SECRET_DIR tells $productName$ to look for Istio mTLS certs, and to - # make them available as a secret named "istio-certs". - AMBASSADOR_ISTIO_SECRET_DIR: "/etc/istio-certs" - - # AMBASSADOR_ENVOY_BASE_ID is set to prevent collisions with the Istio sidecar's Envoy, - # which runs with base-id 0. - AMBASSADOR_ENVOY_BASE_ID: "1" -``` - -To install $productName$ with Helm, use these values to configure Istio integration: - -1. Create the `$productNamespace$` Namespace: - - ```yaml - kubectl create namespace $productNamespace$ - ``` - -2. Enable Istio auto-injection for it: - - ```yaml - kubectl label namespace $productNamespace$ istio-injection=enabled --overwrite - ``` - -3. Make sure the Helm repo is configured: - - ```bash - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - -4. Use Helm to install $productName$ in $productNamespace$: - - ```bash - helm install $productHelmName$ --namespace $productNamespace$ -f istio-integration.yaml datawire/$productHelmName$ && \ - kubectl -n $productNamespace$ wait --for condition=available --timeout=90s deploy -lapp.kubernetes.io/instance=$productDeploymentName$ - ``` - -### Installation Using YAML - -To install using YAML files, you need to manually incorporate the contents of the `istio-integration.yaml` -file shown above into your deployment YAML: - -* `pod-annotations` should be configured as Kubernetes `annotations` on the $productName$ Pods; -* `volumes`, `volumeMounts`, and `env` contents should be included in the $productDeploymentName$ Deployment; and -* you must also label the $productNamespace$ Namespace for auto-injection as described above. - -### Configuring an Existing Installation - -If you have already installed $productName$ and want to enable Istio: - -1. Install Istio. -2. Label the $productNamespace$ namespace for Istio auto-injection, as above. -2. Edit the $productName$ Deployments to contain the `annotations`, `volumes`, `volumeMounts`, and `env` elements - shown above. - * If you installed with Helm, you can use `helm upgrade` with `-f istio-integration.yaml` to modify the - installation for you. -3. Restart the $productName$ pods. - -## Configure an mTLS `TLSContext` - -After configuring $productName$ for Istio integration, the Istio mTLS certificates are available within -$productName$: - -- Both the `istio-proxy` sidecar and $productName$ mount the `istio-certs` volume at `/etc/istio-certs`. -- The `istio-proxy` sidecar saves the mTLS certificates into `/etc/istio-certs` (per the `OUTPUT_CERTS` - environment variable). -- $productName$ reads the mTLS certificates from `/etc/istio-certs` (per the `AMBASSADOR_ISTIO_SECRET_DIR` - environment variable) and creates a Secret named `istio-certs`. - - - At present, the Secret name istio-certs cannot be changed. - - -To make use of the `istio-certs` Secret, create a `TLSContext` referencing it: - - ```shell - $ kubectl apply -f - < - You must either explicitly specify port 80 in your 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 - <This guide applies to $OSSproductName$. It will not work correctly -on $AESproductName$. - -$productName$ can validate incoming requests before routing them to a backing service. In this tutorial, we'll configure $productName$ to use a simple third party rate limit service. (If you don't want to implement your own rate limiting service, $AESproductName$ integrates a [powerful, flexible rate limiting service](/docs/edge-stack/latest/topics/using/rate-limits/rate-limits/).) - -## Before you get started - -This tutorial assumes you have already followed the $productName$ [Installation](../../topics/install/) and [Quickstart Tutorial](../../tutorials/quickstart-demo) guides. If you haven't done that already, you should do so now. - -Once completed, you'll have a Kubernetes cluster running $productName$ and the Quote service. Let's walk through adding rate limiting to this setup. - -## 1. Deploy the rate limit service - -$productName$ delegates the actual rate limit logic to a third party service. We've written a [simple rate limit service](https://github.com/emissary-ingress/ratelimit-example) that: - -- listens for requests on port 5000; -- handles gRPC `shouldRateLimit` requests; -- allows requests with the `x-emissary-test-allow: "true"` header; and -- marks all other requests as `OVER_LIMIT`; - -Here's the YAML we'll start with: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: RateLimitService -metadata: - name: ratelimit - namespace: default -spec: - service: "ratelimit-example.default:5000" - protocol_version: v3 - domain: emissary - failure_mode_deny: true ---- -apiVersion: v1 -kind: Service -metadata: - name: ratelimit-example -spec: - selector: - app: ratelimit-example - ports: - - name: http - port: 5000 - targetPort: http ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: ratelimit-example -spec: - replicas: 1 - selector: - matchLabels: - app: ratelimit-example - template: - metadata: - labels: - app: ratelimit-example - spec: - containers: - - name: ratelimit-example - image: docker.io/emissaryingress/ratelimit-example:v3 - imagePullPolicy: Always - ports: - - name: http - containerPort: 5000 - resources: - limits: - memory: "64Mi" - cpu: "100m" -``` - -Once this configuration is applied Kubernetes will startup the example ratelimit service and $productName$ will be configured to use the rate limit service. The `RateLimitService` configuration tells $productName$ to: - -- Send `ShouldRateLimit` check request to `ratelimit-example.default:5000` -- Configure Envoy to talk with the example ratelimit service using transport protocol `v3` (*only supported version*) -- Set the labels `domain` to `emissary` (*labels discussed below*) - -If $productName$ cannot contact the rate limit service, it can either fail open or closed. The default is to fail open but in the example `RateLimitService` above we toggled it via the `failure_mode_deny: true` setting. - -## 2. Configure $productName$ Mappings - -$productName$ only validates requests on `Mapping`s which set labels to use for rate limiting, so you'll need to apply `labels` to your `Mapping`s to enable rate limiting. For more information -on the labelling process, see the [Rate Limits configuration documentation](../../topics/using/rate-limits/). - - - These labels require Mapping resources with apiVersion getambassador.io/v2 or newer — if you're updating an old installation, check the - apiVersion! - - -Labels are added to a `Mapping` using the `labels` field and `domain` configured in the `RateLimitService`. For example: - -```yaml -labels: - emissary: - - request_label_group: - - x-emissary-test-allow: - request_headers: - key: "x-emissary-test-allow" - header_name: "x-emissary-test-allow" -``` - -If we were to apply it the `Mapping` definition for the `quote-backend` service outlined in the quick-start then it would look like this: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: "*" - prefix: /backend/ - service: quote - labels: - emissary: - - request_label_group: - - x-emissary-test-allow: - request_headers: - key: "x-emissary-test-allow" - header_name: "x-emissary-test-allow" -``` - -Note that the `key` could be anything you like, but our example rate limiting service expects it to match the name of the header. Also note that since our `RateLimitService` expects to use labels in the -`emissary` domain, our `Mapping` must match. - -## 2. Test rate limiting - -If we `curl` to a rate-limited URL: - -```shell -curl -i -H "x-emissary-test-allow: probably" http://$LB_ENDPOINT/backend/ -``` - -We get a `429` status code, since we are being rate limited. - -```shell -HTTP/1.1 429 Too Many Requests -content-type: text/html; charset=utf-8 -content-length: 0 -``` - -If we set the correct header value to the service request, we will get a quote successfully: - -```shell -$ curl -i -H "x-emissary-test-allow: true" http://$LB_ENDPOINT/backend/ - -TCP_NODELAY set -* Connected to 35.196.173.175 (35.196.173.175) port 80 (#0) -> GET /backed HTTP/1.1 -> Host: 35.196.173.175 -> User-Agent: curl/7.54.0 -> Accept: */* -> -< HTTP/1.1 200 OK -< content-type: application/json -< date: Thu, 23 May 2019 15:25:06 GMT -< content-length: 172 -< x-envoy-upstream-service-time: 0 -< server: envoy -< -{ - "server": "humble-blueberry-o2v493st", - "quote": "Nihilism gambles with lives, happiness, and even destiny itself!", - "time": "2019-05-23T15:25:06.544417902Z" -* Connection #0 to host 54.165.128.189 left intact -} -``` - -## More - -For more details about configuring the external rate limit service, read the [rate limit documentation](../../topics/using/rate-limits/). diff --git a/content/en/docs/pre-release/howtos/route.md b/content/en/docs/pre-release/howtos/route.md deleted file mode 100644 index 6a399ec5..00000000 --- a/content/en/docs/pre-release/howtos/route.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -description: "$productName$ uses the Mapping resource to map a resource, like a URL prefix, to a Kubernetes service or web service." ---- - -import Alert from '@material-ui/lab/Alert'; - -# Get traffic from the edge - -
-

Contents

- -* [Examples](#examples) -* [Applying a Mapping Resource](#applying-a-mapping-resource) -* [Resources](#resources) -* [Services](#services) -* [Extending Mappings](#extending-mappings) -* [Best Practices](#best-practices) -* [What's next?](#img-classos-logo-srcimageslogopng-whats-next) - -
- -The core $productName$ resource used to manage cluster ingress is the `Mapping` resource. - -**A `Mapping` resource routes a URL path (or prefix) to a service (either a Kubernetes service or other web service).** - - - Remember that Listener and Host resources are  - required for a functioning $productName$ installation that can route traffic!
- Learn more about Listener.
- Learn more about Host. - - -## Examples - -This `Mapping` would route requests to `https:///webapp/` to the `webapp-svc` Service. **This is not a -complete example on its own; see below.** - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: webapp-mapping -spec: - prefix: /webapp/ - service: webapp-svc -``` - -| Name | Type | Description | -| :--- | :--- | :--- | -| `metadata.name` | String | Identifies the Mapping. | -| `spec.prefix` | String | The URL prefix identifying your resource. [See below](#resources) on how $productName$ handles resources. | -| `spec.service` | String | The service handling the resource. If a Kubernetes service, it must include the namespace (in the format `service.namespace`) if the service is in a different namespace than $productName$. [See below](#services) on service name formatting.| - -Here's another example using a web service that maps requests to `/httpbin/` to `http://httpbin.org` (again, **this is not a -complete example on its own; see below**): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin-mapping -spec: - prefix: /httpbin/ - service: http://httpbin.org - hostname: '*' -``` - -### Complete example configuration - -For demonstration purposes, here's a possible way of combining a `Listener`, a `Host`, and both `Mapping`s above that is complete and functional: - -- it will accept HTTP or HTTPS on port 8443; -- $productName$ is terminating TLS; -- HTTPS to `foo.example.com` will be routed as above; -- HTTP to `foo.example.com` will be redirected to HTTPS; -- HTTP or HTTPS to other hostnames will be rejected; and -- the associations between the `Listener`, the `Host`, and the `Mappings` use Kubernetes `label`s. - -```yaml ---- -apiVersion: v1 -kind: Secret -type: kubernetes.io/tls -metadata: - name: foo-example-secret -data: - tls.crt: -certificate PEM- - tls.key: -secret key PEM- ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: listener-8443 -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: - selector: - matchLabels: - exampleName: basic-https ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host - labels: - exampleName: basic-https -spec: - hostname: "foo.example.com" - tlsSecret: - name: foo-example-secret - selector: - matchLabels: - exampleName: basic-https ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: webapp-mapping - labels: - exampleName: basic-https -spec: - prefix: /webapp/ - service: webapp-svc - hostname: 'foo.example.com' ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin-mapping - labels: - exampleName: basic-https -spec: - prefix: /httpbin/ - service: http://httpbin.org - hostname: 'foo.example.com' - -``` - -Note the addition of `label`s and `selector`s to explicitly specify which resources should associate in this example. - - - Learn more about Listener.
- Learn more about Host. - - -## Applying a Mapping resource - -A Mapping resource can be managed using the same workflow as any other Kubernetes resources (like a Service or Deployment). For example, if the above Mapping is saved into a file called `httpbin-mapping.yaml`, the following command will apply the configuration directly to $productName$: - -``` -kubectl apply -f httpbin-mapping.yaml -``` - -For production use, best practice is to store the file in a version control system and apply the changes with a continuous deployment pipeline. The Ambassador Operating Model provides more detail. - -## Resources - -To $productName$, a resource is a group of one or more URLs that all share a common prefix in the URL path. For example, these URLs all share the `/resource1/` path prefix, so `/resource1/` can be considered a single resource: - -* `https://ambassador.example.com/resource1/foo` -* `https://ambassador.example.com/resource1/bar` -* `https://ambassador.example.com/resource1/baz/zing` - -On the other hand, these URLs share only the prefix `/` -- you _could_ tell $productName$ to treat them as a single resource, but it's probably not terribly useful. - -* `https://ambassador.example.com/resource1/foo` -* `https://ambassador.example.com/resource2/bar` -* `https://ambassador.example.com/resource3/baz/zing` - -Note that the length of the prefix doesn't matter; a prefix like `/v1/this/is/my/very/long/resource/name/` is valid. - -Also note that $productName$ does not actually require the prefix to start and end with `/` -- however, in practice, it's a good idea. Specifying a prefix of `/man` would match all of the following, which probably is not what was intended: - -* `https://ambassador.example.com/man/foo` -* `https://ambassador.example.com/mankind` -* `https://ambassador.example.com/man-it-is/really-hot-today` - -## Services - -$productName$ routes traffic to a service. A service is defined as `[scheme://]service[.namespace][:port]`. Everything except for the service is optional. - -- `scheme` can be either `http` or `https`; if not present, the default is `http`. -- `service` is the name of a service (typically the service name in Kubernetes or Consul); it is not allowed to contain the `.` character. -- `namespace` is the namespace in which the service is running. Starting with $productName$ 1.0.0, if not supplied, it defaults to the namespace in which the Mapping resource is defined. The default behavior can be configured using the [Module resource](../../topics/running/ambassador). When using a Consul resolver, `namespace` is not allowed. -- `port` is the port to which a request should be sent. If not specified, it defaults to `80` when the scheme is `http` or `443` when the scheme is `https`. Note that the [resolver](../../topics/running/resolvers) may return a port in which case the `port` setting is ignored. - -While using service.namespace.svc.cluster.local may work for Kubernetes resolvers, the preferred syntax is service.namespace. - - -## Extending Mappings - -Mapping resources support a rich set of annotations to customize the specific routing behavior. Here's an example service for implementing the [CQRS pattern](https://docs.microsoft.com/en-us/azure/architecture/patterns/cqrs) (using HTTP): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-get -spec: - prefix: /cqrs/ - method: GET - service: getcqrs - hostname: '*' ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-put -spec: - prefix: /cqrs/ - method: PUT - service: putcqrs - hostname: '*' -``` - -## Best Practices - -$productName$'s configuration is assembled from multiple YAML blocks which are managed by independent application teams. This implies that certain best practices should be followed. - -#### $productName$'s configuration should be under version control. - -While you can always read back the $productName$'s configuration from Kubernetes or its diagnostic service, the $productName$ will not do versioning for you. - -#### $productName$ tries to not start with a broken configuration, but it's not perfect. - -Gross errors will result in the $productName$ refusing to start, in which case `kubectl logs` will be helpful. However, it's always possible to map a resource to the wrong service, or use the wrong `rewrite` rules. $productName$ can't detect that on its own, although its [diagnostic service](../../topics/running/diagnostics/) can help you figure it out. - -#### Be careful of mapping collisions. - -If two different developers try to map `/myservice/` to something, this can lead to unexpected behavior. $productName$'s [canary deployment](../../topics/using/canary/) logic means that it's more likely that traffic will be split between them than that it will throw an error -- again, the diagnostic service can help you here. - -#### Unless specified, mapping attributes cannot be applied to any other resource type. - -## 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/content/en/docs/pre-release/howtos/tls-termination.md b/content/en/docs/pre-release/howtos/tls-termination.md deleted file mode 100644 index 2bbdf4c4..00000000 --- a/content/en/docs/pre-release/howtos/tls-termination.md +++ /dev/null @@ -1,192 +0,0 @@ -# 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/content/en/docs/pre-release/howtos/tracing-datadog.md b/content/en/docs/pre-release/howtos/tracing-datadog.md deleted file mode 100644 index d627e29f..00000000 --- a/content/en/docs/pre-release/howtos/tracing-datadog.md +++ /dev/null @@ -1,63 +0,0 @@ -# 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/content/en/docs/pre-release/howtos/tracing-lightstep.md b/content/en/docs/pre-release/howtos/tracing-lightstep.md deleted file mode 100644 index 30353e71..00000000 --- a/content/en/docs/pre-release/howtos/tracing-lightstep.md +++ /dev/null @@ -1,230 +0,0 @@ -# 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. - - - Please note that the 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. - - -## Before you get started - -This tutorial assumes you have already followed the $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. Setup Lightstep - -If you don't already have a Lightstep account be sure to create one [here](https://lightstep.com/). Then create a Project and be sure to create and save the Access Token information. You can find your Access Token information under the Project settings. - -## 2. Deploy the OpenTelemetry Collector - -The next step is to deploy the OpenTelemetry Collector. The purpose of the OpenTelemetry Collector is to receive the requested trace data and then export it to Lightstep. - -For the purposes of this tutorial, we are going to create and use the `monitoring` namespace. This can be done with the following command. - -```bash - kubectl create namespace monitoring -``` - -Next we are going to setup our configuration for the OpenTelemetry Collector. First, we use a Kubernetes secret to store our Lightstep Access Token that we saved in step one. It is important for us to encode the secret in Base64. How you want to do this securely is up to you, for the purposes of this tutorial we will use the online tool [Base64Encode.org](https://www.base64encode.org/). Once the secret is encoded, please apply the following YAML and be sure to update the value of the `lightstep_access_token` with your encoded token. - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: otel - namespace: monitoring -type: Opaque -data: - lightstep_access_token: YOUR_BASE64_ENCODED_TOKEN_HERE -``` - -Next, please add the following YAML to a file named `opentelemetry.yaml`. This configuration will create 3 resources. A ConfigMap that will store our configuration options, an OpenTelemetry Deployment that uses the [OpenTelemetry Collector Contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib) container image, and an associated Service for our Distributed Tracing. - -```yaml ---- ---- -apiVersion: v1 -kind: ConfigMap -metadata: - name: otel-collector-conf - namespace: monitoring - labels: - app: opentelemetry - component: otel-collector-conf -data: - otel-collector-config: | - receivers: - zipkin: {} - processors: - batch: - memory_limiter: - # Same as --mem-ballast-size-mib CLI argument - ballast_size_mib: 683 - # 80% of maximum memory up to 2G - limit_mib: 1500 - # 25% of limit up to 2G - spike_limit_mib: 512 - check_interval: 5s - queued_retry: - extensions: - health_check: {} - zpages: {} - exporters: - otlp: - endpoint: ingest.lightstep.com:443 - headers: {"lightstep-access-token":"${LIGHTSTEP_ACCESS_TOKEN}"} - service: - extensions: [health_check, zpages] - pipelines: - traces: - receivers: [zipkin] - processors: [memory_limiter, batch, queued_retry] - exporters: - - otlp ---- -apiVersion: v1 -kind: Service -metadata: - name: otel-collector - namespace: monitoring - labels: - app: opentelemetry - component: otel-collector -spec: - ports: - - name: otlp # Default endpoint for OpenTelemetry receiver. - port: 55680 - - name: zipkin # Default endpoint for Zipkin trace receiver. - port: 9411 - selector: - component: otel-collector ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: otel-collector - namespace: monitoring - labels: - app: opentelemetry - component: otel-collector -spec: - selector: - matchLabels: - app: opentelemetry - component: otel-collector - minReadySeconds: 5 - progressDeadlineSeconds: 120 - replicas: 1 - template: - metadata: - labels: - app: opentelemetry - component: otel-collector - spec: - containers: - - command: - - "/otelcontribcol" - - "--config=/conf/otel-collector-config.yaml" - - "--mem-ballast-size-mib=683" # Memory Ballast size should be max 1/3 to 1/2 of memory. - image: otel/opentelemetry-collector-contrib:0.11.0 - name: otel-collector - resources: - limits: - cpu: 1000m - memory: 2Gi - requests: - cpu: 200m - memory: 400Mi - ports: - - containerPort: 55680 # Default endpoint for OpenTelemetry receiver. - - containerPort: 9411 # Default endpoint for Zipkin receiver. - env: - - name: LIGHTSTEP_ACCESS_TOKEN - valueFrom: - secretKeyRef: - name: otel - key: lightstep_access_token - volumeMounts: - - name: otel-collector-config-vol - mountPath: /conf - livenessProbe: - httpGet: - path: / - port: 13133 - readinessProbe: - httpGet: - path: / - port: 13133 - volumes: - - configMap: - name: otel-collector-conf - items: - - key: otel-collector-config - path: otel-collector-config.yaml - name: otel-collector-config-vol -``` - -Be sure to apply this configuration with the following command: - -```bash - kubectl apply -f opentelemetry.yaml -``` - -At this point, the OpenTelemetry Collector should be setup properly and ready to send data to Lightstep. - -## 3. Configure the TracingService - -Now that the OpenTelemetry Collector is setup for collecting data, the next step will be for us to setup our [TracingService](../../topics/running/services/tracing-service). We will be using the Zipkin driver to send our request trace data to the OpenTelemetry Collector for Distributed Tracing. Please apply the following YAML. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TracingService -metadata: - name: tracing-zipkin - namespace: ambassador -spec: - service: otel-collector.monitoring:9411 - driver: zipkin -``` - -As a final step we want to restart $productName$ as this is necessary to add the distributed tracing headers. This command will restart all the Pods (assuming $productName$ is installed in the ambassador namespace): - -```bash - kubectl -n ambassador rollout restart deploy -``` - - - Restarting $productName$ is required after deploying a Tracing Service for changes to take effect. - - -## 4. Testing our Distributed Tracing - -Finally, we are going to test our Distributed Tracing. 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. - -```bash - curl -Li http://$LB_ENDPOINT/backend/ -``` - -At this point, we should be able to view and check our traces on the [Lightstep app](https://app.lightstep.com/). You can do so by clicking on the Explorer tab and searching for a trace. - -## Migrating from the Lightstep Tracing Driver - - - Please be sure to follow these steps prior to upgrading to $productName$ version 3.4.0. - - -As of $productName$ version 3.4.0, the Lightstep tracing driver will no longer be supported. This is due to the upgrade to Envoy version 1.24, where the team at LightStep has completely removed support for the LightStep Tracing driver in favor of using the OpenTelemetry Collector. In order to continue to use Lightstep to visualize our traces, we can follow similar steps to the above tutorial. - -First, make sure that the OpenTelemetry Collector is installed. This can be done by following the same commands as step 2 of this page. Please be sure to create/update the Kubernetes secret to include your Lightstep Access Token. - -Then, we simply need to edit our TracingService to point to the OpenTelemetry Collector (instead of the ingest endpoint of Lightstep) and to use the Zipkin driver. Please note that $productName$ can only support 1 TracingService per instance. Because of this, we must edit our previous TracingService rather than applying a second one. - -If you were using the Lightstep tracing driver, you may have your Lightstep Access Token information set in your TracingService config. Using a Kubernetes Secret, we no longer need to reference the token here. - -Once our TracingService configuration has been updated, a restart of $productName$ is necessary for Lightstep to recieve our Distributed Tracing information. This can be done with the following command: - -```bash - kubectl -n ambassador rollout restart deploy -``` diff --git a/content/en/docs/pre-release/howtos/tracing-zipkin.md b/content/en/docs/pre-release/howtos/tracing-zipkin.md deleted file mode 100644 index 37ddc902..00000000 --- a/content/en/docs/pre-release/howtos/tracing-zipkin.md +++ /dev/null @@ -1,129 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Distributed tracing with Zipkin - -In this tutorial, we'll configure $productName$ to initiate a trace on some sample requests, and use Zipkin 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. Deploy Zipkin - -In this tutorial, you will use a simple deployment of the open-source [Zipkin](https://github.com/openzipkin/zipkin/wiki) distributed tracing system to store and visualize $productName$-generated traces. The trace data will be stored in memory within the Zipkin container, and you will be able to explore the traces via the Zipkin web UI. - -First, add the following YAML to a file named `zipkin.yaml`. This configuration will create a Zipkin Deployment that uses the [openzipkin/zipkin](https://hub.docker.com/r/openzipkin/zipkin/) container image and also an associated Service. We will also include a `TracingService` that configures $productName$ to use the Zipkin service (running on the default port of 9411) to provide tracing support. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TracingService -metadata: - name: tracing -spec: - service: "zipkin:9411" - driver: zipkin - config: {} ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: zipkin -spec: - replicas: 1 - selector: - matchLabels: - app: zipkin - template: - metadata: - labels: - app: zipkin - spec: - containers: - - name: zipkin - image: openzipkin/zipkin - env: - # note: in-memory storage holds all data in memory, purging older data upon a span limit. - # you should use a proper storage in production environments - - name: STORAGE_TYPE - value: mem ---- -apiVersion: v1 -kind: Service -metadata: - labels: - name: zipkin - name: zipkin -spec: - ports: - - port: 9411 - targetPort: 9411 - selector: - app: zipkin -``` - -Next, deploy this configuration into your cluster: - -``` -$ kubectl apply -f zipkin.yaml -``` - -As a final step we want to restart $productName$ as this is necessary to add the tracing header. This command will restart all the Pods (assuming $productName$ is installed in the ambassador namespace): - -``` -$ kubectl -n ambassador rollout restart deploy -``` - - Restarting $productName$ is required after deploying a Tracing Service for changes to take effect. - - -## 2. 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/backend/ -``` - -## 3. Test traces - -To test things out, we'll need to access the Zipkin UI. If you're on Kubernetes, get the name of the Zipkin pod: - -``` -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -ambassador-5ffcfc798-c25dc 2/2 Running 0 1d -prometheus-prometheus-0 2/2 Running 0 113d -zipkin-868b97667c-58v4r 1/1 Running 0 2h -``` - -And then use `kubectl port-forward` to access the pod: - -``` -$ kubectl port-forward zipkin-868b97667c-58v4r 9411 -``` - -Open your web browser to `http://localhost:9411` for the Zipkin UI. - -If you're on `minikube` you can access the `NodePort` directly, and this ports number can be obtained via the `minikube services list` command. If you are using `Docker for Mac/Windows`, you can use the `kubectl get svc` command to get the same information. - -``` -$ minikube service list -|-------------|----------------------|-----------------------------| -| NAMESPACE | NAME | URL | -|-------------|----------------------|-----------------------------| -| default | ambassador-admin | http://192.168.99.107:30319 | -| default | ambassador | http://192.168.99.107:31893 | -| default | zipkin | http://192.168.99.107:31043 | -|-------------|----------------------|-----------------------------| -``` - -Open your web browser to the Zipkin dashboard `http://192.168.99.107:31043/zipkin/`. - -In the Zipkin UI, click on the "Find Traces" button to get a listing instrumented traces. Each of the traces that are displayed can be clicked on, which provides further information about each span and associated metadata. - -## Learn more - -For more details about configuring the external tracing service, read the documentation on [external tracing](../../topics/running/services/tracing-service). diff --git a/content/en/docs/pre-release/howtos/websockets.md b/content/en/docs/pre-release/howtos/websockets.md deleted file mode 100644 index 25cac7da..00000000 --- a/content/en/docs/pre-release/howtos/websockets.md +++ /dev/null @@ -1,43 +0,0 @@ -# WebSocket connections - -$productName$ makes it easy to access your services from outside your -application, and this includes services that use WebSockets. Only a -small amount of additional configuration is required, which is as -simple as telling the Mapping to allow "upgrading" from the HTTP protocol to -the "websocket" protocol: - -```yaml -allow_upgrade: -- websocket -``` - -## Example WebSocket service - -The example configuration below demonstrates the addition of the `allow_upgrade:` attribute to support websockets. The use of `use_websocket` is now deprecated. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: my-service-mapping -spec: - hostname: "*" - prefix: /my-service/ - service: my-service - allow_upgrade: - - websocket - ---- -kind: Service -apiVersion: v1 -metadata: - name: my-service -spec: - selector: - app: MyApp - ports: - - protocol: TCP - port: 80 - targetPort: 9376 -``` diff --git a/content/en/docs/pre-release/images/Auth0_JWT.png b/content/en/docs/pre-release/images/Auth0_JWT.png deleted file mode 100644 index e18155f5..00000000 Binary files a/content/en/docs/pre-release/images/Auth0_JWT.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/Auth0_domain_clientID.png b/content/en/docs/pre-release/images/Auth0_domain_clientID.png deleted file mode 100644 index a7f8edf6..00000000 Binary files a/content/en/docs/pre-release/images/Auth0_domain_clientID.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/Auth0_method_callback_origins.png b/content/en/docs/pre-release/images/Auth0_method_callback_origins.png deleted file mode 100644 index 8d31138e..00000000 Binary files a/content/en/docs/pre-release/images/Auth0_method_callback_origins.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/aes-success.png b/content/en/docs/pre-release/images/aes-success.png deleted file mode 100644 index 66f28d3f..00000000 Binary files a/content/en/docs/pre-release/images/aes-success.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/ambassador-arch.png b/content/en/docs/pre-release/images/ambassador-arch.png deleted file mode 100644 index 5a5cb652..00000000 Binary files a/content/en/docs/pre-release/images/ambassador-arch.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/ambassador-logo.svg b/content/en/docs/pre-release/images/ambassador-logo.svg deleted file mode 100644 index 1f0e06a8..00000000 --- a/content/en/docs/pre-release/images/ambassador-logo.svg +++ /dev/null @@ -1,49 +0,0 @@ - - - - ambassador logo@1x - Created with Sketch. - - - - - - - diff --git a/content/en/docs/pre-release/images/ambassador_oidc_flow.jpg b/content/en/docs/pre-release/images/ambassador_oidc_flow.jpg deleted file mode 100644 index 4f1c0c7e..00000000 Binary files a/content/en/docs/pre-release/images/ambassador_oidc_flow.jpg and /dev/null differ diff --git a/content/en/docs/pre-release/images/apple.png b/content/en/docs/pre-release/images/apple.png deleted file mode 100644 index 8b8277f1..00000000 Binary files a/content/en/docs/pre-release/images/apple.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/auth-flow.png b/content/en/docs/pre-release/images/auth-flow.png deleted file mode 100644 index e1ba4387..00000000 Binary files a/content/en/docs/pre-release/images/auth-flow.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/authentication-icon.svg b/content/en/docs/pre-release/images/authentication-icon.svg deleted file mode 100644 index 342e8a3d..00000000 --- a/content/en/docs/pre-release/images/authentication-icon.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_897228_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/pre-release/images/blackbird.png b/content/en/docs/pre-release/images/blackbird.png deleted file mode 100644 index 1f10e5cc..00000000 Binary files a/content/en/docs/pre-release/images/blackbird.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/canary-release-overview.png b/content/en/docs/pre-release/images/canary-release-overview.png deleted file mode 100644 index c683a23d..00000000 Binary files a/content/en/docs/pre-release/images/canary-release-overview.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/configure-icon.svg b/content/en/docs/pre-release/images/configure-icon.svg deleted file mode 100644 index 0f556840..00000000 --- a/content/en/docs/pre-release/images/configure-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_858572_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/pre-release/images/consul-ambassador.png b/content/en/docs/pre-release/images/consul-ambassador.png deleted file mode 100644 index c4911624..00000000 Binary files a/content/en/docs/pre-release/images/consul-ambassador.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/container-inner-dev-loop.png b/content/en/docs/pre-release/images/container-inner-dev-loop.png deleted file mode 100644 index 06586cd6..00000000 Binary files a/content/en/docs/pre-release/images/container-inner-dev-loop.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/datawire-logo.svg b/content/en/docs/pre-release/images/datawire-logo.svg deleted file mode 100644 index fb45872c..00000000 --- a/content/en/docs/pre-release/images/datawire-logo.svg +++ /dev/null @@ -1,27 +0,0 @@ - - - - Group 3 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - diff --git a/content/en/docs/pre-release/images/diagnostics-example.png b/content/en/docs/pre-release/images/diagnostics-example.png deleted file mode 100644 index 6c825b0c..00000000 Binary files a/content/en/docs/pre-release/images/diagnostics-example.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/diagnostics.png b/content/en/docs/pre-release/images/diagnostics.png deleted file mode 100644 index 29248703..00000000 Binary files a/content/en/docs/pre-release/images/diagnostics.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/docker-compose.png b/content/en/docs/pre-release/images/docker-compose.png deleted file mode 100644 index b8829521..00000000 Binary files a/content/en/docs/pre-release/images/docker-compose.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/docker.png b/content/en/docs/pre-release/images/docker.png deleted file mode 100644 index 1f35e5ea..00000000 Binary files a/content/en/docs/pre-release/images/docker.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/edge-stack-1.13.4.png b/content/en/docs/pre-release/images/edge-stack-1.13.4.png deleted file mode 100644 index 954ac1a9..00000000 Binary files a/content/en/docs/pre-release/images/edge-stack-1.13.4.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/edge-stack-1.13.7-json-logging.png b/content/en/docs/pre-release/images/edge-stack-1.13.7-json-logging.png deleted file mode 100644 index 4a47cbdf..00000000 Binary files a/content/en/docs/pre-release/images/edge-stack-1.13.7-json-logging.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/edge-stack-1.13.7-memory.png b/content/en/docs/pre-release/images/edge-stack-1.13.7-memory.png deleted file mode 100644 index 9c415ba3..00000000 Binary files a/content/en/docs/pre-release/images/edge-stack-1.13.7-memory.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/edge-stack-1.13.7-tcpmapping-consul.png b/content/en/docs/pre-release/images/edge-stack-1.13.7-tcpmapping-consul.png deleted file mode 100644 index c455a47f..00000000 Binary files a/content/en/docs/pre-release/images/edge-stack-1.13.7-tcpmapping-consul.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/edge-stack-1.13.8-cloud-bugfix.png b/content/en/docs/pre-release/images/edge-stack-1.13.8-cloud-bugfix.png deleted file mode 100644 index 6beaf653..00000000 Binary files a/content/en/docs/pre-release/images/edge-stack-1.13.8-cloud-bugfix.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/emissary-1.13.10-cors-origin.png b/content/en/docs/pre-release/images/emissary-1.13.10-cors-origin.png deleted file mode 100644 index b7538e5f..00000000 Binary files a/content/en/docs/pre-release/images/emissary-1.13.10-cors-origin.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/fast-icon.svg b/content/en/docs/pre-release/images/fast-icon.svg deleted file mode 100644 index 354542ee..00000000 --- a/content/en/docs/pre-release/images/fast-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1187990_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/pre-release/images/features-icons/basic-authentication.svg b/content/en/docs/pre-release/images/features-icons/basic-authentication.svg deleted file mode 100644 index 2bd19edf..00000000 --- a/content/en/docs/pre-release/images/features-icons/basic-authentication.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_897228_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/pre-release/images/features-icons/canary-release.svg b/content/en/docs/pre-release/images/features-icons/canary-release.svg deleted file mode 100644 index f8de57d9..00000000 --- a/content/en/docs/pre-release/images/features-icons/canary-release.svg +++ /dev/null @@ -1,27 +0,0 @@ - - - - Group 25 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - diff --git a/content/en/docs/pre-release/images/features-icons/cors.svg b/content/en/docs/pre-release/images/features-icons/cors.svg deleted file mode 100644 index e559d924..00000000 --- a/content/en/docs/pre-release/images/features-icons/cors.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_111967_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/pre-release/images/features-icons/datadog.png b/content/en/docs/pre-release/images/features-icons/datadog.png deleted file mode 100644 index eea05f8c..00000000 Binary files a/content/en/docs/pre-release/images/features-icons/datadog.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/features-icons/datadog.svg b/content/en/docs/pre-release/images/features-icons/datadog.svg deleted file mode 100644 index e46e8118..00000000 --- a/content/en/docs/pre-release/images/features-icons/datadog.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Screen Shot 2018-04-05 at 8.22.25 AM - Created with Sketch. - - - - - - - diff --git a/content/en/docs/pre-release/images/features-icons/diagnostics.svg b/content/en/docs/pre-release/images/features-icons/diagnostics.svg deleted file mode 100644 index 940e1bc2..00000000 --- a/content/en/docs/pre-release/images/features-icons/diagnostics.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_196445_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/pre-release/images/features-icons/distributed-tracing.png b/content/en/docs/pre-release/images/features-icons/distributed-tracing.png deleted file mode 100644 index 6b69e28c..00000000 Binary files a/content/en/docs/pre-release/images/features-icons/distributed-tracing.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/features-icons/grpc.png b/content/en/docs/pre-release/images/features-icons/grpc.png deleted file mode 100644 index b2f5a0d9..00000000 Binary files a/content/en/docs/pre-release/images/features-icons/grpc.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/features-icons/prometheus.svg b/content/en/docs/pre-release/images/features-icons/prometheus.svg deleted file mode 100644 index d5252a66..00000000 --- a/content/en/docs/pre-release/images/features-icons/prometheus.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - prometheus_logo_grey - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/pre-release/images/features-icons/rate-limiting.svg b/content/en/docs/pre-release/images/features-icons/rate-limiting.svg deleted file mode 100644 index f1b6eacb..00000000 --- a/content/en/docs/pre-release/images/features-icons/rate-limiting.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - Group 10 - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/pre-release/images/features-icons/regex-routing.svg b/content/en/docs/pre-release/images/features-icons/regex-routing.svg deleted file mode 100644 index 113b53b5..00000000 --- a/content/en/docs/pre-release/images/features-icons/regex-routing.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - noun_699774_cc - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/pre-release/images/features-icons/request-transformers.svg b/content/en/docs/pre-release/images/features-icons/request-transformers.svg deleted file mode 100644 index 0b13e2dc..00000000 --- a/content/en/docs/pre-release/images/features-icons/request-transformers.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_96239_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/pre-release/images/features-icons/shadowing.svg b/content/en/docs/pre-release/images/features-icons/shadowing.svg deleted file mode 100644 index 9e85eee1..00000000 --- a/content/en/docs/pre-release/images/features-icons/shadowing.svg +++ /dev/null @@ -1,15 +0,0 @@ - - - - shadow - Created with Sketch. - - - - - - - - - - diff --git a/content/en/docs/pre-release/images/features-icons/statsd.png b/content/en/docs/pre-release/images/features-icons/statsd.png deleted file mode 100644 index 28374438..00000000 Binary files a/content/en/docs/pre-release/images/features-icons/statsd.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/features-icons/statsd.svg b/content/en/docs/pre-release/images/features-icons/statsd.svg deleted file mode 100644 index cabc90db..00000000 --- a/content/en/docs/pre-release/images/features-icons/statsd.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - 88eb31f74479e422e4e9abfc6c2b00ee - Created with Sketch. - - - - - - - - - - - - - - - diff --git a/content/en/docs/pre-release/images/features-icons/third-party-auth.svg b/content/en/docs/pre-release/images/features-icons/third-party-auth.svg deleted file mode 100644 index 5359a24a..00000000 --- a/content/en/docs/pre-release/images/features-icons/third-party-auth.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_511233_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/pre-release/images/features-icons/timeouts.svg b/content/en/docs/pre-release/images/features-icons/timeouts.svg deleted file mode 100644 index 47f63056..00000000 --- a/content/en/docs/pre-release/images/features-icons/timeouts.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - noun_587034_cc - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/pre-release/images/features-icons/tls-termination.svg b/content/en/docs/pre-release/images/features-icons/tls-termination.svg deleted file mode 100644 index 6a631a96..00000000 --- a/content/en/docs/pre-release/images/features-icons/tls-termination.svg +++ /dev/null @@ -1,17 +0,0 @@ - - - - noun_63544_cc - Created with Sketch. - - - - - - - - - - - - diff --git a/content/en/docs/pre-release/images/features-icons/url-rewrite.svg b/content/en/docs/pre-release/images/features-icons/url-rewrite.svg deleted file mode 100644 index 023e2e05..00000000 --- a/content/en/docs/pre-release/images/features-icons/url-rewrite.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1295942_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/pre-release/images/features-icons/websockets.svg b/content/en/docs/pre-release/images/features-icons/websockets.svg deleted file mode 100644 index af17b9c0..00000000 --- a/content/en/docs/pre-release/images/features-icons/websockets.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - noun_50814_cc - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/pre-release/images/features-table.jpg b/content/en/docs/pre-release/images/features-table.jpg deleted file mode 100644 index 3de2eb4f..00000000 Binary files a/content/en/docs/pre-release/images/features-table.jpg and /dev/null differ diff --git a/content/en/docs/pre-release/images/gRPC-TLS-Ambassador.png b/content/en/docs/pre-release/images/gRPC-TLS-Ambassador.png deleted file mode 100644 index 0189253e..00000000 Binary files a/content/en/docs/pre-release/images/gRPC-TLS-Ambassador.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/gRPC-TLS-Originate.png b/content/en/docs/pre-release/images/gRPC-TLS-Originate.png deleted file mode 100644 index 1b62010d..00000000 Binary files a/content/en/docs/pre-release/images/gRPC-TLS-Originate.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/github-login.png b/content/en/docs/pre-release/images/github-login.png deleted file mode 100644 index cfd4d4bf..00000000 Binary files a/content/en/docs/pre-release/images/github-login.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/global-features-bg.svg b/content/en/docs/pre-release/images/global-features-bg.svg deleted file mode 100644 index a39c5232..00000000 --- a/content/en/docs/pre-release/images/global-features-bg.svg +++ /dev/null @@ -1,34 +0,0 @@ - - - - ambassador_logo@2x - Created with Sketch. - - - - - - - - diff --git a/content/en/docs/pre-release/images/grafana.png b/content/en/docs/pre-release/images/grafana.png deleted file mode 100644 index 03912506..00000000 Binary files a/content/en/docs/pre-release/images/grafana.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/grpc-tls.png b/content/en/docs/pre-release/images/grpc-tls.png deleted file mode 100644 index 4d705ff0..00000000 Binary files a/content/en/docs/pre-release/images/grpc-tls.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/helm-navy.png b/content/en/docs/pre-release/images/helm-navy.png deleted file mode 100644 index a9710143..00000000 Binary files a/content/en/docs/pre-release/images/helm-navy.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/helm.png b/content/en/docs/pre-release/images/helm.png deleted file mode 100644 index 1c5af71b..00000000 Binary files a/content/en/docs/pre-release/images/helm.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/highly-available-icon.svg b/content/en/docs/pre-release/images/highly-available-icon.svg deleted file mode 100644 index 9cb3eff9..00000000 --- a/content/en/docs/pre-release/images/highly-available-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1205522_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/pre-release/images/jaeger.png b/content/en/docs/pre-release/images/jaeger.png deleted file mode 100644 index 3b821c09..00000000 Binary files a/content/en/docs/pre-release/images/jaeger.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/kubernetes.png b/content/en/docs/pre-release/images/kubernetes.png deleted file mode 100644 index a392a886..00000000 Binary files a/content/en/docs/pre-release/images/kubernetes.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/left-arrow.svg b/content/en/docs/pre-release/images/left-arrow.svg deleted file mode 100644 index 75cdc7f1..00000000 --- a/content/en/docs/pre-release/images/left-arrow.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Path 2 - Created with Sketch. - - - - - - - diff --git a/content/en/docs/pre-release/images/linux.png b/content/en/docs/pre-release/images/linux.png deleted file mode 100644 index 1832c594..00000000 Binary files a/content/en/docs/pre-release/images/linux.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/logo.png b/content/en/docs/pre-release/images/logo.png deleted file mode 100644 index 701f63ba..00000000 Binary files a/content/en/docs/pre-release/images/logo.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/mapping-editor.png b/content/en/docs/pre-release/images/mapping-editor.png deleted file mode 100644 index f8b751a1..00000000 Binary files a/content/en/docs/pre-release/images/mapping-editor.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/network-architecture.png b/content/en/docs/pre-release/images/network-architecture.png deleted file mode 100644 index 3217b3e1..00000000 Binary files a/content/en/docs/pre-release/images/network-architecture.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/penguin-background.svg b/content/en/docs/pre-release/images/penguin-background.svg deleted file mode 100644 index 7affc0d5..00000000 --- a/content/en/docs/pre-release/images/penguin-background.svg +++ /dev/null @@ -1,102 +0,0 @@ - - - - @2xambassador_logo - Created with Sketch. - - - - - - - - - - - - - diff --git a/content/en/docs/pre-release/images/pro-iap.png b/content/en/docs/pre-release/images/pro-iap.png deleted file mode 100644 index 787265d8..00000000 Binary files a/content/en/docs/pre-release/images/pro-iap.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/quote.svg b/content/en/docs/pre-release/images/quote.svg deleted file mode 100644 index bab6e871..00000000 --- a/content/en/docs/pre-release/images/quote.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - “ - Created with Sketch. - - - - - - - - - - - diff --git a/content/en/docs/pre-release/images/right-arrow.svg b/content/en/docs/pre-release/images/right-arrow.svg deleted file mode 100644 index 627144c6..00000000 --- a/content/en/docs/pre-release/images/right-arrow.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - Path 2 Copy - Created with Sketch. - - - - - - - diff --git a/content/en/docs/pre-release/images/routing-icon.svg b/content/en/docs/pre-release/images/routing-icon.svg deleted file mode 100644 index bd860b13..00000000 --- a/content/en/docs/pre-release/images/routing-icon.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - noun_1062254_cc - Created with Sketch. - - - - - - - - - diff --git a/content/en/docs/pre-release/images/self-service-features-bg.svg b/content/en/docs/pre-release/images/self-service-features-bg.svg deleted file mode 100644 index 40bc400a..00000000 --- a/content/en/docs/pre-release/images/self-service-features-bg.svg +++ /dev/null @@ -1,93 +0,0 @@ - - - - Group 8 - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - SELF-SERVICE FEATURES - - - - diff --git a/content/en/docs/pre-release/images/shadowing.png b/content/en/docs/pre-release/images/shadowing.png deleted file mode 100644 index 097ecbd5..00000000 Binary files a/content/en/docs/pre-release/images/shadowing.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/speedometers.png b/content/en/docs/pre-release/images/speedometers.png deleted file mode 100644 index 7ce2c2a2..00000000 Binary files a/content/en/docs/pre-release/images/speedometers.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/tp-architecture.png b/content/en/docs/pre-release/images/tp-architecture.png deleted file mode 100644 index 20ae3589..00000000 Binary files a/content/en/docs/pre-release/images/tp-architecture.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/tp-tutorial-1.png b/content/en/docs/pre-release/images/tp-tutorial-1.png deleted file mode 100644 index ee68dc7d..00000000 Binary files a/content/en/docs/pre-release/images/tp-tutorial-1.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/tp-tutorial-2.png b/content/en/docs/pre-release/images/tp-tutorial-2.png deleted file mode 100644 index 129dc6ee..00000000 Binary files a/content/en/docs/pre-release/images/tp-tutorial-2.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/tp-tutorial-3.png b/content/en/docs/pre-release/images/tp-tutorial-3.png deleted file mode 100644 index 946629fc..00000000 Binary files a/content/en/docs/pre-release/images/tp-tutorial-3.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/tp-tutorial-4.png b/content/en/docs/pre-release/images/tp-tutorial-4.png deleted file mode 100644 index cb6e7a9d..00000000 Binary files a/content/en/docs/pre-release/images/tp-tutorial-4.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/trad-inner-dev-loop.png b/content/en/docs/pre-release/images/trad-inner-dev-loop.png deleted file mode 100644 index 618b674f..00000000 Binary files a/content/en/docs/pre-release/images/trad-inner-dev-loop.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/windows.png b/content/en/docs/pre-release/images/windows.png deleted file mode 100644 index a065dc17..00000000 Binary files a/content/en/docs/pre-release/images/windows.png and /dev/null differ diff --git a/content/en/docs/pre-release/images/xkcd.png b/content/en/docs/pre-release/images/xkcd.png deleted file mode 100644 index ed0d5c33..00000000 Binary files a/content/en/docs/pre-release/images/xkcd.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/edge-stack-1.13.4.png b/content/en/docs/pre-release/release-notes/edge-stack-1.13.4.png deleted file mode 100644 index 954ac1a9..00000000 Binary files a/content/en/docs/pre-release/release-notes/edge-stack-1.13.4.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/edge-stack-1.13.7-json-logging.png b/content/en/docs/pre-release/release-notes/edge-stack-1.13.7-json-logging.png deleted file mode 100644 index 4a47cbdf..00000000 Binary files a/content/en/docs/pre-release/release-notes/edge-stack-1.13.7-json-logging.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/edge-stack-1.13.7-memory.png b/content/en/docs/pre-release/release-notes/edge-stack-1.13.7-memory.png deleted file mode 100644 index 9c415ba3..00000000 Binary files a/content/en/docs/pre-release/release-notes/edge-stack-1.13.7-memory.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/edge-stack-1.13.7-tcpmapping-consul.png b/content/en/docs/pre-release/release-notes/edge-stack-1.13.7-tcpmapping-consul.png deleted file mode 100644 index c455a47f..00000000 Binary files a/content/en/docs/pre-release/release-notes/edge-stack-1.13.7-tcpmapping-consul.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/edge-stack-1.13.8-cloud-bugfix.png b/content/en/docs/pre-release/release-notes/edge-stack-1.13.8-cloud-bugfix.png deleted file mode 100644 index 6beaf653..00000000 Binary files a/content/en/docs/pre-release/release-notes/edge-stack-1.13.8-cloud-bugfix.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/edge-stack-2.0.0-host_crd.png b/content/en/docs/pre-release/release-notes/edge-stack-2.0.0-host_crd.png deleted file mode 100644 index c77ef528..00000000 Binary files a/content/en/docs/pre-release/release-notes/edge-stack-2.0.0-host_crd.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/edge-stack-2.0.0-ingressstatus.png b/content/en/docs/pre-release/release-notes/edge-stack-2.0.0-ingressstatus.png deleted file mode 100644 index 6856d308..00000000 Binary files a/content/en/docs/pre-release/release-notes/edge-stack-2.0.0-ingressstatus.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/edge-stack-2.0.0-insecure_action_hosts.png b/content/en/docs/pre-release/release-notes/edge-stack-2.0.0-insecure_action_hosts.png deleted file mode 100644 index 79c20bad..00000000 Binary files a/content/en/docs/pre-release/release-notes/edge-stack-2.0.0-insecure_action_hosts.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/edge-stack-2.0.0-listener.png b/content/en/docs/pre-release/release-notes/edge-stack-2.0.0-listener.png deleted file mode 100644 index ea45a02b..00000000 Binary files a/content/en/docs/pre-release/release-notes/edge-stack-2.0.0-listener.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/edge-stack-2.0.0-prune_routes.png b/content/en/docs/pre-release/release-notes/edge-stack-2.0.0-prune_routes.png deleted file mode 100644 index bc43229f..00000000 Binary files a/content/en/docs/pre-release/release-notes/edge-stack-2.0.0-prune_routes.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/edge-stack-2.0.0-tlscontext.png b/content/en/docs/pre-release/release-notes/edge-stack-2.0.0-tlscontext.png deleted file mode 100644 index 68dbad80..00000000 Binary files a/content/en/docs/pre-release/release-notes/edge-stack-2.0.0-tlscontext.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/edge-stack-2.0.0-v3alpha1.png b/content/en/docs/pre-release/release-notes/edge-stack-2.0.0-v3alpha1.png deleted file mode 100644 index c0ac3596..00000000 Binary files a/content/en/docs/pre-release/release-notes/edge-stack-2.0.0-v3alpha1.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/emissary-1.13.10-cors-origin.png b/content/en/docs/pre-release/release-notes/emissary-1.13.10-cors-origin.png deleted file mode 100644 index b7538e5f..00000000 Binary files a/content/en/docs/pre-release/release-notes/emissary-1.13.10-cors-origin.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/emissary-ga.png b/content/en/docs/pre-release/release-notes/emissary-ga.png deleted file mode 100644 index 062f043a..00000000 Binary files a/content/en/docs/pre-release/release-notes/emissary-ga.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/tada.png b/content/en/docs/pre-release/release-notes/tada.png deleted file mode 100644 index c8832e8e..00000000 Binary files a/content/en/docs/pre-release/release-notes/tada.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/v2.0.4-k8s-1.22.png b/content/en/docs/pre-release/release-notes/v2.0.4-k8s-1.22.png deleted file mode 100644 index ed9b0415..00000000 Binary files a/content/en/docs/pre-release/release-notes/v2.0.4-k8s-1.22.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/v2.0.4-l7depth.png b/content/en/docs/pre-release/release-notes/v2.0.4-l7depth.png deleted file mode 100644 index 9314324c..00000000 Binary files a/content/en/docs/pre-release/release-notes/v2.0.4-l7depth.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/v2.0.4-mapping-dns-type.png b/content/en/docs/pre-release/release-notes/v2.0.4-mapping-dns-type.png deleted file mode 100644 index 7770c77d..00000000 Binary files a/content/en/docs/pre-release/release-notes/v2.0.4-mapping-dns-type.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/v2.0.4-v3alpha1.png b/content/en/docs/pre-release/release-notes/v2.0.4-v3alpha1.png deleted file mode 100644 index 9c50b8fb..00000000 Binary files a/content/en/docs/pre-release/release-notes/v2.0.4-v3alpha1.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/v2.0.4-version.png b/content/en/docs/pre-release/release-notes/v2.0.4-version.png deleted file mode 100644 index 9481b7db..00000000 Binary files a/content/en/docs/pre-release/release-notes/v2.0.4-version.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/v2.0.5-auth-circuit-breaker.png b/content/en/docs/pre-release/release-notes/v2.0.5-auth-circuit-breaker.png deleted file mode 100644 index cac8cf7b..00000000 Binary files a/content/en/docs/pre-release/release-notes/v2.0.5-auth-circuit-breaker.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/v2.0.5-mappingselector.png b/content/en/docs/pre-release/release-notes/v2.0.5-mappingselector.png deleted file mode 100644 index 31942ede..00000000 Binary files a/content/en/docs/pre-release/release-notes/v2.0.5-mappingselector.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/v2.1.0-canary.png b/content/en/docs/pre-release/release-notes/v2.1.0-canary.png deleted file mode 100644 index 39d3bbbf..00000000 Binary files a/content/en/docs/pre-release/release-notes/v2.1.0-canary.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/v2.1.0-gzip-enabled.png b/content/en/docs/pre-release/release-notes/v2.1.0-gzip-enabled.png deleted file mode 100644 index 061fcbc9..00000000 Binary files a/content/en/docs/pre-release/release-notes/v2.1.0-gzip-enabled.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/v2.1.0-smoother-migration.png b/content/en/docs/pre-release/release-notes/v2.1.0-smoother-migration.png deleted file mode 100644 index ebd77497..00000000 Binary files a/content/en/docs/pre-release/release-notes/v2.1.0-smoother-migration.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/v2.1.2-annotations.png b/content/en/docs/pre-release/release-notes/v2.1.2-annotations.png deleted file mode 100644 index b5498c3c..00000000 Binary files a/content/en/docs/pre-release/release-notes/v2.1.2-annotations.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/v2.1.2-host-mapping-matching.png b/content/en/docs/pre-release/release-notes/v2.1.2-host-mapping-matching.png deleted file mode 100644 index 1cfba5ed..00000000 Binary files a/content/en/docs/pre-release/release-notes/v2.1.2-host-mapping-matching.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/v2.1.2-mapping-cors.png b/content/en/docs/pre-release/release-notes/v2.1.2-mapping-cors.png deleted file mode 100644 index f76ea01c..00000000 Binary files a/content/en/docs/pre-release/release-notes/v2.1.2-mapping-cors.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/v2.1.2-mapping-less-weighted.png b/content/en/docs/pre-release/release-notes/v2.1.2-mapping-less-weighted.png deleted file mode 100644 index 7e299062..00000000 Binary files a/content/en/docs/pre-release/release-notes/v2.1.2-mapping-less-weighted.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/v2.1.2-mapping-no-rewrite.png b/content/en/docs/pre-release/release-notes/v2.1.2-mapping-no-rewrite.png deleted file mode 100644 index 5d3d5a29..00000000 Binary files a/content/en/docs/pre-release/release-notes/v2.1.2-mapping-no-rewrite.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/v2.2.0-cloud.png b/content/en/docs/pre-release/release-notes/v2.2.0-cloud.png deleted file mode 100644 index 5923fcb4..00000000 Binary files a/content/en/docs/pre-release/release-notes/v2.2.0-cloud.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/v2.2.0-percent-escape.png b/content/en/docs/pre-release/release-notes/v2.2.0-percent-escape.png deleted file mode 100644 index df4d81b9..00000000 Binary files a/content/en/docs/pre-release/release-notes/v2.2.0-percent-escape.png and /dev/null differ diff --git a/content/en/docs/pre-release/release-notes/v2.2.0-tls-cert-validation.png b/content/en/docs/pre-release/release-notes/v2.2.0-tls-cert-validation.png deleted file mode 100644 index f8635b5a..00000000 Binary files a/content/en/docs/pre-release/release-notes/v2.2.0-tls-cert-validation.png and /dev/null differ diff --git a/content/en/docs/pre-release/releaseNotes.yml b/content/en/docs/pre-release/releaseNotes.yml deleted file mode 100644 index 93f3c73b..00000000 --- a/content/en/docs/pre-release/releaseNotes.yml +++ /dev/null @@ -1,1658 +0,0 @@ -# -*- fill-column: 100 -*- - -# This file should be placed in the folder for the version of the -# product that's meant to be documented. A `/release-notes` page will -# be automatically generated and populated at build time. -# -# Note that an entry needs to be added to the `doc-links.yml` file in -# order to surface the release notes in the table of contents. -# -# The YAML in this file should contain: -# -# changelog: An (optional) URL to the CHANGELOG for the product. -# items: An array of releases with the following attributes: -# - version: The (optional) version number of the release, if applicable. -# - date: The date of the release in the format YYYY-MM-DD. -# - notes: An array of noteworthy changes included in the release, each having the following attributes: -# - type: The type of change, one of `bugfix`, `feature`, `security` or `change`. -# - title: A short title of the noteworthy change. -# - body: >- -# Two or three sentences describing the change and why it -# is noteworthy. This is HTML, not plain text or -# markdown. It is handy to use YAML's ">-" feature to -# allow line-wrapping. -# - image: >- -# The URL of an image that visually represents the -# noteworthy change. This path is relative to the -# `release-notes` directory; if this file is -# `FOO/releaseNotes.yml`, then the image paths are -# relative to `FOO/release-notes/`. -# - docs: The path to the documentation page where additional information can be found. -# - href: A path from the root to a resource on the getambassador website, takes precedence over a docs link. - -changelog: https://github.com/emissary-ingress/emissary/blob/$branch$/CHANGELOG.md -items: - - version: 3.8.2 - date: '2023-10-11' - notes: - - title: Upgrade Envoy - type: security - body: >- - This release includes security patches to the current Envoy proxy version to address CVE 2023-44487 and includes a fix to determine if a client is making too many requests with premature resets. The connection is disconnected if more than 50 percent of resets are considered premature. Another fix is also included which exposes a runtime setting to control the limit on the number of HTTP requests processed from a single connection in a single I/O cycle to mitigate CPU starvation. - docs: topics/running/running/ - - - title: Upgrade Golang to 1.20.10 - type: security - body: >- - Upgrading to the latest release of Golang as part of our general dependency upgrade process. This update resolves CVE-2023-39323 and CVE-2023-39325. - docs: https://go.dev/doc/devel/release#go1.20.minor - - - version: 3.8.1 - date: '2023-09-18' - notes: - - title: Upgrade Golang to 1.20.8 - type: security - body: >- - Upgrading to the latest release of Golang as part of our general dependency upgrade process. This includes security fixes for CVE-2023-39318, CVE-2023-39319. - docs: https://go.dev/doc/devel/release#go1.20.minor - - - version: 3.8.0 - date: '2023-08-29' - notes: - - title: Account for matchLabels when associating mappings with the same prefix to different Hosts - type: bugfix - body: >- - As of v2.2.2, if two mappings were associated with different Hosts through host - 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.
- docs: https://github.com/emissary-ingress/emissary/blob/master/charts/emissary-ingress/CHANGELOG.md - - - version: 3.7.1 - date: '2023-07-13' - notes: - - title: Upgrade to Envoy 1.26.3 - type: security - body: >- - This upgrades $productName$ to be built on Envoy v1.26.3 which includes a fix for CVE-2023-35945. - docs: https://www.envoyproxy.io/docs/envoy/v1.26.1/version_history/v1.26/v1.26 - - - version: 3.7.0 - date: '2023-06-20' - notes: - - title: Upgrade to Envoy 1.26.1 - type: feature - body: >- - This upgrades $productName$ to be built on Envoy v1.26.1 which provides security, performance and feature enhancements. You can read more about them here: Envoy Proxy 1.26.1 Release Notes - docs: https://www.envoyproxy.io/docs/envoy/v1.26.1/version_history/v1.26/v1.26 - - - version: 3.6.0 - date: '2023-04-17' - notes: - - 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.
- - - Add support for setting nodeSelector, tolerations and affinity on the Ambassador Agent. Thanks to Philip Panyukov.
- - - Use autoscaling API version based on Kubernetes version. Thanks to Elvind Valderhaug.
- - - Upgrade 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.

- - Thanks to Pier. - - docs: https://github.com/emissary-ingress/emissary/blob/master/charts/emissary-ingress/CHANGELOG.md - - - version: 3.5.0 - date: '2023-02-15' - notes: - - title: Upgraded to golang 1.20.1 - type: security - body: >- - Upgraded to the latest release of Golang as part of our general dependency upgrade process. This includes - security fixes for CVE-2022-41725, CVE-2022-41723. - - title: TracingService support for native OpenTelemetry driver - type: feature - body: >- - In Envoy 1.24, experimental support for a native OpenTelemetry tracing driver was introduced that allows exporting spans in the otlp format. Many observability platforms accept that format and is the recommended replacement for the LightStep driver. $productName$ now supports setting the TracingService.spec.driver=opentelemetry to export traces in the otlp format.

- - Thanks to Paul for helping us get this tested and over the finish line! - - - title: Switch to a non-blocking readiness check - type: feature - body: >- - The /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).

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

- - Configure the listener port using 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.

- - In v2.Y/v3.Y+, the way $productName$ generates Envoy configuration changed to address memory pressure and improve route lookup speed in Envoy. However, when including a port in the hostname, an incorrect configuration was generated with an sni match including the port. This caused incoming request to never match causing a 404 Not Found.This has been fixed and the correct envoy configuration is - being generated which restores existing behavior. - - - title: Add support for resolving port names in Ingress resource - type: change - body: >- - Previously, specifying backend ports by name in Ingress was not supported and would result in defaulting to port 80. This allows $productName$ to now resolve port names for backend services. If the port number cannot be resolved by the name (e.g named port in the Service doesn't exist) then it will continue to default back - to port 80.

- - Thanks to Anton Ustyuzhanin!. - github: - - title: "#4809" - link: https://github.com/emissary-ingress/emissary/pull/4809 - - - title: Add starupProbe to emissary-apiext server - type: change - body: >- - The 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:

- - - Update default image to $productName$ v3.5.0.
- - Add support for configuring startupProbes on the emissary-ingress deployment.
- - Allow setting pod and container security settings on the Ambassador Agent.
- - Added deprecation notice in the values.yaml file for 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:

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

- - Users that are using $productName$ with Certificate Revocation List and allow external users to provide input should upgrade to ensure they are not vulnerable to CVE-2023-0286. - - - version: 3.4.0 - date: '2023-01-03' - notes: - - title: Upgrade to Envoy 1.24.1 - type: feature - body: >- - This upgrades $productName$ to be built on Envoy v1.24.1. Two notable changes were introduced:

- - First, the team at LightStep and the Envoy Maintainers have decided to no longer support the native LightStep tracing driver in favor of using the Open Telemetry driver. The code for the native Enovy LightStep driver has been removed from the Envoy code base. This means $productName$ will no longer support LightStep in the 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.

- - Second, a bug was fixed in Envoy 1.24 that changes how the upstream clusters distributed tracing 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.

- - This allows the healthcheck server to be configured to use IPv6-only k8s environments. (Thanks to Dmitry Golushko!). - docs: https://www.getambassador.io/docs/emissary/pre-release/topics/running/environment/ - - - 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 - - - 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. $productName$ does not expose any of these golang servers to external clients directly. - - - 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: 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 - - - 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 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: 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/content/en/docs/pre-release/topics/concepts/architecture.md b/content/en/docs/pre-release/topics/concepts/architecture.md deleted file mode 100644 index fe9e0bd3..00000000 --- a/content/en/docs/pre-release/topics/concepts/architecture.md +++ /dev/null @@ -1,27 +0,0 @@ -# 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). - -![Architecture](../../images/ambassador-arch.png) - -## 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/content/en/docs/pre-release/topics/concepts/gitops-continuous-delivery.md b/content/en/docs/pre-release/topics/concepts/gitops-continuous-delivery.md deleted file mode 100644 index 336a1c66..00000000 --- a/content/en/docs/pre-release/topics/concepts/gitops-continuous-delivery.md +++ /dev/null @@ -1,66 +0,0 @@ -# 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/content/en/docs/pre-release/topics/concepts/index.md b/content/en/docs/pre-release/topics/concepts/index.md deleted file mode 100644 index 2d02a027..00000000 --- a/content/en/docs/pre-release/topics/concepts/index.md +++ /dev/null @@ -1,10 +0,0 @@ -# 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/content/en/docs/pre-release/topics/concepts/kubernetes-network-architecture.md b/content/en/docs/pre-release/topics/concepts/kubernetes-network-architecture.md deleted file mode 100644 index 2239a24f..00000000 --- a/content/en/docs/pre-release/topics/concepts/kubernetes-network-architecture.md +++ /dev/null @@ -1,52 +0,0 @@ -# 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: - -
- -![Kubernetes Network Architecture](/../../images/documentation/kubernetes-network.inline.svg) - -
- -Each of the components in this topology is discussed in further detail below. - -### Load balancer - -The load balancer is deployed outside of the Kubernetes cluster. Typically, the load balancer also has one or more static IP addresses assigned to it. A DNS entry is then created to map a domain name (e.g., example.com) to the static IP address. - -Cloud infrastructure providers such as Amazon Web Services, Azure, Digital Ocean, and Google make it easy to create these load balancers directly from Kubernetes. This is done by creating a Kubernetes service of `type: LoadBalancer`. When this service is created, the cloud provider will use the metadata contained in the Kubernetes service definition to provision a load balancer. - -If the Kubernetes cluster is deployed in a private data center, an external load balancer is still generally used. Provisioning of this load balancer usually requires the involvement of the data center operations team. - -In both the private data center and cloud infrastructure case, the external load balancer should be configured to point to the edge proxy. - -### Edge Proxy / ingress controller - -The Edge Proxy is typically a Layer 7 proxy that is deployed directly in the cluster. The core function of the edge proxy is to accept incoming traffic from the external load balancer and route the traffic to Kubernetes services. The edge proxy should be configured using Kubernetes manifests. This enables a common management workflow for both the edge proxy and Kubernetes services. - -The most popular approach to configuring edge proxies is with the Kubernetes ingress resource. When an edge proxy can process ingress resources, it is called an ingress controller. Not all edge proxies are ingress controllers (because they can't process ingress resources), but all ingress controllers are edge proxies. - -The ingress resource is a Kubernetes standard. As such, it is a lowest common denominator resource. In practice, users find that the ingress resource is insufficient in scope to address the requirements for edge routing. Semantics such as TLS termination, redirecting to TLS, timeouts, rate limiting, and authentication are all beyond the scope of the ingress resource. - -$productName$ can function as an ingress controller (i.e., it reads ingress resources), although it also includes many other capabilities that are beyond the scope of the ingress specification. Most $productName$ users find that the various additional capabilities of $productName$ are essential, and end up using $productName$'s extensions to the ingress resource, instead of using ingress resources themselves. - -### Kubernetes services and Pods - -Each instance of your application is deployed in a Kubernetes pod. As the workload on your application increases or decreases, Kubernetes can automatically add or remove pods. A Kubernetes _service_ represents a group of pods that comprise the same version of a given application. Traffic can be routed to the pods via a Kubernetes service, or it can be routed directly to the pods. - -When traffic is routed to the pods via a Kubernetes service, Kubernetes uses a built-in mechanism called `kube-proxy` to load balance traffic between the pods. Due to its implementation, `kube-proxy` is a Layer 4 proxy, i.e., it load balances at a connection level. For particular types of traffic such as HTTP/2 and gRPC, this form of load balancing is particularly problematic as it can easily result in a very uneven load balancing configuration. - -Traffic can also be routed directly to pods, bypassing the Kubernetes service. Since pods are much more ephemeral than Kubernetes services, this approach requires an edge proxy that is optimized for this use case. In particular, the edge proxy needs to support real-time discovery of pods, and be able to dynamically update pod locations without downtime. - -$productName$ supports routing both to Kubernetes services and directly to pods. - -## Further reading - -* [Kubernetes Ingress 101](https://blog.getambassador.io/kubernetes-ingress-nodeport-load-balancers-and-ingress-controllers-6e29f1c44f2d) -* [Envoy Proxy Performance on Kubernetes](/resources/envoyproxy-performance-on-k8s/) diff --git a/content/en/docs/pre-release/topics/concepts/microservices-api-gateways.md b/content/en/docs/pre-release/topics/concepts/microservices-api-gateways.md deleted file mode 100644 index ba95b8fc..00000000 --- a/content/en/docs/pre-release/topics/concepts/microservices-api-gateways.md +++ /dev/null @@ -1,60 +0,0 @@ -# Microservices API gateways - -A microservices API gateway is an API gateway designed to accelerate the development workflow of independent services teams. A microservices API gateway provides all the functionality for a team to independently publish, monitor, and update a microservice. - -This focus on accelerating the development workflow is distinct from the purpose of traditional API gateways, which focus on the challenges of managing APIs. Over the past decade, organizations have worked to expose internal systems through well-defined APIs. The challenge of safely exposing hundreds or thousands of APIs to end-users (both internal and external) led to the emergence of API gateways. Over time, API gateways have become centralized, mission critical pieces of infrastructure that control access to these APIs. - -In this article, we'll discuss how the difference in business objective (productivity vs management) results in a very different API gateway. - -## Microservices organization - -In a microservices organization, small teams of developers work independently from each other to rapidly deliver functionality to the customer. In order for each service team to work independently, with a productive workflow, a services team needs to be able to: - -1. Publish their service, so that others can use the service -2. Monitor their service, to see how well it's working -3. Test and update their service, so they can keep on improving the service - -The team needs to do all of this *without* requiring assistance from another operations or platform team--as soon as a services team requires another team, they're no longer working independently, and this can lead to bottlenecks. - -For service publication, a microservices API gateway provides a static address for consumers, and dynamically route requests to the appropriate service address. In addition, providing authentication and TLS termination for security are typical considerations in exposing a service to other consumers. - -Understanding the end-user experience of a service is crucial to improving the service. For example, a software update could inadvertently impact the latency of certain requests. A microservices API gateway is well situated to collect key observability metrics on end-user traffic as it routes traffic to the end service. - -A microservices API gateway also supports dynamically routing user requests to different service versions for canary testing. By routing a small fraction of end-user requests to a new version of a service, service teams can safely test the impact of new updates to a small subset of users. - -## Microservices API Gateways vs. enterprise API Gateways - -At first glance, the use case described above may be fulfilled with an enterprise-focused API gateway. While this may be true, the actual emphasis of enterprise API gateways and microservices API gateways are somewhat different: - -| Use case | Traditional Enterprise API gateway | Microservices API gateway | -|---------------|-------------------|------------------------------| -| Primary Purpose | Expose, compose, and manage internal business APIs | Expose and observe internal business services | -| Publishing Functionality | API management team or service team registers / updates gateway via admin API | Service team registers / updates gateway via declarative code as part of the deployment process | -| Monitoring | Admin and operations focused e.g. meter API calls per consumer, report errors (e.g. internal 5XX). | Developer focused e.g. latency, traffic, errors, saturation | -| Handling and Debugging Issues | L7 error-handling (e.g. custom error page or payload). Run gateway/API with additional logging. Troubleshoot issue in staging environment | Configure more detailed monitoring. Enable traffic shadowing and / or canarying | -| Testing | Operate multiple environments for QA, Staging, and Production. Automated integration testing, and gated API deployment. Use client-driven API versioning for compatibility and stability (e.g. semver) | Facilitate canary routing for dynamic testing (taking care with data mutation side effects). Use developer-driven service versioning for upgrade management | -| Local Development | Deploy gateway locally (via installation script, Vagrant or Docker), and attempt to mitigate infrastructure differences with production. Use language-specific gateway mocking and stubbing frameworks | Deploy gateway locally via service orchestration platform (e.g. Kubernetes) | - -## Self-service publishing - -A team needs to be able to publish a new service to customers without requiring an operations or API management team. This ability to self-service for deployment and publication enables the team to keep the feature release velocity high. While a traditional enterprise API gateway may provide a simple mechanism (e.g., REST API) for publishing a new service, in practice, the usage is often limited to the use of a dedicated team that is responsible for the gateway. The primary reason for limiting publication to a single team is to provide an additional (human) safety mechanism: an errant API call could have potentially disastrous effects on production. - -Microservices API gateways utilize mechanisms that enable service teams to easily *and* safely publish new services, with the inherent understanding that the producing team are responsible for their service, and will fix an issue if one occurs. A microservices gateway provides configurable monitoring for issue detection, and provides hooks for debugging, such as inspecting traffic or traffic shifting/duplication. - -## Monitoring and rate limiting - -A common business model for APIs is metering, where a consumer is charged different fees depending on API usage. Traditional enterprise API gateways excel in this use case: they provide functionality for monitoring per-client usage of an API, and the ability to limit usage when the client exceeds their quota. - -A microservice gateway also requires monitoring and rate limiting, but for different reasons. Monitoring user-visible metrics such as throughput, latency, and availability, are important to ensure that new updates don't impact the end-user. Robust end-user metrics are critical to allowing rapid, incremental updates. Rate limiting is used to improve the overall resilience of a service. When a service is not responding as expected, an API gateway can throttle incoming requests to allow a service to recover and prevent a cascade failure. - -## Testing and updates - -A microservices application has multiple services, each of which is being independently updated. Automated pre-production testing of a moving target is necessary but not sufficient for microservices. Canary testing, where a small percentage of production traffic is routed to a new service version, is an important tool to help test an update. By limiting a new service version to a small percentage of users, the impact of a service failure is limited. - -In a traditional enterprise API gateway, routing is used to isolate or compose/aggregate changing API versions. Automated pre-production testing and manual post-production verification and exploration are required. - -## Summary - -Traditional enterprise API gateways are designed to solve the challenges of API management. While they may appear to solve some of the challenges of adopting microservices, the reality is that a microservices workflow creates a different set of requirements. Integrating a microservices API gateway into your development workflow empowers service teams to self-publish, monitor, and update their service, quickly and safely. This will enable your organization to ship software more rapidly, and with more reliability than ever before. - -For further reading on how an API Gateway can accelerate continuous delivery, read [this blog post](https://blog.getambassador.io/continuous-delivery-how-can-an-api-gateway-help-or-hinder-1ff15224ec4d). diff --git a/content/en/docs/pre-release/topics/concepts/progressive-delivery.md b/content/en/docs/pre-release/topics/concepts/progressive-delivery.md deleted file mode 100644 index f2ade27f..00000000 --- a/content/en/docs/pre-release/topics/concepts/progressive-delivery.md +++ /dev/null @@ -1,47 +0,0 @@ -# Progressive delivery - -Today's cloud-native applications may consist of hundreds of services, each of which are being updated at any time. Thus, many cloud-native organizations augment regression test strategies with testing in production using progressive delivery techniques. - -Progressive Delivery is an approach for releasing software to production users. In the progressive delivery model, software is released to ever growing subsets of production users. This approach reduces the blast radius in the event of a failure. - -## Why test in production? - -Modern cloud applications are continuously deployed, as different teams rapidly update their respective services. Deploying and testing updates in a pre-production staging environment introduces a bottleneck to the speed of iteration. More importantly, staging environments are not representative of what will be running in production when the deployment actually occurs given the velocity of service updates and changes in production. Testing in production addresses both of these challenges: developers evaluate their changes in the real-world environment, enabling rapid iteration. - -## Progressive delivery strategies - -There are a number of different strategies for progressive delivery. These include: - -* Feature flags, where specific features are made available to specific user groups -* Canary releases, where a (small) percentage of traffic is routed to a new version of a service before the service is full production -* Traffic shadowing, where real user traffic is copied, or shadowed, from production to the service under test - -Observability is a critical requirement for testing in production. Regardless of progressive delivery strategy, collecting key metrics around latency, traffic, errors, and saturation (the [“Four Golden Signals of Monitoring”](https://landing.google.com/sre/sre-book/chapters/monitoring-distributed-systems/#xref_monitoring_golden-signals)) provides valuable insight into the stability and performance of a new version of the service. Moreover, application developers can compare the metrics (e.g., latency) between the production version and an updated version. If the metrics are similar, then updates can proceed with much greater confidence. - -$productName$ supports a variety of strategies for progressive delivery. These strategies are discussed in further detail below. - -### Canary releases - -Canary releases shifts a small amount of real user traffic from production to the service under test. - -The user will see the direct response from the canary version of the service from any traffic that is shifted to the canary release, and they will not trigger or see the response from the current production released version of the service. The canary results can also be verified (both the downstream response and associated upstream side effects), but it is key to understand that any side effects will be persisted. - -In addition to allowing verification that the service is not crashing or otherwise behaving badly from an operational perspective when dealing with real user traffic and behavior, canary releasing allows user validation. For example, if a business KPI performs worse for all canaried requests, then this most likely indicates that the canaried service should not be fully released in its current form. - -Canary tests can be automated, and are typically run after testing in a pre-production environment has been completed. The canary release is only visible to a fraction of actual users, and any bugs or negative changes can be reversed quickly by either routing traffic away from the canary or by rolling-back the canary deployment. - -![Canary release process overview](../../images/canary-release-overview.png) - -Canary releases are not a panacea. In particular, many services may not receive sufficient traffic in order for canary releases to provide useful information in an actionable timeframe. - -### Traffic shadowing - -This approach “shadows” or mirrors a small amount of real user traffic from production to the service under test. - -Although the shadowed results can be verified (both the downstream response and associated upstream side effects) they are not returned to the user -- the user only sees the results from the currently released service. Typically any side effects are not persisted or are executed as a no-op and verified (much like setting up a mock, and verifying that a method/function was called with the correct parameters). - -This allows verification that the service is not crashing or otherwise behaving badly from an operational perspective when dealing with real user traffic and behavior (and the larger the percentage of traffic shadowed, the higher the probability of confidence). - -## Further reading - -* [Canary release pattern](https://blog.getambassador.io/cloud-native-patterns-canary-release-1cb8f82d371a) diff --git a/content/en/docs/pre-release/topics/concepts/rate-limiting-at-the-edge.md b/content/en/docs/pre-release/topics/concepts/rate-limiting-at-the-edge.md deleted file mode 100644 index f471b6d5..00000000 --- a/content/en/docs/pre-release/topics/concepts/rate-limiting-at-the-edge.md +++ /dev/null @@ -1,33 +0,0 @@ -# Rate limiting concepts at the edge - -Rate limiting at the edge is a technique that is used to prevent a sudden or sustained increase in user traffic from breaking an API or underlying service. On the Internet, users can do whatever they want to your APIs, as you have no direct control over these end-users. Whether it’s intentional or not, these users can impact the availability, responsiveness, and scalability of your service. - -## Two approaches: Rate limiting and load shedding - -Rate limiting use cases that fall into this scenario range from implementing functional requirements related to a business scenario -- for example, where requests from paying customers is prioritized over requests from non-paying trial users -- to implementing cross-functional requirements, such as resilience from a malicious actor attempting to issue a denial-of-service (DoS) attack. - -A closely related technique to rate limiting is load shedding, and this can be used to selectively prioritize traffic (by dropping requests) based on the state of the entire system. For example, if a backend data store has become overloaded and slow to respond, it may be appropriate to drop (or “shed”) low priority requests or requests that are not time sensitive. - -## Use cases and scenarios - -The table below outlines several scenarios where rate limiting and load shedding can provide an effective solution to a range of functional and cross-functional requirements. The “Type of Rate Limiter” column provides a summary of the category of rate limiting that would be most appropriate for the scenario, and the “Specifics” column outlines what business or system properties would be involved in computing rate limiting decisions. - -| Scenario | Type of Rate Limiter |                            Specifics                        -| --- | --- | --- | -**Fairness.** One or more users are sending large volumes of requests, and thus impacting other users of the API | **User request rate limiting -** restricts each user to a predetermined number of requests per time unit.

**Concurrent user request limiting -** limits the number of concurrent user requests that can be inflight at any given point in time. |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
  • Geographic rate limiter
  • Time-based rate limiter
-**Prioritisation.** The business model depends on handling high priority requests over others | **User request rate limiting** |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device, free vs non-free user etc)
-**Resilience.** The API backend cannot scale rapidly enough to meet request demand due to a technical issue. | **Backend utilisation load shedder -** rate limit based upon utilisation of aggregate backend instances.

**Node/server utilisation load shedder -** rate limit based upon utilisation of individual or isolated groups of compute nodes/servers. |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
-**Security.** Prevent bad actors from using a DoS attack to overwhelm services, fuzzing, or brute force attacks |**User request rate limiting**

**Node/server utilisation load shedder** |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
  • Service identifier load shedder e.g. login service, audit service
-**Responsiveness.** As per the Reactive Manifesto, responsive systems focus on providing rapid and consistent response times, establishing reliable upper bounds so they deliver a consistent quality of service | **Concurrent user request limiting**

**Backend utilisation load shedder**

**Node/server utilisation load shedder** |
  • User ID rate limiter
  • User property rate limiter (IP address, organisation, device etc)
  • Service identifier load shedder e.g. login service, audit service
- -## Avoiding contention with rate limiting configuration: Decoupling Dev and Ops - -One of the core features of $productName$ is the decentralization of configuration, allowing operations and development teams to independently control $productName$, as well as individual application development teams to minimize collaboration when configuring independently deployable services. This same approach applies to rate limiting configuration. - -The $productName$ rate limiting configuration allows centralized operations teams to define and implement global rate limiting and load shedding policies to protect the system, while still allowing individual application teams to define rate limiting policies that enforce business rules, for example, around paying and non-paying customers (perhaps implementing the so-called “freemium” model). See [Advanced Rate Limiting](../../../../2.0/howtos/advanced-rate-limiting) documentation for examples. - -## Benefits of applying a rate limiter to the edge - -Modern applications and APIs can experience floods of traffic over a short time period (e.g. from achieving a HackerNews front page link), and increasingly bad actors and cyber criminals are targeting public-facing services. - -By implementing rate limiting and load shedding capabilities at the edge, a large amount of scenarios that are bad for business can be mitigated. These capabilities also make the life of the operations and development team that much easier, as the need to constantly firefight ingress traffic is reduced. diff --git a/content/en/docs/pre-release/topics/install/ambassador-oss-community.md b/content/en/docs/pre-release/topics/install/ambassador-oss-community.md deleted file mode 100644 index b53d1407..00000000 --- a/content/en/docs/pre-release/topics/install/ambassador-oss-community.md +++ /dev/null @@ -1,14 +0,0 @@ -# Integration in community projects - -import Table from "../../../../../src/components/CommunityTable"; - -**$AESproductName$ is now available and includes additional functionality beyond the current $OSSproductName$.** -These features include automatic HTTPS, OAuth/OpenID Connect authentication support, integrated rate -limiting, a developer portal, and [more](/edge-stack-faq/). - -## $OSSproductName$ integrations - -If you still want to use just $OSSproductName$, don't worry! $OSSproductName$ -is currently available out-of-the-box in some Kubernetes installers and local environments. - -
\ No newline at end of file diff --git a/content/en/docs/pre-release/topics/install/bare-metal.md b/content/en/docs/pre-release/topics/install/bare-metal.md deleted file mode 100644 index 84ac1c8d..00000000 --- a/content/en/docs/pre-release/topics/install/bare-metal.md +++ /dev/null @@ -1,93 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Install with bare metal - -In cloud environments, provisioning a readily available network load balancer with $productName$ is the best option for handling ingress into your Kubernetes cluster. When running Kubernetes on a bare metal setup, where network load balancers are not available by default, we need to consider different options for exposing $productName$. - -## Exposing $productName$ via NodePort - -The simplest way to expose an application in Kubernetes is via a `NodePort` service. In this configuration, we create the $productName$ service] and identify `type: NodePort` instead of `LoadBalancer`. Kubernetes will then create a service and assign that service a port to be exposed externally and direct traffic to $productName$ via the defined `port`. - -```yaml ---- -apiVersion: v1 -kind: Service -metadata: - name: ambassador -spec: - type: NodePort - ports: - - name: http - port: 8088 - targetPort: 8080 - nodePort: 30036 # Optional: Define the port you would like exposed - protocol: TCP - selector: - service: ambassador -``` - -Using a `NodePort` leaves $productName$ isolated from the host network, allowing the Kubernetes service to handle routing to $productName$ pods. You can drop-in this YAML to replace the `LoadBalancer` service in the [YAML installation guide](../yaml-install) and use `http://:/` as the host for requests. - -## Exposing $productName$ via host network - -When running $productName$ on a bare metal install of Kubernetes, you have the option to configure $productName$ pods to use the network of the host they are running on. This method allows you to bind $productName$ directly to port 80 or 443 so you won't need to identify the port in requests. - -i.e `http://:/` becomes `http:///` - -This can be configured by setting `hostNetwork: true` in the $productName$ deployment. `dnsPolicy: ClusterFirstWithHostNet` will also need to set to tell $productName$ to use *KubeDNS* when attempting to resolve mappings. - -```diff ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: ambassador -spec: - replicas: 1 - selector: - matchLabels: - service: ambassador - template: - metadata: - annotations: - sidecar.istio.io/inject: "false" - labels: - service: ambassador - app.kubernetes.io/managed-by: getambassador.io - spec: -+ hostNetwork: true -+ dnsPolicy: ClusterFirstWithHostNet - serviceAccountName: ambassador - containers: - - name: ambassador - image: docker.io/datawire/ambassador:$version$ - resources: - limits: - cpu: 1 - memory: 400Mi - requests: - cpu: 200m - memory: 100Mi - env: - - name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace - livenessProbe: - httpGet: - path: /ambassador/v0/check_alive - port: 8877 - initialDelaySeconds: 30 - periodSeconds: 3 - readinessProbe: - httpGet: - path: /ambassador/v0/check_ready - port: 8877 - initialDelaySeconds: 30 - periodSeconds: 3 - restartPolicy: Always -``` - -This configuration does not require a defined $productName$ service, so you can remove that service if you have defined one. - -**Note:** Before configuring $productName$ with this method, consider some of the functionality that is lost by bypassing the Kubernetes service including only having one $productName$ able to bind to port 8080 or 8443 per node and losing any load balancing that is typically performed by Kubernetes services. diff --git a/content/en/docs/pre-release/topics/install/convert-to-v3alpha1.md b/content/en/docs/pre-release/topics/install/convert-to-v3alpha1.md deleted file mode 100644 index 2d8dfb79..00000000 --- a/content/en/docs/pre-release/topics/install/convert-to-v3alpha1.md +++ /dev/null @@ -1,275 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Convert Configuration to `getambassador.io/v3alpha1` - -Once your $productName$ $version$ installation is running, it is **strongly recommended** that -you convert your existing configuration resources from `getambassador.io/v2` to -`getambassador.io/v3alpha1`. - - - While it is not necessary to convert all your resources to getambassador.io/v3alpha1 - immediately, you should ultimately update them all for full functionality with $productName$ - - -In general, the best way to convert any resource is to start with `kubectl get`: using -`kubectl get -o yaml` on any `getambassador.io/v2` resource will cause $productName$ to -translate it to a `getambassador.io/v3alpha1` resource. You can then verify that the -`getambassador.io/v3alpha1` resource looks correct and re-apply it, which will convert the -stored copy to `getambassador.io/v3alpha1`. - -As you do the conversion, here are the things to bear in mind: - -## 1. `ambassador_id` must be an array, not a simple string. - -`getambassador.io/v2` allowed `ambassador_id` to be either an array of strings, or a simple -string. In `getambassador.io/v3alpha1`, only the array form is supported: instead of -`ambassador_id: "foo"`, use `ambassador_id: [ "foo" ]`. This applies to all $productName$ -resources, and is supported by all versions of Ambassador 1.X. - -## 2. You must have a `Listener` for each port on which $productName$ should listen. - - - Learn more about Listener - - -`Listener` is **mandatory**. Defining your own `Listener`(s) allows you to carefully -tailor the set of ports you actually need to use, and exactly which `Host` resources -are matched with them (see below). - -## 3. `Listener`, `Host`, and `Mapping` must be explicit about how they associate. - -You need to have `Listener`s, `Host`s, and `Mapping`s correctly associated with each other for $productName$ 2.X configuration. - -### 3.1. `Listener` and `Host` are associated through `Listener.hostBinding` - - - Learn more about Listener
- Learn more about Host - - -In a `Listener`, the `hostBinding` controls whether a given `Host` is associated with that `Listener`, as discussed in the [`Listener`](../../running/listener) documentation. -**The recommended setting is using `hostBinding.selector`** to choose only `Host`s that have a defined -Kubernetes label: - -```yaml -hostBinding: - selector: - matchLabels: - my-listener: listener-8080 -``` - -The above example shows a `Listener` configured to associate only with `Host`s that have a `my-listener: listener-8080` label. - -For migration purposes, it is possible to have a `Listener` associate with all of the `Host`s. This is not recommended for production environments, however, as it can resulting confusing behavior with large numbers of `Host`s, and it -can also result in larger Envoy configurations that slow reconfiguration. - -```yaml -hostBinding: - namespace: - from: ALL -``` - -but **this is not recommended in production**. Allowing every `Host` to associate -with every `Listener` can result in confusing behavior with large numbers of `Host`s, and it -can also result in larger Envoy configurations that slow reconfiguration. - -### 3.2. `Host` and `Mapping` are associated through `Host.mappingSelector` - - -In $productName$ 1.X, `Mapping`s were nearly always associated with every `Host`. Since this -tends to result in larger Envoy configurations that slow down reconfiguration, $productName$ 2.X -inverts this behavior: **`Host` and `Mapping` will not associate without explicit selection**. - -To have a `Mapping` associate with a `Host`, at least one of the following must hold: - -- Recommended: The `Host` must define a `mappingSelector` that matches a `label` on the `Mapping`. -- Alternately, the `Mapping` must define `hostname` that matches the `hostname` of the `Host`. - (Note that the `hostname` of both `Host` and `AmbasssadorMapping` is a DNS glob.) - -If the `Host` defines a `mappingSelector` and the `Mapping` also defines a `hostname`, both must match. - -As a migration aid: - -- A `Mapping` with a `hostname` of `"*"` will associate with any `Host` that -has no `mappingSelector`, and -- A `v3alpha1` `Mapping` will honor `host` if `hostname` is not present. - - - Learn more about Host
- Learn more about Mapping - - - - A Mapping that specifies host_regex: true is associated with  - all Hosts. This is generally far less desirable than using hostname - with a DNS glob. - - - - Support for host and host_regex will be removed before - v3alpha1 is promoted to v3. - - -## 4. Use `Host` to terminate TLS - - - Learn more about Host
- Learn more about TLSContext - - -In $productName$ 1.X, simply creating a `TLSContext` is sufficient to terminate TLS, but in -2.X you _must_ use a `Host`. The minimal setup to terminate TLS is now something like this: - -```yaml ---- -apiVersion: v1 -kind: Secret -metadata: - name: my-secret -type: kubernetes.io/tls -data: - tls.crt: base64-PEM - tls.key: base64-PEM ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: my-host -spec: - hostname: host.example.com - tlsSecret: my-secret -``` - -In the example above, TLS is terminated for `host.example.com`. A `TLSContext` is still right way to share data -about TLS configuration across `Host`s: set both `tlsSecret` and `tlsContext` in the `Host`. - -## 5. `Mapping` should use `hostname` if possible - - - Learn more about Mapping - - -The `getambassador.io/v3alpha1` `Mapping` introduces the new `hostname` element, which is always -a DNS glob. Using `hostname` instead of `host` is **strongly recommended** unless you absolutely -require regular expression matching: - -- if `host` is being used for an exact match, simply rename `host` to `hostname`. -- if `host` is being used for a regex that effects a prefix or suffix match, rename it - to `hostname` and rewrite the regex into a DNS glob, e.g. `host: .*\.example\.com` would become - `hostname: *.example.com`. - -Additionally, when `hostname` is used, the `Mapping` will be associated with a `Host` only -if `hostname` matches the hostname of the `Host`. If the `Host`'s `selector` is also set, -both the `selector` and the hostname must line up. - - - An 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. - - -## 6. `Mapping` added headers must not be simple strings - - - Learn more about Mapping - - -The `getambassador.io/v2` `Mapping` supported strings and dictionaries for `add_request_headers` and -`add_response_headers`, for example: - -```yaml -add_request_headers: - X-Add-String: bar - X-Add-Dict: - value: bar -``` - -In `getambassador.io/v2`, both `X-Add-String` and `X-Add-Dict` will be added with the value `bar`. - -The string form - shown with `X-Add-String` - is not supported in `getambassador.io/v3alpha1`. Use the -dictionary form instead (which works in both `getambassador.io/v2` and `getambassador.io/v3alpha1`). - -## 7. `Mapping` `headers` and `query_parameters` must not be `true` - - - Learn more about Mapping - - -`headers` and `query_parameters` in a `Mapping` control header matches and query-parameter matches. In -`getambassador.io/v2`, they support both strings and dictionaries, and each has a `_regex` variant. -For example: - - ```yaml - headers: - x-exact-match: foo - x-existence-match: true - headers_regex: - x-regex-match: "fo.*o" - ``` - -In this example, the `Mapping` requires the `x-exact-match` header to have the value `foo`, the -`x-regex-match` whose value starts with `fo` and ends with `o`. However, `x-existence-match` requires -simply that the `x-existence-match` header exists. - -In `getambassador.io/v3alpha1`, the `true` value for an existence match is not supported. Instead, -use `headers_regex` for the same header with value of `.*`. This is fully supported in 1.k) - -`query_parameters` and `query_parameters_regex` work exactly like `headers` and `headers_reex`. - -## 8. `Mapping` `labels` must be converted to new syntax - - - Learn more about Mapping - - -In `getambassador.io/v2`, the `labels` element in a `Mapping` supported several different types of -data. In `getambassador.io/v3alpha1`, all labels must have the same type, so labels must be converted -to the new syntax: - -| `getambassador.io/v2` | `getambassador.io/v3alpha1` | -| -------------------------------- | ----------------------------------------------------------- | -| `source_cluster` | `{ source_cluster: { key: source_cluster } }` | -| `destination_cluster` | `{ destination_cluster: { key: destination_cluster }` } | -| `remote_address` | `{ remote_address: { key: remote_address } }` | -| `{ my_key: { header: my_hdr } }` | `{ generic_key: { value: my_val } }` | -| `{ my_val }` | `{ generic_key: { value: my_val } }` | -| `{ my_key: { header: my_hdr } }` | `{ request_headers: { key: my_key, header_name: my_hdr } }` | - -You can check the [Rate Limiting Labels documentation](../../using/rate-limits#attaching-labels-to-requests) -for more examples. - -## 9. `tls` cannot be `true` in `AuthService`, `Mapping`, `RateLimitService`, and `TCPMapping` - - - Learn more about AuthService
- Learn more about Mapping
- Learn more about RateLimitService
- Learn more about TCPMapping - - -The `tls` element in `AuthService`, `Mapping`, `RateLimitService`, and `TCPMapping` controls TLS -origination. In `getambassador.io/v2`, it may be a string naming a `TLSContext` to use to determine -which client certificate is sent, or the boolean value `true` to request TLS origination with no -cluent certificate being sent. - -In `getambassador.io/v3alpha1`, only the string form is supported. To originate TLS with no client -certificate (the semantic of `tls: true`), omit the `tls` element and prefix the `service` with -`https://`. Note that `TCPMapping` in `getambassador.io/v2` does not support the `https://prefix`. - -## 10. Some `Module` settings have moved or changed - - - Learn more about Listener - - -A few settings have moved from the `Module` in 2.0. Make sure you review the following settings -and move them to their new locations if you are using them in a `Module`: - -- Configuration for the `PROXY` protocol is part of the `Listener` resource in $productName$ 2.0, -so the `use_proxy_protocol` element of the `ambassador` `Module` is no longer supported. - -- `xff_num_trusted_hops` has been removed from the `Module`, and its functionality has been moved -to the `l7Depth` setting in the `Listener` resource. - -- It is no longer possible to configure TLS using the `tls` element of the `Module`. Its -functionality is fully covered by the `TLSContext` resource. diff --git a/content/en/docs/pre-release/topics/install/docker.md b/content/en/docs/pre-release/topics/install/docker.md deleted file mode 100644 index e430a55c..00000000 --- a/content/en/docs/pre-release/topics/install/docker.md +++ /dev/null @@ -1,73 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Run the demo with Docker - -In this Docker quickstart guide, we'll get $productName$ running locally -with a demo configuration. In the next section, we'll then walk through how to -deploy $productName$ in Kubernetes with a custom configuration. - -## 1. Running the demo configuration - -By default, $productName$ uses a demo configuration to show some of its basic features. Get it running with Docker, and expose $productName$ on port 8080: - -``` -docker run -it -p 8080:8080 --name=$productDeploymentName$ --rm docker.io/emissaryingress/emissary:$version$ --demo -``` - -## 2. $productName$'s diagnostics - -$productName$ provides live diagnostics viewable with a web browser. While this would normally not be exposed to the public network, the Docker demo publishes the diagnostics service at the following URL: - -`http://localhost:8080/ambassador/v0/diag/` - -You'll have to authenticate to view this page: use the username `admin`, -password `admin` (obviously this would be a poor choice in the real world!). -We'll talk more about authentication shortly. - -To access the Diagnostics page with authentication, use `curl http://localhost:8080/ambassador/v0/diag/ -u admin:admin` - -Some of the most important information - your $productName$ version, how recently $productName$'s configuration was updated, and how recently Envoy last reported status to $productName$ - is right at the top. The diagnostics overview can show you what it sees in your configuration map, and which Envoy objects were created based on your configuration. - -## 3. The Quote service - -Since $productName$ is a comprehensive, self-service edge stack, its primary purpose is to provide access and control to microservices for the teams that manage them. The demo is preconfigured with a mapping that connects the `/qotm/` resource to the "Quote" service -- a demo service that supplies quotations. You can try it out by opening - -`http://localhost:8080/qotm/` - -in your browser, or from the command line as - -``` -curl -L 'http://localhost:8080/qotm/?json=true' -``` - -This request will route to the `qotm` service at `demo.getambassador.io`, and return a random quote. - -You can see details of the mapping by clicking the blue `http://localhost:8080/qotm/` link at the very bottom of the `Ambassador Route Table` in the diagnostics overview. - -## 4. Authentication - -On the diagnostic overview, you can also see that $productName$ is configured to do authentication -- in the middle of the overview page, you'll see the `Ambassador Services In Use` section, and you can click the `tcp://127.0.0.1:5050` link for details on the `AuthService` configuration. This demo auth service is running inside the Docker container with $productName$ and the Quote service, and $productName$ uses it to mediate access to everything behind $productName$. - -You saw above that access to the diagnostic overview required you to authenticate as an administrator. Getting a random quote does not require authentication, but to get a specific quote, you'll have to authenticate as a demo user. To see this in action, open - -`http://localhost:8080/qotm/quote/5` - -in your browser. From the command line, you can see that: - -``` -curl -Lv 'http://localhost:8080/qotm/quote/5?json=true' -``` - -will return a 401, but - -``` -curl -Lv -u username:password 'http://localhost:8080/qotm/quote/5?json=true' -``` - -will succeed. (Note that that's literally "username" and "password" -- the demo auth service is deliberately not very secure!) - -Note that it's up to the auth service to decide what needs authentication -- teaming $productName$ with an authentication service can be as flexible or strict as you need it to be. - -## Next steps - -We've just walked through some of the core features of $productName$ in a local configuration. To see $productName$ in action on Kubernetes, check out the [Installation Guide](../). diff --git a/content/en/docs/pre-release/topics/install/helm.md b/content/en/docs/pre-release/topics/install/helm.md deleted file mode 100644 index a807d335..00000000 --- a/content/en/docs/pre-release/topics/install/helm.md +++ /dev/null @@ -1,104 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Install with Helm - - - - To migrate from $productName$ 1.X to $productName$ 2.X, see the - [$productName$ migration matrix](../migration-matrix/). This guide - **will not work** for that, due to changes to the configuration - resources used for $productName$ 2.X. - - - -[Helm](https://helm.sh) is a package manager for Kubernetes that automates the release and management of software on Kubernetes. $productName$ can be installed via a Helm chart with a few simple steps, depending on if you are deploying for the first time, upgrading $productName$ from an existing installation, or migrating from $productName$. - -## Before you begin - -The $productName$ Helm chart is hosted by Datawire and published at `https://app.getambassador.io`. - -Start by adding this repo to your helm client with the following command: - -``` -helm repo add datawire https://app.getambassador.io -helm repo update -``` - -## Install with Helm - -When you run the Helm chart, it installs $productName$. - -1. Install the $productName$ CRDs. - - Before installing $productName$ $version$ itself, you must configure your - Kubernetes cluster to support the `getambassador.io/v3alpha1` and `getambassador.io/v2` - configuration resources. This is required. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. Install the $productName$ Chart with the following command: - - ``` - helm install -n $productNamespace$ --create-namespace \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - -3. Next Steps - - $productName$ shold now be successfully installed and running, but in order to get started deploying Services and test routing to them you need to configure a few more resources. - - - [The `Listener` Resource](../../running/listener/) is required to configure which ports the $productName$ pods listen on so that they can begin responding to requests. - - [The `Mapping` Resouce](../../using/intro-mappings/) is used to configure routing requests to services in your cluster. - - [The `Host` Resource](../../running/host-crd/) configures TLS termination for enablin HTTPS communication. - - Explore how $productName$ [configures communication with clients](../../../howtos/configure-communications) - - - We strongly recommend following along with our Quickstart Guide to get started by creating a Listener, deploying a simple service to test with, and setting up a Mapping to route requests from $productName$ to the demo service. - - - - $productName$ $version$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - -For more advanced configuration and details about helm values, -[please see the helm chart.](https://artifacthub.io/packages/helm/datawire/emissary-ingress/) - -## Upgrading an existing installation - -See the [migration matrix](../migration-matrix) for instructions about upgrading -$productName$. - - diff --git a/content/en/docs/pre-release/topics/install/index.less b/content/en/docs/pre-release/topics/install/index.less deleted file mode 100644 index bc649e7c..00000000 --- a/content/en/docs/pre-release/topics/install/index.less +++ /dev/null @@ -1,57 +0,0 @@ -@media (max-width: 769px) { - #index-installContainer { - flex-direction: column; - } - .index-dropdown { - width: auto; - } - .index-dropBtn { - width: 100%; - } -} - -.index-dropBtn { - background-color: #8e77ff; - color: white; - padding: 10px; - font-size: 16px; - border: none; - margin-top: -20px; -} - -.index-dropdown { - position: relative; - display: inline-block; -} - -.index-dropdownContent { - display: none; - position: absolute; - background-color: #f1f1f1; - width: 100%; - box-shadow: 0px 8px 16px 0px rgba(0, 0, 0, 0.2); - z-index: 1; -} - -.index-dropdownContent a { - color: black; - padding: 12px 16px; - text-decoration: none; - display: block; -} - -.index-dropdownContent a:hover { - background-color: #ddd; -} - -.index-dropdown:hover .index-dropdownContent { - display: block; -} - -.index-dropdown:hover .index-dropBtn { - background-color: #5f3eff; -} - -#index-installContainer { - display: flex; -} diff --git a/content/en/docs/pre-release/topics/install/index.md b/content/en/docs/pre-release/topics/install/index.md deleted file mode 100644 index 40fa95fd..00000000 --- a/content/en/docs/pre-release/topics/install/index.md +++ /dev/null @@ -1,47 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; -import './index.less' - -# Installing $productName$ - -## 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/content/en/docs/pre-release/topics/install/migrate-to-2-alternate.md b/content/en/docs/pre-release/topics/install/migrate-to-2-alternate.md deleted file mode 100644 index edc42916..00000000 --- a/content/en/docs/pre-release/topics/install/migrate-to-2-alternate.md +++ /dev/null @@ -1,40 +0,0 @@ ---- - 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/content/en/docs/pre-release/topics/install/migrate-to-3-alternate.md b/content/en/docs/pre-release/topics/install/migrate-to-3-alternate.md deleted file mode 100644 index 3b9df0c1..00000000 --- a/content/en/docs/pre-release/topics/install/migrate-to-3-alternate.md +++ /dev/null @@ -1,36 +0,0 @@ -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/content/en/docs/pre-release/topics/install/migration-matrix.md b/content/en/docs/pre-release/topics/install/migration-matrix.md deleted file mode 100644 index a9538207..00000000 --- a/content/en/docs/pre-release/topics/install/migration-matrix.md +++ /dev/null @@ -1,46 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrading $productName$ - - - Read the instructions below before making any changes to your cluster! - - -There are currently multiple paths for upgrading $productName$, depending on what version you're currently -running, what you want to be running, and whether you installed $productName$ using [Helm](../helm) or -YAML. - -(To check out if you installed $productName$ using Helm, run `helm list --all` and see if -$productName$ is listed. If so, you installed using Helm.) - - - Read the instructions below before making any changes to your cluster! - - -## If you are currently running $AESproductName$ - -See the [instructions on updating $AESproductName$](/docs/edge-stack/$aesDocsVersion$/topics/install/migration-matrix/). - -## If you installed $OSSproductName$ using Helm - -| If you're running. | You can upgrade to | -|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------| -| $OSSproductName$ $version$ | [$AESproductName$ $aesVersion$](/docs/edge-stack/$aesDocsVersion$/topics/install/upgrade/helm/emissary-3.8/edge-stack-3.X/) | -| $OSSproductName$ 3.7.X | [$OSSproductName$ $version$](../upgrade/helm/emissary-3.7/emissary-3.X) | -| $OSSproductName$ $versionTwoX$ | [$OSSproductName$ $version$](../upgrade/helm/emissary-2.5/emissary-3.X) | -| $OSSproductName$ 2.4.X | [$OSSproductName$ $versionTwoX$](../upgrade/helm/emissary-2.4/emissary-2.X) | -| $OSSproductName$ 2.0.5 | [$OSSproductName$ $versionTwoX$](../upgrade/helm/emissary-2.0/emissary-2.X) | -| $OSSproductName$ $versionOneX$ | [$OSSproductName$ $versionTwoX$](../upgrade/helm/emissary-1.14/emissary-2.X) | -| $OSSproductName$ prior to $versionOneX$ | [$OSSproductName$ $versionOneX$](../../../../1.14/topics/install/upgrading) | - -## If you installed $OSSproductName$ manually by applying YAML - -| If you're running. | You can upgrade to | -|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------| -| $OSSproductName$ $version$ | [$AESproductName$ $aesVersion$](/docs/edge-stack/$aesDocsVersion$/topics/install/upgrade/yaml/emissary-3.8/edge-stack-3.X/) | -| $OSSproductName$ 3.7.X | [$OSSproductName$ $version$](../upgrade/yaml/emissary-3.7/emissary-3.X) | -| $OSSproductName$ $versionTwoX$ | [$OSSproductName$ $version$](../upgrade/yaml/emissary-2.5/emissary-3.X) | -| $OSSproductName$ 2.4.X | [$OSSproductName$ $versionTwoX$](../upgrade/yaml/emissary-2.4/emissary-2.X) | -| $OSSproductName$ 2.0.5 | [$OSSproductName$ $versionTwoX$](../upgrade/yaml/emissary-2.0/emissary-2.X) | -| $OSSproductName$ $versionOneX$ | [$OSSproductName$ $versionTwoX$](../upgrade/yaml/emissary-1.14/emissary-2.X) | -| $OSSproductName$ prior to $versionOneX$ | [$OSSproductName$ $versionOneX$](../../../../1.14/topics/install/upgrading) | diff --git a/content/en/docs/pre-release/topics/install/upgrade/helm/emissary-1.14/emissary-2.X.md b/content/en/docs/pre-release/topics/install/upgrade/helm/emissary-1.14/emissary-2.X.md deleted file mode 100644 index bd61fafc..00000000 --- a/content/en/docs/pre-release/topics/install/upgrade/helm/emissary-1.14/emissary-2.X.md +++ /dev/null @@ -1,312 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 1.14.X (Helm) - - - This guide covers migrating from $productName$ 1.14.X to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -We're pleased to introduce $productName$ $versionTwoX$! The 2.X family introduces a number of -changes to allow $productName$ to more gracefully handle larger installations (including -multitenant or multiorganizational installations), reduce memory footprint, and improve -performance. In keeping with [SemVer](https://semver.org), $productName$ 2.X introduces -some changes that aren't backward-compatible with 1.X. These changes are detailed in -[Major Changes in $productName$ 2.X](../../../../../../about/changes-2.x/). - -## Migration Overview - - - Read the migration instructions below before making any changes to your - cluster! - - -The recommended strategy for migration is to run $productName$ 1.14 and $productName$ -$versionTwoX$ side-by-side in the same cluster. This gives $productName$ $versionTwoX$ -and $productName$ 1.14 access to all the same configuration resources, with some -important caveats: - -1. **$productName$ 1.14 will not see any `getambassador.io/v3alpha1` resources.** - - This is intentional; it provides a way to apply configuration only to - $productName$ $versionTwoX$, while not interfering with the operation of your - $productName$ 1.14 installation. - -2. **If needed, you can use labels to further isolate configurations.** - - If you need to prevent your $productName$ $versionTwoX$ installation from - seeing a particular bit of $productName$ 1.14 configuration, you can apply - a Kubernetes label to the configuration resources that should be seen by - your $productName$ $versionTwoX$ installation, then set its - `AMBASSADOR_LABEL_SELECTOR` environment variable to restrict its 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$ $versionTwoX$, then set - `AMBASSADOR_LABEL_SELECTOR=version-two=true` in its Deployment. - -3. **Be careful about label selectors on Kubernetes Services!** - - If you have services in $productName$ 1.14 that use selectors that will match - Pods from $productName$ $versionTwoX$, traffic will be erroneously split between - $productName$ 1.14 and $productName$ $versionTwoX$. The labels used by $productName$ - $versionTwoX$ include: - - ```yaml - app.kubernetes.io/name: emissary-ingress - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/part-of: emissary-ingress - app.kubernetes.io/managed-by: getambassador.io - product: aes - profile: main - ``` - -4. **Be careful to only have one $productName$ Agent running at a time.** - - The $productName$ Agent is responsible for communications between - $productName$ and Ambassador Cloud. If multiple versions of the Agent are - running simultaneously, Ambassador Cloud could see conflicting information - about your cluster. - - The best way to avoid multiple agents when installing with Helm is to use - `--set agent.enabled=false` to tell Helm not to install a new Agent with - $productName$ $versionTwoX$. Once testing is done, you can switch Agents safely. - -You can also migrate by [installing $productName$ $versionTwoX$ in a separate cluster](../../../../migrate-to-2-alternate). -This permits absolute certainty that your $productName$ 1.14 configuration will not be -affected by changes meant for $productName$ $versionTwoX$, and it eliminates concerns about -ACME, but it is more effort. - -## Side-by-Side Migration Steps - -Migration is a seven-step process: - -1. **Make sure that older configuration resources are not present.** - - $productName$ 2.X does not support `getambassador.io/v0` or `getambassador.io/v1` - resources, and Kubernetes will not permit removing support for CRD versions that are - still in use for stored resources. To verify that no resources older than - `getambassador.io/v2` are active, run - - ``` - kubectl get crds -o 'go-template={{range .items}}{{.metadata.name}}={{.status.storedVersions}}{{"\n"}}{{end}}' | fgrep getambassador.io - ``` - - If `v1` is present in the output, **do not begin migration.** The old resources must be - converted to `getambassador.io/v2` and the `storedVersion` information in the cluster - must be updated. If necessary, contact Ambassador Labs on [Slack](http://a8r.io/slack) - for more information. - -2. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you must configure your - Kubernetes cluster to support its new `getambassador.io/v3alpha1` configuration - resources. Note that `getambassador.io/v2` resources are still supported, but **you - must install support for `getambassador.io/v3alpha1`** to run $productName$ $versionTwoX$, - even if you intend to continue using only `getambassador.io/v2` resources for some - time. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -3. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, you need to install $productName$ $versionTwoX$ itself - **in the same namespace as your existing $productName$ 1.14 installation**. It's important - to use the same namespace so that the two installations can see the same secrets, etc. - - Start by making sure that your `emissary` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Typically, $productName$ 1.14 was installed in the `ambassador` namespace. If you installed - $productName$ 1.14 in a different namespace, change the namespace in the commands below. - - - If you do not need to set `AMBASSADOR_LABEL_SELECTOR`: - - ```bash - helm install -n ambassador \ - --set agent.enabled=false \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - - - If you do need to set `AMBASSADOR_LABEL_SELECTOR`, use `--set`, for example: - - ```bash - helm install -n ambassador \ - --set agent.enabled=false \ - --set env.AMBASSADOR_LABEL_SELECTOR="version-two=true" \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 2.X. - Do not use the ambassador Helm chart. - - - - $productName$ $versionTwoX$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - -4. **Install `Listener`s and `Host`s as needed.** - - An important difference between $productName$ 1.14 and $productName$ $versionTwoX$ is the - new **mandatory** `Listener` CRD. Also, when running both installations side by side, - you will need to make sure that a `Host` is present for the new $productName$ $versionTwoX$ - Service. For example: - - ```bash - kubectl apply -f - < - Kubernetes will not allow you to have a 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.
-
- If you find that your $productName$ $versionTwoX$ installation and your $productName$ 1.14 - installation absolutely must have resources that are only seen by one version or the - other way, see overview section 2, "If needed, you can use labels to further isolate configurations". - - - **If you find that you need to roll back**, just reinstall your 1.14 CRDs and delete your - installation of $productName$ $versionTwoX$. - -6. **When ready, switch over to $productName$ $versionTwoX$.** - - You can run $productName$ 1.14 and $productName$ $versionTwoX$ side-by-side as long as you care - to. However, taking full advantage of $productName$ 2.X's capabilities **requires** - [updating your configuration to use `getambassador.io/v3alpha1` configuration resources](../../../../convert-to-v3alpha1), - since some useful features in $productName$ $versionTwoX$ are only available using - `getambassador.io/v3alpha1` resources. - - When you're ready to have $productName$ $versionTwoX$ handle traffic on its own, switch - your original $productName$ 1.14 Service to point to $productName$ $versionTwoX$. Use - `kubectl edit service ambassador` and change the `selectors` to: - - ``` - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/name: emissary-ingress - profile: main - ``` - - Repeat using `kubectl edit service ambassador-admin` for the `ambassador-admin` - Service. - -7. **Finally, install the $productName$ $versionTwoX$ Ambassador Agent.** - - First, scale the 1.14 agent to 0: - - ``` - kubectl scale -n ambassador deployment/ambassador-agent --replicas=0 - ``` - - Once that's done, install the new Agent. **Note that if you needed to set - `AMBASSADOR_LABEL_SELECTOR`, you must add that to this `helm upgrade` command.** - - ```bash - helm upgrade -n ambassador \ - --set agent.enabled=true \ - $productHelmName$ datawire/$productHelmName$ \ - kubectl rollout status -n $productNamespace$ deployment/$productDeploymentName$ -w - ``` - -Congratulations! At this point, $productName$ $versionTwoX$ is fully running and it's safe to remove the `ambassador` and `ambassador-agent` Deployments: - -``` -kubectl delete deployment/ambassador deployment/ambassador-agent -``` - -Once $productName$ 1.14 is no longer running, you may [convert](../../../../convert-to-v3alpha1) -any remaining `getambassador.io/v2` resources to `getambassador.io/v3alpha1`. -You may also want to redirect DNS to the `edge-stack` Service and remove the -`ambassador` Service. diff --git a/content/en/docs/pre-release/topics/install/upgrade/helm/emissary-2.0/emissary-2.X.md b/content/en/docs/pre-release/topics/install/upgrade/helm/emissary-2.0/emissary-2.X.md deleted file mode 100644 index c0a392f1..00000000 --- a/content/en/docs/pre-release/topics/install/upgrade/helm/emissary-2.0/emissary-2.X.md +++ /dev/null @@ -1,75 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.0.5 (Helm) - - - This guide covers migrating from $productName$ 2.0.5 to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster; Helm will not do this for you. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, use Helm to install $productName$ $versionTwoX$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 2.X. - Do not use the ambassador Helm chart. - diff --git a/content/en/docs/pre-release/topics/install/upgrade/helm/emissary-2.4/emissary-2.X.md b/content/en/docs/pre-release/topics/install/upgrade/helm/emissary-2.4/emissary-2.X.md deleted file mode 100644 index 3e44b511..00000000 --- a/content/en/docs/pre-release/topics/install/upgrade/helm/emissary-2.4/emissary-2.X.md +++ /dev/null @@ -1,75 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.4.Z (Helm) - - - This guide covers migrating from $productName$ 2.4.Z to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster; Helm will not do this for you. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, use Helm to install $productName$ $versionTwoX$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 2.X. - Do not use the ambassador Helm chart. - diff --git a/content/en/docs/pre-release/topics/install/upgrade/helm/emissary-2.5/emissary-3.X.md b/content/en/docs/pre-release/topics/install/upgrade/helm/emissary-2.5/emissary-3.X.md deleted file mode 100644 index d8439c5a..00000000 --- a/content/en/docs/pre-release/topics/install/upgrade/helm/emissary-2.5/emissary-3.X.md +++ /dev/null @@ -1,153 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.5.Z (Helm) - - - This guide covers migrating from $productName$ 2.5.Z to $productName$ $version$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - - - Make sure that you have updated any 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$. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -$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. - -### Resources to check before migrating to $version$. - -$productName$ 3.X has been upgraded from Envoy 1.17.X to Envoy 1.22 which removed support for the Envoy V2 Transport Protocol. This means all `AuthService`, `RatelimitService`, and `LogServices` must be updated to use the V3 Protocol. Additionally support for some of the runtime bootstrap flags has been removed. - -You can refer to the [Major changes in $productName$ 3.x](../../../../../../about/changes-3.y/) guide for an overview of the changes. - -1. $productName$ 3.2 fixed a bug with `Host.spec.selector\mappingSelector` and `Listener.spec.selector` not being properly enforced. - In previous versions, if only a single label from the selector was present on the resource then they would be associated. Additionally, when associating `Hosts` with `Mappings`, if the `Mapping` configured a `hostname` that matched the `hostname` of the `Host` then they would be associated regardless of the configuration of the `selector\mappingSelector` on the `Host`. - - Before upgrading, review your Ambassador resources, and if you make use of the selectors, ensure that every other resource you want it to be associated with contains all the required labels. - - The environment variable `DISABLE_STRICT_LABEL_SELECTORS` can be set to `"true"` on the $productName$ deployment to revert to the - old incorrect behavior to help prevent any configuration issues after upgrading in the event that not all manifests making use of the selectors have been corrected yet. - - For more information on `DISABLE_STRICT_LABEL_SELECTORS` see the [Environment Variables page](../../../../../running/environment). - -2. Check Transport Protocol usage on all resources before migrating. - - The `AuthService`, `RatelimitService`, and `LogServices` 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. - - `protocol_version` should be updated to `v3` for all of the above resources while still running $productName$ $versionTwoX$. As of version `2.3.z`+, support for `protocol_version` `v2` and `v3` is supported in order to allow migration from `protocol_version` `v2` to `v3` before upgrading to $productName$ $version$ where support for `v2` is removed. - - Upgrading any application code for your own implementations of these services is very straightforward. - - The following imports simply need to be updated to switch from Envoy's Transport Protocol `v2` to `v3`, and then the configuration for these resources can be updated to add the `protocl_version: "v3"` when the updated service is deployed. - - `v2` Imports: - ```golang - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" - ``` - - `v3` Imports: - ```golang - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" - ``` - -3. Check removed runtime changes - - ```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, - - # Developers 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, - ``` - -4. Support for LightStep tracing driver removed - - - As of $productName$ 3.4.Z, the LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read before upgrading. - - -$productName$ 3.4 is based on Envoy 1.24.1 which removed support for the `LightStep` tracing driver. The team at LightStep and the maintainers of Envoy-Proxy recommend that users instead leverage the OpenTelemetry Collector to send tracing information to LightStep. We have written a guide which can be found here Distributed Tracing with OpenTelemetry and Lightstep that outlines how to set this up. **It is important that you follow this upgrade path prior to upgrading or you will drop tracing data.** - -## Migration Steps - -Migration is a two-step process: - -1. **Install new CRDs.** - - After reviewing the changes in 3.x and confirming that you are ready to upgrade, the process is the same as upgrading minor versions - in previous version of $productName$ and does not require the complex migration steps that the migration from 1.x tto 2.x required. - - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $version$.** - - After installing the new CRDs, use Helm to install $productName$ $version$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 3.Y. - diff --git a/content/en/docs/pre-release/topics/install/upgrade/helm/emissary-3.4/emissary-3.X.md b/content/en/docs/pre-release/topics/install/upgrade/helm/emissary-3.4/emissary-3.X.md deleted file mode 100644 index f5b4e26d..00000000 --- a/content/en/docs/pre-release/topics/install/upgrade/helm/emissary-3.4/emissary-3.X.md +++ /dev/null @@ -1,87 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 3.4.Z (Helm) - - - This guide covers migrating from $productName$ 3.4.Z to $productName$ $version$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -### Resources to check before migrating to $version$. - - - As of $productName$ 3.4.Z, the LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read below before upgrading. - - -$productName$ 3.4 has been upgraded from Envoy 1.23 to Envoy 1.24.1 which removed support for the `LightStep` tracing driver. The team at LightStep and the maintainers of Envoy-Proxy recommend that users instead leverage the OpenTelemetry Collector to send tracing information to LightStep. We have written a guide which can be found here Distributed Tracing with OpenTelemetry and Lightstep that outlines how to set this up. **It is important that you follow this upgrade path prior to upgrading or you will drop tracing data.** - -## Migration Steps - -Migration is a two-step process: - -1. **Install new CRDs.** - - After reviewing the changes in 3.x and confirming that you are ready to upgrade, the process is the same as upgrading minor versions - in previous version of $productName$ and does not require the complex migration steps that the migration from 1.x tto 2.x required. - - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $version$.** - - After installing the new CRDs, use Helm to install $productName$ $version$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 3.Y. - diff --git a/content/en/docs/pre-release/topics/install/upgrade/helm/emissary-3.7/emissary-3.X.md b/content/en/docs/pre-release/topics/install/upgrade/helm/emissary-3.7/emissary-3.X.md deleted file mode 100644 index ffa7f19d..00000000 --- a/content/en/docs/pre-release/topics/install/upgrade/helm/emissary-3.7/emissary-3.X.md +++ /dev/null @@ -1,81 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 3.7.Z (Helm) - - - This guide covers migrating from $productName$ 3.7.Z to $productName$ $version$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation originally made using Helm. - If you did not install with Helm, see the YAML-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -### Resources to check before migrating to $version$. - -## Migration Steps - -Migration is a two-step process: - -1. **Install new CRDs.** - - After reviewing the changes in 3.x and confirming that you are ready to upgrade, the process is the same as upgrading minor versions - in the previous version of $productName$ and does not require the complex migration steps that the migration from 1.x to 2.x required. - - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $version$.** - - After installing the new CRDs, use Helm to install $productName$ $version$. Start by - making sure that your `datawire` Helm repo is set correctly: - - ```bash - helm repo remove datawire - helm repo add datawire https://app.getambassador.io - helm repo update - ``` - - Then, update your $productName$ installation in the `$productNamespace$` namespace. - If necessary for your installation (e.g. if you were running with - `AMBASSADOR_SINGLE_NAMESPACE` set), you can choose a different namespace. - - ```bash - helm upgrade -n $productNamespace$ \ - $productHelmName$ datawire/$productHelmName$ && \ - kubectl rollout status -n $productNamespace$ deployment/emissary-ingress -w - ``` - - - You must use the $productHelmName$ Helm chart for $productName$ 3.Y. - diff --git a/content/en/docs/pre-release/topics/install/upgrade/yaml/emissary-1.14/emissary-2.X.md b/content/en/docs/pre-release/topics/install/upgrade/yaml/emissary-1.14/emissary-2.X.md deleted file mode 100644 index eb1dcf6c..00000000 --- a/content/en/docs/pre-release/topics/install/upgrade/yaml/emissary-1.14/emissary-2.X.md +++ /dev/null @@ -1,282 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 1.14.X (YAML) - - - This guide covers migrating from $productName$ 1.14.X to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -We're pleased to introduce $productName$ $versionTwoX$! The 2.X family introduces a number of -changes to allow $productName$ to more gracefully handle larger installations (including -multitenant or multiorganizational installations), reduce memory footprint, and improve -performance. In keeping with [SemVer](https://semver.org), $productName$ 2.X introduces -some changes that aren't backward-compatible with 1.X. These changes are detailed in -[Major Changes in $productName$ 2.X](../../../../../../about/changes-2.x/). - -## Migration Overview - - - Read the migration instructions below before making any changes to your - cluster! - - -The recommended strategy for migration is to run $productName$ 1.14 and $productName$ -$versionTwoX$ side-by-side in the same cluster. This gives $productName$ $versionTwoX$ -and $productName$ 1.14 access to all the same configuration resources, with some -important caveats: - -1. **$productName$ 1.14 will not see any `getambassador.io/v3alpha1` resources.** - - This is intentional; it provides a way to apply configuration only to - $productName$ $versionTwoX$, while not interfering with the operation of your - $productName$ 1.14 installation. - -2. **If needed, you can use labels to further isolate configurations.** - - If you need to prevent your $productName$ $versionTwoX$ installation from - seeing a particular bit of $productName$ 1.14 configuration, you can apply - a Kubernetes label to the configuration resources that should be seen by - your $productName$ $versionTwoX$ installation, then set its - `AMBASSADOR_LABEL_SELECTOR` environment variable to restrict its 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$ $versionTwoX$, then set - `AMBASSADOR_LABEL_SELECTOR=version-two=true` in its Deployment. - -3. **Be careful about label selectors on Kubernetes Services!** - - If you have services in $productName$ 1.14 that use selectors that will match - Pods from $productName$ $versionTwoX$, traffic will be erroneously split between - $productName$ 1.14 and $productName$ $versionTwoX$. The labels used by $productName$ - $versionTwoX$ include: - - ```yaml - app.kubernetes.io/name: emissary-ingress - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/part-of: emissary-ingress - app.kubernetes.io/managed-by: getambassador.io - product: aes - profile: main - ``` - -4. **Be careful to only have one $productName$ Agent running at a time.** - - The $productName$ Agent is responsible for communications between - $productName$ and Ambassador Cloud. If multiple versions of the Agent are - running simultaneously, Ambassador Cloud could see conflicting information - about your cluster. - - The migration YAML used below to install $productName$ $versionTwoX$ will not - install a duplicate agent. If you are building your own YAML, make sure not - to include a duplicate agent. - -You can also migrate by [installing $productName$ $versionTwoX$ in a separate cluster](../../../../migrate-to-2-alternate). -This permits absolute certainty that your $productName$ 1.14 configuration will not be -affected by changes meant for $productName$ $versionTwoX$, and it eliminates concerns about -ACME, but it is more effort. - -## Side-by-Side Migration Steps - -Migration is a seven-step process: - -1. **Make sure that older configuration resources are not present.** - - $productName$ 2.X does not support `getambassador.io/v0` or `getambassador.io/v1` - resources, and Kubernetes will not permit removing support for CRD versions that are - still in use for stored resources. To verify that no resources older than - `getambassador.io/v2` are active, run - - ``` - kubectl get crds -o 'go-template={{range .items}}{{.metadata.name}}={{.status.storedVersions}}{{"\n"}}{{end}}' | fgrep getambassador.io - ``` - - If `v1` is present in the output, **do not begin migration.** The old resources must be - converted to `getambassador.io/v2` and the `storedVersion` information in the cluster - must be updated. If necessary, contact Ambassador Labs on [Slack](http://a8r.io/slack) - for more information. - -2. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you must configure your - Kubernetes cluster to support its new `getambassador.io/v3alpha1` configuration - resources. Note that `getambassador.io/v2` resources are still supported, but **you - must install support for `getambassador.io/v3alpha1`** to run $productName$ $versionTwoX$, - even if you intend to continue using only `getambassador.io/v2` resources for some - time. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -3. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, you need to install $productName$ $versionTwoX$ itself - **in the same namespace as your existing $productName$ 1.14 installation**. It's important - to use the same namespace so that the two installations can see the same secrets, etc. - - We publish two manifests for different namespaces. Use only the one that - matches the namespace into which you installed $productName$ 1.14: - - - [`emissary-emissaryns.yaml`] for the `emissary` namespace; or - - [`emissary-defaultns.yaml`] for the `default` namespace. - - If you installed $productName$ 1.14 into some other namespace, you'll need to - download one of the files and edit it to match your namespace. - - [`emissary-emissaryns.yaml`]: https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-emissaryns.yaml - [`emissary-defaultns.yaml`]: https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-defaultns.yaml - - **If you need to set `AMBASSADOR_LABEL_SELECTOR`**, you'll need to download - your chosen file and and edit it to do so. - - Assuming that you're using the `default` namespace: - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-defaultns.yaml && \ - kubectl rollout status -n default deployment/edge-stack -w - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - -4. **Install `Listener`s and `Host`s as needed.** - - An important difference between $productName$ 1.14 and $productName$ $versionTwoX$ is the - new **mandatory** `Listener` CRD. Also, when running both installations side by side, - you will need to make sure that a `Host` is present for the new $productName$ $versionTwoX$ - Service. For example: - - ```bash - kubectl apply -f - < - Kubernetes will not allow you to have a 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.
-
- If you find that your $productName$ $versionTwoX$ installation and your $productName$ 1.14 - installation absolutely must have resources that are only seen by one version or the - other way, see overview section 2, "If needed, you can use labels to further isolate configurations". - - - **If you find that you need to roll back**, just reinstall your 1.14 CRDs and delete your - installation of $productName$ $versionTwoX$. - -6. **When ready, switch over to $productName$ $versionTwoX$.** - - You can run $productName$ 1.14 and $productName$ $versionTwoX$ side-by-side as long as you care - to. However, taking full advantage of $productName$ 2.X's capabilities **requires** - [updating your configuration to use `getambassador.io/v3alpha1` configuration resources](../../../../convert-to-v3alpha1), - since some useful features in $productName$ $versionTwoX$ are only available using - `getambassador.io/v3alpha1` resources. - - When you're ready to have $productName$ $versionTwoX$ handle traffic on its own, switch - your original $productName$ 1.14 Service to point to $productName$ $versionTwoX$. Use - `kubectl edit service ambassador` and change the `selectors` to: - - ``` - app.kubernetes.io/instance: emissary-ingress - app.kubernetes.io/name: emissary-ingress - profile: main - ``` - - Repeat using `kubectl edit service ambassador-admin` for the `ambassador-admin` - Service. - - -Congratulations! At this point, $productName$ $versionTwoX$ is fully running and it's safe to remove the `ambassador` and `ambassador-agent` Deployments: - -``` -kubectl delete deployment/ambassador deployment/ambassador-agent -``` - -Once $productName$ 1.14 is no longer running, you may [convert](../../../../convert-to-v3alpha1) -any remaining `getambassador.io/v2` resources to `getambassador.io/v3alpha1`. -You may also want to redirect DNS to the `edge-stack` Service and remove the -`ambassador` Service. diff --git a/content/en/docs/pre-release/topics/install/upgrade/yaml/emissary-2.0/emissary-2.X.md b/content/en/docs/pre-release/topics/install/upgrade/yaml/emissary-2.0/emissary-2.X.md deleted file mode 100644 index b16d046f..00000000 --- a/content/en/docs/pre-release/topics/install/upgrade/yaml/emissary-2.0/emissary-2.X.md +++ /dev/null @@ -1,65 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.0.5 (YAML) - - - This guide covers migrating from $productName$ 2.0.5 to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, upgrade $productName$ $versionTwoX$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/pre-release/topics/install/upgrade/yaml/emissary-2.4/emissary-2.X.md b/content/en/docs/pre-release/topics/install/upgrade/yaml/emissary-2.4/emissary-2.X.md deleted file mode 100644 index ec8b6a70..00000000 --- a/content/en/docs/pre-release/topics/install/upgrade/yaml/emissary-2.4/emissary-2.X.md +++ /dev/null @@ -1,67 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.4.Z (YAML) - - - This guide covers migrating from $productName$ 2.4.Z to $productName$ $versionTwoX$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading between minor -versions is straightforward. - -## Migration Steps - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $versionTwoX$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $versionTwoX$.** - - After installing the new CRDs, upgrade $productName$ $versionTwoX$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/pre-release/topics/install/upgrade/yaml/emissary-2.5/emissary-3.X.md b/content/en/docs/pre-release/topics/install/upgrade/yaml/emissary-2.5/emissary-3.X.md deleted file mode 100644 index ea3b7bc9..00000000 --- a/content/en/docs/pre-release/topics/install/upgrade/yaml/emissary-2.5/emissary-3.X.md +++ /dev/null @@ -1,144 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.5.Z (YAML) - - - This guide covers migrating from $productName$ 2.5.Z to $productName$ $version$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - - - Make sure that you have updated any 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$. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading -between versions is straightforward. - -$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. - -### Resources to check before migrating to $version$. - -$productName$ 3.X has been upgraded from Envoy 1.17.X to Envoy 1.22 which removed support for the Envoy V2 Transport Protocol. This means all `AuthService`, `RatelimitService`, and `LogServices` must be updated to use the V3 Protocol. Additionally support for some of the runtime bootstrap flags has been removed. - -You can refer to the [Major changes in $productName$ 3.x](../../../../../../about/changes-3.y/) guide for an overview of the changes. - -1. $productName$ 3.2 fixed a bug with `Host.spec.selector\mappingSelector` and `Listener.spec.selector` not being properly enforced. - In previous versions, if only a single label from the selector was present on the resource then they would be associated. Additionally, when associating `Hosts` with `Mappings`, if the `Mapping` configured a `hostname` that matched the `hostname` of the `Host` then they would be associated regardless of the configuration of the `selector\mappingSelector` on the `Host`. - - Before upgrading, review your Ambassador resources, and if you make use of the selectors, ensure that every other resource you want it to be associated with contains all the required labels. - - The environment variable `DISABLE_STRICT_LABEL_SELECTORS` can be set to `"true"` on the $productName$ deployment to revert to the - old incorrect behavior to help prevent any configuration issues after upgrading in the event that not all manifests making use of the selectors have been corrected yet. - - For more information on `DISABLE_STRICT_LABEL_SELECTORS` see the [Environment Variables page](../../../../../running/environment#disable_strict_label_selectors). - -2. Check Transport Protocol usage on all resources before migrating. - - The `AuthService`, `RatelimitService`, and `LogServices` 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. - - `protocol_version` should be updated to `v3` for all of the above resources while still running $productName$ $versionTwoX$. As of version `2.3.z`+, support for `protocol_version` `v2` and `v3` is supported in order to allow migration from `protocol_version` `v2` to `v3` before upgrading to $productName$ $version$ where support for `v2` is removed. - - Upgrading any application code for your own implementations of these services is very straightforward. - - The following imports simply need to be updated to switch from Envoy's Transport Protocol `v2` to `v3`, and then the configuration for these resources can be updated to add the `protocl_version: "v3"` when the updated service is deployed. - - `v2` Imports: - ```golang - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" - ``` - - `v3` Imports: - ```golang - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" - ``` - -3. Check removed runtime changes - - ```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, - - # Developers 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, - ``` - -4. Support for LightStep tracing driver removed - - - As of $productName$ 3.4.Z, the LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read before upgrading. - - -$productName$ 3.4 is based on Envoy 1.24.1 which removed support for the `LightStep` tracing driver. The team at LightStep and the maintainers of Envoy-Proxy recommend that users instead leverage the OpenTelemetry Collector to send tracing information to LightStep. We have written a guide which can be found here Distributed Tracing with OpenTelemetry and Lightstep that outlines how to set this up. **It is important that you follow this upgrade path prior to upgrading or you will drop tracing data.** - -## Migration Steps - -Migration is a two-step process: - -1. **Install new CRDs.** - - After reviewing the changes in 3.x and confirming that you are ready to upgrade, the process is the same as upgrading minor versions - in previous version of $productName$ and does not require the complex migration steps that the migration from 1.x tto 2.x required. - - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $version$.** - - After installing the new CRDs, upgrade $productName$ $version$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/pre-release/topics/install/upgrade/yaml/emissary-3.4/emissary-3.X.md b/content/en/docs/pre-release/topics/install/upgrade/yaml/emissary-3.4/emissary-3.X.md deleted file mode 100644 index 723ac6a1..00000000 --- a/content/en/docs/pre-release/topics/install/upgrade/yaml/emissary-3.4/emissary-3.X.md +++ /dev/null @@ -1,75 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 3.4.Z (YAML) - - - This guide covers migrating from $productName$ 3.4.Z to $productName$ $version$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading -between versions is straightforward. - -### Resources to check before migrating to $version$. - - - As of $productName$ 3.4.Z, the LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read below before upgrading. - - -$productName$ 3.4 has been upgraded from Envoy 1.23 to Envoy 1.24.1 which removed support for the `LightStep` tracing driver. The team at LightStep and the maintainers of Envoy-Proxy recommend that users instead leverage the OpenTelemetry Collector to send tracing information to LightStep. We have written a guide which can be found here Distributed Tracing with OpenTelemetry and Lightstep that outlines how to set this up. **It is important that you follow this upgrade path prior to upgrading or you will drop tracing data.** - -## Migration Steps - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $version$.** - - After installing the new CRDs, upgrade $productName$ $version$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/pre-release/topics/install/upgrade/yaml/emissary-3.7/emissary-3.X.md b/content/en/docs/pre-release/topics/install/upgrade/yaml/emissary-3.7/emissary-3.X.md deleted file mode 100644 index 024dd30c..00000000 --- a/content/en/docs/pre-release/topics/install/upgrade/yaml/emissary-3.7/emissary-3.X.md +++ /dev/null @@ -1,69 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 3.7.Z (YAML) - - - This guide covers migrating from $productName$ 3.7.Z to $productName$ $version$. If - this is not your exact situation, see the migration - matrix. - - - - This guide is written for upgrading an installation made without using Helm. - If you originally installed with Helm, see the Helm-based - upgrade instructions. - - -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading -between versions is straightforward. - -### Resources to check before migrating to $version$. - -## Migration Steps - -Migration is a two-step process: - -1. **Install new CRDs.** - - Before installing $productName$ $version$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml - kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system - ``` - - - $productName$ $version$ includes a Deployment in the `emissary-system` namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. **Install $productName$ $version$.** - - After installing the new CRDs, upgrade $productName$ $version$. - - - Our 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. - - - ```bash - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-emissaryns.yaml && \ - kubectl rollout status -n emissary deployment/emissary-ingress -w - ``` diff --git a/content/en/docs/pre-release/topics/install/yaml-install.md b/content/en/docs/pre-release/topics/install/yaml-install.md deleted file mode 100644 index bb628f5b..00000000 --- a/content/en/docs/pre-release/topics/install/yaml-install.md +++ /dev/null @@ -1,89 +0,0 @@ ---- - description: In this guide, we'll walk through the process of deploying $productName$ in Kubernetes for ingress routing. ---- - -import Alert from '@material-ui/lab/Alert'; - -# Install manually - - - - To migrate from $productName$ 1.X to $productName$ 2.X, see the - [$productName$ migration matrix](../migration-matrix/). This guide - **will not work** for that, due to changes to the configuration - resources used for $productName$ 2.X. - - - -In this guide, we'll walk you through installing $productName$ in your Kubernetes cluster. - -The manual install process does not allow for as much control over configuration -as the [Helm install method](../helm), so if you need more control over your $productName$ -installation, it is recommended that you use helm. - -## Before you begin - -$productName$ is designed to run in Kubernetes for production. The most essential requirements are: - -* Kubernetes 1.11 or later -* The `kubectl` command-line tool - -## Install with YAML - -$productName$ is typically deployed to Kubernetes from the command line. If you don't have Kubernetes, you should use our [Docker](../docker) image to deploy $productName$ locally. - -1. In your terminal, run the following command: - - ``` - kubectl create namespace $productNamespace$ || true - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml && \ - kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-emissaryns.yaml && \ - kubectl -n $productNamespace$ wait --for condition=available --timeout=90s deploy $productDeploymentName$ - ``` - - - $productName$ $version$ includes a Deployment in the $productNamespace$ namespace - called 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. - - - - If the 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. - - - - There is a known issue with the 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. - - -2. Determine the IP address or hostname of your cluster by running the following command: - - ``` - kubectl get -n $productNamespace$ service $productDeploymentName$ -o "go-template={{range .status.loadBalancer.ingress}}{{or .ip .hostname}}{{end}}" - ``` - - Your load balancer may take several minutes to provision your IP address. Repeat the provided command until you get an IP address. - -3. Next Steps - - $productName$ shold now be successfully installed and running, but in order to get started deploying Services and test routing to them you need to configure a few more resources. - - - [The `Listener` Resource](../../running/listener/) is required to configure which ports the $productName$ pods listen on so that they can begin responding to requests. - - [The `Mapping` Resouce](../../using/intro-mappings/) is used to configure routing requests to services in your cluster. - - [The `Host` Resource](../../running/host-crd/) configures TLS termination for enablin HTTPS communication. - - Explore how $productName$ [configures communication with clients](../../../howtos/configure-communications) - - - We strongly recommend following along with our Quickstart Guide to get started by creating a Listener, deploying a simple service to test with, and setting up a Mapping to route requests from $productName$ to the demo service. - - -## Upgrading an existing installation - -See the [migration matrix](../migration-matrix) for instructions about upgrading -$productName$. - - diff --git a/content/en/docs/pre-release/topics/running/ambassador-deployment.md b/content/en/docs/pre-release/topics/running/ambassador-deployment.md deleted file mode 100644 index d870f32c..00000000 --- a/content/en/docs/pre-release/topics/running/ambassador-deployment.md +++ /dev/null @@ -1,21 +0,0 @@ -# Deployment architecture - -$productName$ can be deployed in a variety of configurations. The specific configuration depends on your data center. - -## Public cloud - -If you're using a public cloud provider such as Amazon, Azure, or Google, $productName$ can be deployed directly to a Kubernetes cluster running in the data center. Traffic is routed to $productName$ via a cloud-managed load balancer such as an Amazon Elastic Load Balancer or Google Cloud Load Balancer. Typically, this load balancer is transparently managed by Kubernetes in the form of the `LoadBalancer` service type. $productName$ then routes traffic to your services running in Kubernetes. - -## On-Premise data center - -In an on-premise data center, $productName$ is deployed on the Kubernetes cluster. Instead of exposing it via the `LoadBalancer` service type, $productName$ is exposed as a `NodePort`. Traffic is sent to a specific port on any of the nodes in the cluster, which route the traffic to $productName$, which then routes the traffic to your services running in Kubernetes. You'll also need to deploy a separate load balancer to route traffic from your core routers to $productName$. [MetalLB](https://metallb.universe.tf/) is an open-source external load balancer for Kubernetes designed for this problem. Other options are traditional TCP load balancers such as F5 or Citrix Netscaler. - -## Hybrid data center - -Many data centers include services that are running outside of Kubernetes on virtual machines. For $productName$ to route to services both inside and outside of Kubernetes, it needs the real-time network location of all services. This problem is known as "[service discovery](https://www.datawire.io/guide/traffic/service-discovery-microservices/)" and $productName$ supports using [Consul](https://www.consul.io). Services in your data center register themselves with Consul, and $productName$ uses Consul-supplied data to dynamically route requests to available services. - -## Hybrid on-premise data center - -The diagram below details a common network architecture for a hybrid on-premise data center. Traffic flows from core routers to MetalLB, which routes to $productName$ running in Kubernetes. $productName$ routes traffic to individual services running on both Kubernetes and VMs. Consul tracks the real-time network location of the services, which $productName$ uses to route to the given services. - -![Architecture](../../images/consul-ambassador.png) diff --git a/content/en/docs/pre-release/topics/running/ambassador-with-aws.md b/content/en/docs/pre-release/topics/running/ambassador-with-aws.md deleted file mode 100644 index b321543a..00000000 --- a/content/en/docs/pre-release/topics/running/ambassador-with-aws.md +++ /dev/null @@ -1,364 +0,0 @@ -# $productName$ with AWS - -$productName$ is a platform agnostic Kubernetes API gateway. It will run in any distribution of Kubernetes whether it is managed by a cloud provider or on homegrown bare-metal servers. - -This document serves as a reference for different configuration options available when running Kubernetes in AWS. See [Installing $productName$](../../install) for the various installation methods available. - -## Recommended configuration - -There are lot of configuration options available to you when running $productName$ in AWS. While you should read this entire document to understand what is best for you, the following is the recommended configuration when running $productName$ in AWS: - -It is recommended to terminate TLS at $productName$ so you can take advantage of all the TLS configuration options available in $productName$ including setting the allowed TLS versions, setting `alpn_protocol` options, enforcing HTTP -> HTTPS redirection, and [automatic certificate management](../host-crd) in the $productName$. - -When terminating TLS at $productName$, you should deploy a L4 [Network Load Balancer (NLB)](#network-load-balancer-nlb) with the proxy protocol enabled to get the best performance out of your load balancer while still preserving the client IP address. - -The following `Service` should be configured to deploy an NLB with cross zone load balancing enabled (see [NLB notes](#network-load-balancer-nlb) for caveat on the cross-zone-load-balancing annotation). You will need to configure the proxy protocol in the NLB manually in the AWS Console. - -```yaml -apiVersion: v1 -kind: Service -metadata: - name: ambassador - namespace: ambassador - annotations: - service.beta.kubernetes.io/aws-load-balancer-type: "nlb" - service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: "true" -spec: - type: LoadBalancer - ports: - - name: HTTP - port: 80 - targetPort: 8080 - - name: HTTPS - port: 443 - targetPort: 8443 - selector: - service: ambassador -``` - - After deploying the `Service` above and manually enabling the proxy protocol you will need to deploy the following [Ambassador `Module`](../ambassador) to tell $productName$ to use the proxy protocol and then restart $productName$ for the configuration to take effect. - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - use_proxy_proto: true - ``` - - $productName$ will now expect traffic from the load balancer to be wrapped with the proxy protocol so it can read the client IP address. - -## AWS load balancer notes - -AWS provides three types of load balancers: - -### "Classic" Elastic Load Balancer (ELB) - -The ELB is the first generation AWS Elastic Load Balancer. It is the default type of load balancer ensured by a `type: LoadBalancer` `Service` and routes directly to individual EC2 instances. It can be configured to run at layer 4 or layer 7 of the OSI model. See [What is a Classic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/introduction.html) for more details. - -* Ensured by default for a `type: LoadBalancer` `Service` -* Layer 4: TCP, TCP/SSL - * Protocol support - * HTTP(S) - * Websockets - * HTTP/2 - * Connection based load balancing - * Cannot modify the request -* Layer 7: HTTP, HTTPS - * Protocol support - * HTTP(S) - * Request based load balancing - * Can modify the request (append to `X-Forwarded-*` headers) -* Can perform TLS termination - -**Notes:** -- While it has been superseded by the `Network Load Balancer` and `Application Load Balancer` the ELB offers the simplest way of provisioning an L4 or L7 load balancer in Kubernetes. -- All of the [load balancer annotations](#load-balancer-annotations) are respected by the ELB. -- If using the ELB for TLS termination, it is recommended to run in L7 mode so it can modify `X-Forwarded-Proto` correctly. - -### Network Load Balancer (NLB) - -The NLB is a second generation AWS Elastic Load Balancer. It can be ensure by a `type: LoadBalancer` `Service` using an annotation. It can only run at layer 4 of the OSI model and load balances based on connection allowing it to handle millions of requests per second. See [What is a Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/introduction.html) for more details. - -* Can be ensured by a `type: LoadBalancer` `Service` -* Layer 4: TCP, TCP/SSL - * Protocol support - * HTTP(S) - * Websockets - * HTTP/2 - * Connection based load balacing - * Cannot modify the request -* Can perform TLS termination - -**Notes:** -- The NLB is the most efficient load balancer capable of handling millions of requests per second. It is recommended for streaming connections since it will maintain the connection stream between the client and $productName$. -- Most of the [load balancer annotations](#load-balancer-annotations) are respected by the NLB. You will need to manually configure the proxy protocol and take an extra step to enable cross zone load balancing. -- Since it operates at L4 and cannot modify the request, you will need to tell $productName$ if it is terminating TLS or not (see [TLS termination](#tls-termination) notes below). - -### Application Load Balancer (ALB) - -The ALB is a second generation AWS Elastic Load Balancer. It cannot be ensured by a `type: LoadBalancer` `Service` and must be deployed and configured manually. It can only run at layer 7 of the OSI model and load balances based on request information allowing it to perform fine-grained routing to applications. See [What is a Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/introduction.html) for more details. - -* Cannot be configured by a `type: LoadBalancer` `Service` -* Layer 7: HTTP, HTTPS - * Protocol support - * HTTP(S) - * Request based load balancing - * Can modify the request (append to `X-Forwarded-*` headers) -* Can perform TLS termination - -**Notes:** - -- The ALB can perform routing based on the path, headers, host, etc.. Since $productName$ performs this kind of routing in your cluster, unless you are using the same load balancer to route to services outside of Kubernetes, the overhead of provisioning an ALB is often not worth the benefits. -- If you would like to use an ALB, you will need to expose $productName$ with a `type: NodePort` service and manually configure the ALB to forward to the correct ports. -- None of the [load balancer annotations](#load-balancer-annotations) are respected by the ALB. You will need to manually configure all options. -- The ALB will properly set the `X-Forward-Proto` header if terminating TLS. See (see [TLS termination](#tls-termination) notes below). - -## Load balancer annotations - -Kubernetes on AWS exposes a mechanism to request certain load balancer configurations by annotating the `type: LoadBalancer` `Service`. The most complete set and explanations of these annotations can be found in this [Kubernetes document](https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer). This document will go over the subset that is most relevant when deploying $productName$. - -- `service.beta.kubernetes.io/aws-load-balancer-ssl-cert`: - - Configures the load balancer to use a valid certificate ARN to terminate TLS at the Load Balancer. - - Traffic from the client into the load balancer is encrypted but, since TLS is being terminated at the load balancer, traffic from the load balancer to $productName$ will be cleartext. You will need to configure $productName$ differently depending on whether the load balancer is running in L4 or L7 (see [TLS termination](#tls-termination) notes below). - -- `service.beta.kubernetes.io/aws-load-balancer-ssl-ports`: - - Configures which port the load balancer will be listening for SSL traffic on. Defaults to `"*"`. - - If you want to enable cleartext redirection, make sure to set this to `"443"` so traffic on port 80 will come in over cleartext. - -- `service.beta.kubernetes.io/aws-load-balancer-backend-protocol`: - - Configures the ELB to operate in L4 or L7 mode. Can be set to `"tcp"`/`"ssl"` for an L4 listener or `"http"`/`"https"` for an L7 listener. Defaults to `"tcp"` or `"ssl"` if `aws-load-balancer-ssl-cert` is set. - -- `service.beta.kubernetes.io/aws-load-balancer-type: "nlb"`: - - When this annotation is set it will launch a [Network Load Balancer (NLB)](#network-load-balancer-nlb) instead of a classic ELB. - -- `service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled`: - - Configures the load balancer to load balance across zones. For high availability, it is typical to deploy nodes across availability zones so this should be set to `"true"`. - - **Note:** You cannot configure this annotation and `service.beta.kubernetes.io/aws-load-balancer-type: "nlb"` at the same time. You must first deploy the `Service` with an NLB and then update it with the cross zone load balancing configuration. - -- `service.beta.kubernetes.io/aws-load-balancer-proxy-protocol`: - - Configures the ELB to enable the proxy protocol. `"*"`, which enables the proxy protocol on all ELB backends, is the only acceptable value. - - The proxy protocol can be used to preserve the client IP address. - - If setting this value, you need to make sure $productName$ is configured to use the proxy protocol (see [preserving the client IP address](#preserving-the-client-ip-address) below). - - **Note:** This annotation will not be recognized if `aws-load-balancer-type: "nlb"` is configured. Proxy protocol must be manually enabled for NLBs. - -## TLS termination - -TLS termination is an important part of any modern web app. $productName$ exposes a lot of TLS termination configuration options that make it a powerful tool for managing encryption between your clients and microservices. Refer to the [TLS Termination](../tls) documentation for more information on how to configure TLS termination at $productName$. - -With AWS, the AWS Certificate Manager (ACM) makes it easy to configure TLS termination at an AWS load balancer using the annotations explained above. - -This means that, when running $productName$ in AWS, you have the choice between terminating TLS at the load balancer using a certificate from the ACM or at $productName$ using a certificate stored as a `Secret` in your cluster. - -The following documentation will cover the different options available to you and how to configure $productName$ and the load balancer to get the most of each. - -### TLS termination at $productName$ - -Terminating TLS at $productName$ will guarantee you to be able to use all of the TLS termination options that $productName$ exposes including enforcing the minimum TLS version, setting the `alpn_protocols`, and redirecting cleartext to HTTPS. - -If terminating TLS at $productName$, you can provision any AWS load balancer that you want with the following (default) port assignments: - -```yaml -spec: - ports: - - name: http - port: 80 - targetPort: 8080 - - name: https - port: 443 - targetPort: 8443 -``` - -While terminating TLS at $productName$ makes it easier to expose more advanced TLS configuration options, it does have the drawback of not being able to use the ACM to manage certificates. You will have to manage your TLS certificates yourself or use the [automatic certificate management](../host-crd) available in $productName$ to have $productName$ do it for you. - -### TLS termination at the load balancer - -If you choose to terminate TLS at your Amazon load balancer you will be able to use the ACM to manage TLS certificates. This option does add some complexity to your $productName$ configuration, depending on which load balancer you are using. - -Terminating TLS at the load balancer means that $productName$ will be receiving all traffic as un-encrypted cleartext traffic. Since $productName$ expects to be serving both encrypted and cleartext traffic by default, you will need to make the following configuration changes to $productName$ to support this: - -#### L4 load balancer (default ELB or NLB) - -* **Load Balancer Service Configuration:** - The following `Service` will deploy a L4 ELB with TLS termination configured at the load balancer: - ```yaml - apiVersion: v1 - kind: Service - metadata: - name: ambassador - namespace: ambassador - annotations: - service.beta.kubernetes.io/aws-load-balancer-ssl-cert: {{ACM_CERT_ARN}} - service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "443" - spec: - type: LoadBalancer - ports: - - name: HTTP - port: 80 - targetPort: 8080 - - name: HTTPS - port: 443 - targetPort: 8080 - selector: - service: ambassador - ``` - - Note that the `spec.ports` has been changed so both the HTTP and HTTPS ports forward to the cleartext port 8080 on $productName$. - -* **`Host`:** - - The `Host` configures how $productName$ handles encrypted and cleartext traffic. The following `Host` configuration will tell $productName$ to `Route` cleartext traffic that comes in from the load balancer: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Host - metadata: - name: ambassador - spec: - hostname: "*" - selector: - matchLabels: - hostname: wildcard - acmeProvider: - authority: none - requestPolicy: - insecure: - action: Route - ``` - -**Important:** - -Because L4 load balancers do not set `X-Forwarded` headers, $productName$ will not be able to distinguish between traffic that came in to the load balancer as encrypted or cleartext. Because of this, **HTTP -> HTTPS redirection is not possible when terminating TLS at a L4 load balancer**. - -#### L7 load balancer (ELB or ALB) - -* **Load Balancer Service Configuration (L7 ELB):** - - The following `Service` will deploy a L7 ELB with TLS termination configured at the load balancer: - ```yaml - apiVersion: v1 - kind: Service - metadata: - name: ambassador - namespace: ambassador - annotations: - service.beta.kubernetes.io/aws-load-balancer-ssl-cert: {{ACM_CERT_ARN}} - service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "443" - service.beta.kubernetes.io/aws-load-balancer-backend-protocol: "http" - spec: - type: LoadBalancer - ports: - - name: HTTP - port: 80 - targetPort: 8080 - - name: HTTPS - port: 443 - targetPort: 8080 - selector: - service: ambassador - ``` - - Note that the `spec.ports` has been changed so both the HTTP and HTTPS ports forward to the cleartext port 8080 on $productName$. - -* **`Host`:** - - The `Host` configures how $productName$ handles encrypted and cleartext traffic. The following `Host` configuration will tell $productName$ to `Redirect` cleartext traffic that comes in from the load balancer: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Host - metadata: - name: ambassador - spec: - hostname: "*" - selector: - matchLabels: - hostname: wildcard - acmeProvider: - authority: none - requestPolicy: - insecure: - action: Redirect - ``` - -* **Module:** - - Since a L7 load balancer will be able to append to `X-Forwarded` headers, we need to configure $productName$ to trust the value of these headers. The following `Module` will configure $productName$ to trust a single L7 proxy in front of $productName$: - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - xff_num_trusted_hops: 1 - use_remote_address: false - ``` - -**Note:** - -$productName$ uses the value of `X-Forwarded-Proto` to know if the request originated as encrypted or cleartext. Unlike L4 load balancers, L7 load balancers will set this header so HTTP -> HTTPS redirection is possible when terminating TLS at a L7 load balancer. - -## Preserving the client IP address - -Many applications will want to know the IP address of the connecting client. In Kubernetes, this IP address is often obscured by the IP address of the `Node` that is forwarding the request to $productName$ so extra configuration must be done if you need to preserve the client IP address. - -In AWS, there are two options for preserving the client IP address. - -1. Use a L7 Load Balancer that sets `X-Forwarded-For` - - A L7 load balancer will populate the `X-Forwarded-For` header with the IP address of the downstream connecting client. If your clients are connecting directly to the load balancer, this will be the IP address of your client. - - When using L7 load balancers, you must configure $productName$ to trust the value of `X-Forwarded-For` and not append its own IP address to it by setting `xff_num_trusted_hops` and `use_remote_address: false` in the [Ambassador `Module`](../ambassador): - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - xff_num_trusted_hops: 1 - use_remote_address: false - ``` - - After configuring the above `Module`, you will need to restart $productName$ for the changes to take effect. - -2. Use the proxy protocol - - The [proxy protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) is a wrapper around an HTTP request that, like `X-Forwarded-For`, lists the IP address of the downstream connecting client but is able to be set by L4 load balancers as well. - - In AWS, you can configure ELBs to use the proxy protocol by setting the `service.beta.kubernetes.io/aws-load-balancer-proxy-protocol: "*"` annotation on the service. You must manually configure this on ALBs and NLBs. - - After configuring the load balancer to use the proxy protocol, you need to tell $productName$ to expect it on the request. - - ```yaml - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - namespace: ambassador - spec: - config: - use_proxy_proto: true - ``` - - After configuring the above `Module`, you will need to restart $productName$ for the changes to take effect. diff --git a/content/en/docs/pre-release/topics/running/ambassador-with-gke.md b/content/en/docs/pre-release/topics/running/ambassador-with-gke.md deleted file mode 100644 index 2b90581d..00000000 --- a/content/en/docs/pre-release/topics/running/ambassador-with-gke.md +++ /dev/null @@ -1,187 +0,0 @@ -# $productName$ with GKE - -Google offers a [L7 load balancer](https://cloud.google.com/kubernetes-engine/docs/concepts/ingress) to -leverage network services such as managed SSL certificates, SSL offloading or the Google content delivery network. -A L7 load balancer in front of $productName$ can be configured by hand or by using the Ingress-GCE resource. Using the -Ingress resource also allows you to create Google-managed SSL certificates through Kubernetes. - -With this setup, HTTPS will be terminated at the Google load balancer. The load balancer will be created and configured by -the Ingress-GCE resource. The load balancer consists of a set of -[forwarding rules](https://cloud.google.com/load-balancing/docs/forwarding-rule-concepts#https_lb) and a set of -[backend services](https://cloud.google.com/load-balancing/docs/backend-service). -In this setup, the ingress resource creates two forwarding rules, one for HTTP and one for HTTPS. The HTTPS -forwarding rule has the SSL certificates attached. Also, one backend service will be created to point to -a list of instance groups at a static port. This will be the NodePort of the $productName$ service. - -With this setup, the load balancer terminates HTTPS and then directs the traffic to the $productName$ service -via the `NodePort`. $productName$ is then doing all the routing to the other internal/external services. - -# Overview of steps - -1. Install and configure the ingress with the HTTP(S) load balancer -2. Install $productName$ -3. Configure and connect $productName$ to ingress -4. Create an SSL certificate and enable HTTPS -5. Create BackendConfig for health checks -6. Configure $productName$ to do HTTP -> HTTPS redirection - -`ambassador` will be running as a `NodePort` service. Health checks will be configured to go to a BackendConfig resource. - -## 0. $productName$ - -This guide will install $OSSproductName$. You can also install $AESproductName$. Please note: -- The ingress and the `ambassador` service need to run in the same namespace -- The `ambassador` service needs to be of type `NodePort` and not `LoadBalancer`. Also remove the line with `externalTrafficPolicy: Local` -- Ambassador-Admin needs to be of type `NodePort` instead of `ClusterIP` since it needs to be available for health checks - -## 1 . Install and configure ingress with the HTTP(S) load balancer - -Create a GKE cluster through the web console. Use the release channel. When the cluster -is up and running follow [this tutorial from Google](https://cloud.google.com/kubernetes-engine/docs/tutorials/http-balancer) to configure -an ingress and a L7 load balancer. After you have completed these steps you will have a running L7 load balancer -and one service. - -## 2. Install $productName$ - -Follow the first section of the [$OSSproductName$ installation guide](../../install/) to install $OSSproductName$. -Stop before defining the `ambassador` service. - -$productName$ needs to be deployed as `NodePort` instead of `LoadBalancer` to work with the L7 load balancer and the ingress. - -Save the YAML below in ambassador.yaml and apply with `kubectl apply -f ambassador.yaml` - -```yaml -apiVersion: v1 -kind: Service -metadata: - name: ambassador -spec: - type: NodePort - ports: - - port: 8080 - targetPort: 8080 - selector: - service: ambassador -``` - -You will now have an `ambassador` service running next to your ingress. - -## 3. Configure and connect `ambassador` to the ingress - -You need to change the ingress for it to send traffic to `ambassador`. Assuming you have followed the tutorial, you should -have a file named basic-ingress.yaml. Change it to point to `ambassador` instead of web: - -```yaml -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - name: basic-ingress -spec: - backend: - serviceName: ambassador - servicePort: 8080 -``` - -Now let's connect the other service from the tutorial to `ambassador` by specifying a Mapping: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: web - namespace: default -spec: - hostname: "*" - prefix: / - service: web:8080 -``` - -All traffic will now go to `ambassador` and from `ambassador` to the `web` service. You should be able to hit your load balancer and get the output. It may take some time until the load balancer infrastructure has rolled out all changes and you might see gateway errors during that time. -As a side note: right now all traffic will go to the `web` service, including the load balancer health check. - -## 4. Create an SSL certificate and enable HTTPS - -Read up on [managed certificates on GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/managed-certs). You need -a DNS name and point it to the external IP of the load balancer. - -certificate.yaml: -```yaml -apiVersion: networking.gke.io/v1beta1 -kind: ManagedCertificate -metadata: - name: www-example-com -spec: - domains: - - www.example.com -``` - -Modify the ingress from before: -```yaml -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - name: basic-ingress - annotations: - networking.gke.io/managed-certificates: www-example-com -spec: - backend: - serviceName: ambassador - servicePort: 8080 -``` - -Please wait (5-15 minutes) until the certificate is created and all edge servers have the certificates ready. -`kubectl describe ManagedCertificate` will show you the status or go to the web console to view the load balancer. - -You should now be able to access the web service via `https://www.example.com`. - -## 5. Configure BackendConfig for health checks - -Create and apply a BackendConfig resource with a [custom health check](https://cloud.google.com/kubernetes-engine/docs/how-to/ingress-features#direct_health) specified: - -```yaml -apiVersion: cloud.google.com/v1 -kind: BackendConfig -metadata: - name: ambassador-hc-config - namespace: ambassador -spec: - # https://cloud.google.com/kubernetes-engine/docs/how-to/ingress-features - timeoutSec: 30 - connectionDraining: - drainingTimeoutSec: 30 - logging: - enable: true - sampleRate: 1.0 - healthCheck: - checkIntervalSec: 10 - timeoutSec: 10 - port: 8877 - type: HTTP - requestPath: /ambassador/v0/check_alive -``` - -Then edit your previous `ambassador.yaml` file to add an annotation referencing the BackendConfig and apply the file: - -``` -apiVersion: v1 -kind: Service -metadata: - name: ambassador - annotations: - cloud.google.com/backend-config: '{"default": "ambassador-hc-config"}' -spec: - type: NodePort - ports: - - port: 8080 - targetPort: 8080 - selector: - service: ambassador -``` - -## 6. Configure $productName$ to do HTTP -> HTTPS redirection - -Configure $productName$ to [redirect traffic from HTTP to HTTPS](../tls/cleartext-redirection/#http-https-redirection). You will need to restart $productName$ to effect the changes with `kubectl rollout restart deployment ambassador`. - -The result should be that `http://www.example.com` will redirect to `https://www.example.com`. - -You can now add more services by specifying the hostname in the Mapping. diff --git a/content/en/docs/pre-release/topics/running/ambassador.md b/content/en/docs/pre-release/topics/running/ambassador.md deleted file mode 100644 index 3af41d93..00000000 --- a/content/en/docs/pre-release/topics/running/ambassador.md +++ /dev/null @@ -1,558 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# The `Ambassador` `Module` Resource - -
-

Contents

- -* [Envoy](#envoy) -* [General](#general) -* [gRPC](#grpc) -* [Header behavior](#header-behavior) -* [Observability](#observability) -* [Protocols](#protocols) -* [Security](#security) -* [Service health / timeouts](#service-health--timeouts) -* [Traffic management](#traffic-management) - - -
- -If present, the `ambassador` `Module` defines system-wide configuration for $productName$. You won't need it unless you need to change one of the system-wide configuration settings below. - -To use the `ambassador` `Module` to configure $productName$, it MUST be named `ambassador`, otherwise it will be ignored. To create multiple `ambassador` `Module`s in the same Kubernetes namespace, you will need to apply them as annotations with separate `ambassador_id`s: you will not be able to use multiple CRDs. - -There are many items that can be configured on the `ambassador` `Module`. They are listed below with examples and grouped by category. - -## Envoy - -##### Content-Length headers - -* `allow_chunked_length: true` tells Envoy to allow requests or responses with both `Content-Length` and `Transfer-Encoding` headers set. The default is `false`. - -By default, messages with both `Content-Length` and `Content-Transfer-Encoding` are rejected. If `allow_chunked_length` is `true`, $productName$ will remove the `Content-Length` header and process the message. See the [Envoy documentation for more details](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto.html?highlight=allow_chunked_length#config-core-v3-http1protocoloptions). - -##### Envoy access logs - -* `envoy_log_path` defines the path of Envoy's access log. By default this is standard output. -* `envoy_log_type` defines the type of access log Envoy will use. Currently, only `json` or `text` are supported. -* `envoy_log_format` defines the Envoy access log line format. - -These logs can be formatted using [Envoy operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) to display specific information about an incoming request. The example below will show only the protocol and duration of a request: - -```yaml -envoy_log_path: /dev/fd/1 -envoy_log_type: json -envoy_log_format: - { - "protocol": "%PROTOCOL%", - "duration": "%DURATION%" - } -``` - -See the Envoy documentation for the [standard log format](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#default-format-string) and a [complete list of log format operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/access_log). - -##### Envoy validation timeout - -* `envoy_validation_timeout` defines the timeout, in seconds, for validating a new Envoy configuration. The default is 10. - -A value of 0 disables Envoy configuration validation. Most installations will not need to change this setting. - -For example: - -```yaml -envoy_validation_timeout: 30 -``` - -would allow 30 seconds to validate the generated Envoy configuration. - -##### Error response overrides - -* `error_response_overrides` permits changing the status code and body text for 4XX and 5XX response codes. The default is not to override any error responses. - -By default, $productName$ will pass through error responses without modification, and errors generated locally will use Envoy's default response body, if any. - -See [using error response overrides](../custom-error-responses) for usage details. For example, this configuration: - -```yaml -error_response_overrides: - - on_status_code: 404 - body: - text_format: "File not found" -``` - -would explicitly modify the body of 404s to say "File not found". - -##### Forwarding client cert details - -Two attributes allow providing information about the client's TLS certificate to upstream certificates: - -* `forward_client_cert_details: true` will tell Envoy to add the `X-Forwarded-Client-Cert` to upstream - requests. The default is `false`. -* `set_current_client_cert_details` will tell Envoy what information to include in the - `X-Forwarded-Client-Cert` header. The default is not to include the `X-Forwarded-Client-Cert` header at all. - -$productName$ will not forward information about a certificate that it cannot validate. - -See the Envoy documentation on [X-Forwarded-Client-Cert](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers.html?highlight=xfcc#x-forwarded-client-cert) and [SetCurrentClientCertDetails](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto.html#extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-setcurrentclientcertdetails) for more information. - -```yaml -forward_client_cert_details: true -set_current_client_cert_details: SANITIZE -``` - -##### Server name - -* `server_name` allows overriding the server name that Envoy sends with responses to clients. The default is `envoy`. - -##### Suppress Envoy headers - -* `suppress_envoy_headers: true` will prevent $productName$ from emitting certain additional - headers to HTTP requests and responses. The default is `false`. - -For the exact set of headers covered by this config, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter#config-http-filters-router-headers-set) - ---- -## General - -##### Ambassador ID - -* `ambassador_id` allows using multiple instances of $productName$ in the same cluster. The default is unset. - -We recommend _not_ setting `ambassador_id` if you are running only one instance of $productName$ in your cluster. For more information, see the [Running and Deployment documentation](../running/#ambassador_id). - -If used, the `ambassador_id` value must be an array, for example: - -```yaml -ambassador_id: [ "test_environment" ] -``` - -##### Defaults - -* `defaults` provides a dictionary of default values that will be applied to various $productName$ resources. The default is to have no defaults configured. - -See [Using `ambassador` `Module` Defaults](../../using/defaults) for more information. - ---- - -## gRPC - -##### Bridges - -* `enable_grpc_http11_bridge: true` will enable the gRPC-HTTP/1.1 bridge. The default is `false`. -* `enable_grpc_web: true` will enable the gRPC-Web bridge. The default is `false`. - -gRPC is a binary HTTP/2-based protocol. While this allows high performance, it can be problematic for clients that are unable to speak HTTP/2 (such as JavaScript in many browsers, or legacy clients in difficult-to-update environments). - -The gRPC-HTTP/1.1 bridge can translate HTTP/1.1 calls with `Content-Type: application/grpc` into gRPC calls: $productName$ will perform buffering and translation as necessary. For more details on the translation process, see the [Envoy gRPC HTTP/1.1 bridge documentation](https://www.envoyproxy.io/docs/envoy/v1.11.2/configuration/http_filters/grpc_http1_bridge_filter.html). - -Likewise, gRPC-Web is a JSON and HTTP-based protocol that allows browser-based clients to take advantage of gRPC protocols. The gRPC-Web specification requires a server-side proxy to translate between gRPC-Web requests and gRPC backend services, and $productName$ can fill this role when the gRPC-Web bridge is enabled. For more details on the translation process, see the [Envoy gRPC HTTP/1.1 bridge documentation](https://www.envoyproxy.io/docs/envoy/v1.11.2/configuration/http_filters/grpc_http1_bridge_filter.html); for more details on gRPC-Web itself, see the [gRPC-Web client GitHub repo](https://github.com/grpc/grpc-web). - -##### Statistics - -* `grpc_stats` allows enabling telemetry for gRPC calls using Envoy's [gRPC Statistics Filter](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/grpc_stats_filter). The default is disabled. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - grpc_stats: - upstream_stats: true - services: - - name: . - method_names: [] -``` - -Supported parameters: -* `all_methods` -* `services` -* `upstream_stats` - -Available metrics: -* `envoy_cluster_grpc__` -* `envoy_cluster_grpc__request_message_count` -* `envoy_cluster_grpc__response_message_count` -* `envoy_cluster_grpc__success` -* `envoy_cluster_grpc__total` -* `envoy_cluster_grpc_upstream_` - **only when `upstream_stats: true`** - -Please note that `` will only be present if `all_methods` is set or the service and the method are present under `services`. If `all_methods` is false or the method is not on the list, the available metrics will be in the format `envoy_cluster_grpc_`. - -* `all_methods`: If set to true, emit stats for all service/method names. -If set to false, emit stats for all service/message types to the same stats without including the service/method in the name. -**This option is only safe if all clients are trusted. If this option is enabled with untrusted clients, the clients could cause unbounded growth in the number -of stats in Envoy, using unbounded memory and potentially slowing down stats pipelines.** - -* `services`: If set, specifies an allow list of service/methods that will have individual stats emitted for them. Any call that does not match the allow list will be counted in a stat with no method specifier (generic metric). - - - If both all_methods and services are present, all_methods will be ignored. - - -* `upstream_stats`: If true, the filter will gather a histogram for the request time of the upstream. - ---- - -## Header behavior - -##### Header case - -* `proper_case: true` forces headers to have their "proper" case as shown in RFC7230. The default is `false`. -* `header_case_overrides` allows forcing certain headers to have specific casing. The default is to override no headers. - -proper_case and header_case_overrides are mutually exclusive. - -RFC7230 specifies that HTTP header names are case-insensitive, but always shows and refers to headers as starting with a capital letter, continuing in lowercase, then repeating the single capital letter after each non-alpha character. This has become an established convention when working with HTTP: - -- `Host`, not `host` or `HOST` -- `Content-Type`, not `content-type`, `Content-type`, or `cOnTeNt-TyPe` - -Internally, Envoy typically uses [all lowercase](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/header_casing) for header names. This is fully compliant with RFC7230, but some services and clients may require headers to follow the stricter casing rules implied by RFC7230 section headers: in that situation, setting `proper_case: true` will tell Envoy to force all headers to use the casing above. - -Alternately, it is also possible - although less common - for services or clients to require some other specific casing for specific headers. `header_case_overrides` specifies an array of header names: if a case-insensitive match for a header is found in the list, the matching header will be replaced with the one in the list. For example, the following configuration will force headers that match `X-MY-Header` and `X-EXPERIMENTAL` to use that exact casing, regardless of the original case used in flight: - -```yaml -header_case_overrides: -- X-MY-Header -- X-EXPERIMENTAL -``` - -If the upstream service responds with `x-my-header: 1`, $productName$ will return `X-MY-Header: 1` to the client. Similarly, if the client includes `x-ExperiMENTAL: yes` in its request, the request to the upstream service will include `X-EXPERIMENTAL: yes`. Other headers will not be altered; $productName$ will use its default lowercase header. - -Please see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto.html#config-core-v3-http1protocoloptions-headerkeyformat) for more information. Note that in general, we recommend updating clients and services rather than relying on `header_case_overrides`. - -##### Linkerd interoperability - -* `add_linkerd_headers: true` will force $productName$ to include the `l5d-dst-override` header for Linkerd. The default is `false`. - -When using older Linkerd installations, requests going to an upstream service may need to include the `l5d-dst-override` header to ensure that Linkerd will route them correctly. Setting `add_linkerd_headers` does this automatically. See the [Mapping](../../using/mappings#linkerd-interoperability-add_linkerd_headers) documentation for more details. - -##### Max request headers size - -* `max_request_headers_kb` sets the maximum allowed request header size in kilobytes. If not set, the default is 60 KB. - -See [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto.html) for more information. - -##### Preserve external request ID - -* `preserve_external_request_id: true` will preserve any `X-Request-Id` header presented by the client. The default is `false`, in which case Envoy will always generate a new `X-Request-Id` value. - -##### Strip matching host port - -* `strip_matching_host_port: true` will tell $productName$ to strip any port number from the host/authority header before processing and routing the request if that port number matches the port number of Envoy's listener. The default is `false`, which will preserve any port number. - -In the default installation of $productName$ the public port is 443, which then maps internally to 8443, so this only works in custom installations where the public Service port and Envoy listener port match. - -A common reason to try using this property is if you are using gRPC with TLS and your client library appends the port to the Host header (i.e. `myurl.com:443`). We have an alternative solution in our [gRPC guide](../../../howtos/grpc#working-with-host-headers-that-include-the-port) that uses a [Lua script](#lua-scripts) to remove all ports from every Host header for that use case. - ---- - -## Miscellaneous - - -##### Envoy's admin port - -* `admin_port` specifies the port where $productName$'s Envoy will listen for low-level admin requests. The default is 8001; it should almost never need changing. - -##### Lua scripts - -* `lua_scripts` allows defining a custom Lua script to run on every request. The default is to run no script. - -This is useful for simple use cases that mutate requests or responses, for example to add a custom header: - -```yaml -lua_scripts: | - function envoy_on_response(response_handle) - response_handle:headers():add("Lua-Scripts-Enabled", "Processed") - end -``` - -For more details on the Lua API, see the [Envoy Lua filter documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/lua_filter.html). - -Some caveats around the embedded scripts: - -* They run in-process, so any bugs in your Lua script can break every request. -* They're run on every request/response to every URL. -* They're inlined in the $productName$ YAML; as such, we do not recommend using Lua scripts for long, complex logic. - -If you need more flexible and configurable options, $AESproductName$ supports a [pluggable Filter system](/docs/edge-stack/latest/topics/using/filters/). - -##### Merge slashes - -* `merge_slashes: true` will cause $productName$ to merge adjacent slashes in incoming paths when doing route matching and request filtering. The default is `false`. - -For example, with `merge_slashes: true`, a request for `//foo///bar` would be matched to a `Mapping` with prefix `/foo/bar`. - -##### Modify Default Buffer Size - -By default, the Envoy that ships with $productName$ uses a defailt of 1MiB soft limit for an upstream service's read and write buffer limits. This setting allows you to configure that buffer limit. See the [Envoy docs](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto.html?highlight=per_connection_buffer_limit_bytes) for more information. - -```yaml -buffer_limit_bytes: 5242880 # Sets the default buffer limit to 5 MiB -``` - -##### Use $productName$ namespace for service resolution - -* `use_ambassador_namespace_for_service_resolution: true` tells $productName$ to assume that unqualified services are in the same namespace as $productName$. The default is `false`. - -By default, when $productName$ sees a service name without a namespace, it assumes that the namespace is the same as the resource referring to the service. For example, for this `Mapping`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-1 - namespace: foo -spec: - hostname: "*" - prefix: / - service: upstream -``` - -$productName$ would look for a Service named `upstream` in namespace `foo`. - -However, if `use_ambassador_namespace_for_service_resolution` is `true`, this `Mapping` would look for a Service named `foo` in the namespace in which $productName$ is installed instead. - ---- - -## Observability - -##### Diagnostics - -* `diagnostics` controls access to the diagnostics interface. - -By default, $productName$ creates a `Mapping` that allows access to the diagnostic interface at `/ambassador/v0/diag` from anywhere in the cluster. To disable the `Mapping` entirely, set `diagnostics.enabled` to `false`: - - -```yaml -diagnostics: - enabled: false -``` - -With diagnostics disabled, `/ambassador/v0/diag` will respond with 404; however, the service itself is still running, and `/ambassador/v0/diag/` is reachable from inside the $productName$ Pod at `https://localhost:8877`. You can use Kubernetes port forwarding to set up remote access to the diagnostics page temporarily: - -``` -kubectl port-forward -n ambassador deploy/ambassador 8877 -``` - -Alternately, to leave the `Mapping` intact but restrict access to only the local Pod, set `diagnostics.allow_non_local` to `false`: - -```yaml -diagnostics: - allow_non_local: true -``` - -See [Protecting Access to the Diagnostics Interface](../../../howtos/protecting-diag-access) for more information. - ---- -## Protocols - -##### Enable IPv4 and IPv6 - -* `enable_ipv4` determines whether IPv4 DNS lookups are enabled. The default is `true`. -* `enable_ipv6` determines whether IPv6 DNS lookups are enabled. The default is `false`. - -If both IPv4 and IPv6 are enabled, $productName$ will prefer IPv6. This can have strange effects if $productName$ receives `AAAA` records from a DNS lookup, but the underlying network of the pod doesn't actually support IPv6 traffic. For this reason, the default is IPv4 only. - -An [`Mapping`](../../using/mappings) can override both `enable_ipv4` and `enable_ipv6`, but if either is not stated explicitly in a `Mapping`, the values here are used. Most $productName$ installations will probably be able to avoid overriding these settings in Mappings. - -##### HTTP/1.0 support - -* `enable_http10: true` will enable handling incoming HTTP/1.0 and HTTP/0.9 requests. The default is `false`. - ---- -## Security - -##### Cross origin resource sharing (CORS) - -* `cors` sets the default CORS configuration for all mappings in the cluster. The default is that CORS is not configured. - -For example: - -```yaml -cors: - origins: http://foo.example,http://bar.example - methods: POST, GET, OPTIONS - ... -``` - -See the [CORS syntax](../../using/cors) for more information. - -##### IP allow and deny - -* `ip_allow` and `ip_deny` define HTTP source IP address ranges to allow or deny. The default is to allow all traffic. - -Only one of ip_allow and ip_deny may be specified. - -If `ip_allow` is specified, any traffic not matching a range to allow will be denied. If `ip_deny` is specified, any traffic not matching a range to deny will be allowed. A list of ranges to allow and a separate list to deny may not both be specified. - -Both take a list of IP address ranges with a keyword specifying how to interpret the address, for example: - -```yaml -ip_allow: -- peer: 127.0.0.1 -- remote: 99.99.0.0/16 -``` - -The keyword `peer` specifies that the match should happen using the IP address of the other end of the network connection carrying the request: `X-Forwarded-For` and the `PROXY` protocol are both ignored. Here, our example specifies that connections originating from the $productName$ pod itself should always be allowed. - -The keyword `remote` specifies that the match should happen using the IP address of the HTTP client, taking into account `X-Forwarded-For` and the `PROXY` protocol if they are allowed (if they are not allowed, or not present, the peer address will be used instead). This permits matches to behave correctly when, for example, $productName$ is behind a layer 7 load balancer. Here, our example specifies that HTTP clients from the IP address range `99.99.0.0` - `99.99.255.255` will be allowed. - -You may specify as many ranges for each kind of keyword as desired. - -##### Rejecting Client Requests With Escaped Slashes - -* `reject_requests_with_escaped_slashes: true` will tell $productName$ to reject requests containing escaped slashes. The default is `false`. - -When set to `true`, $productName$ will reject any client requests that contain escaped slashes (`%2F`, `%2f`, `%5C`, or `%5c`) in their URI path by returning HTTP 400. By default, $productName$ will forward these requests unmodified. - -In general, a request with an escaped slash will _not_ match a `Mapping` prefix with an unescaped slash. However, external authentication services and other upstream services may handle escaped slashes differently, which can lead to security issues if paths with escaped slashes are allowed. By setting `reject_requests_with_escaped_slashes: true`, this class of security concern can be largely avoided. - -##### Trust downstream client IP - -* `use_remote_address: false` tells $productName$ that it cannot trust the remote address of incoming connections, and must instead rely exclusively on the `X-Forwarded-For` header. The default is `true`. - -When `true` (the default), $productName$ will append its own IP address to the `X-Forwarded-For` header so that upstream services of $productName$ can get the full set of IP addresses that have propagated a request. You may also need to set `externalTrafficPolicy: Local` on your `LoadBalancer` to propagate the original source IP address. - -See the [Envoy documentation on the `X-Forwarded-For header` ](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers) and the [Kubernetes documentation on preserving the client source IP](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/#preserving-the-client-source-ip) for more details. - -##### `X-Forwarded-For` trusted hops - -* `xff_num_trusted_hops` sets the default value for [the `l7Depth` setting of a `Listener`](../listener/#securitymodel). The default is 0. - -See the [`Listener` documentation](../listener/#securitymodel) for more details. - ---- - -## Service health / timeouts - -##### Incoming connection idle timeout - -* `listener_idle_timeout_ms` sets the idle timeout for incoming connections. The default is no timeout, meaning that incoming connections may remain idle forever. - -If set, this specifies the length of time (in milliseconds) that an incoming connection is allowed to be idle before being dropped. This can useful if you have proxies and/or firewalls in front of $productName$ and need to control how $productName$ initiates closing an idle TCP connection. - -Please see the [Envoy documentation on HTTP protocol options](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/protocol.proto#config-core-v3-httpprotocoloptions) for more information. - -##### Keepalive - -* `keepalive` sets the global TCP keepalive settings. - -$productName$ will use these settings for all `AmbasasdorMapping`s unless overridden in a `Mapping`'s configuration. Without `keepalive`, $productName$ follows the operating system defaults. - -For example, the following configuration: - -```yaml -keepalive: - time: 2 - interval: 2 - probes: 100 -``` - -would enable keepalives every two seconds (`interval`), starting after two seconds of idleness (`time`), with the connection being dropped if 100 keepalives are sent with no response (`probes`). For more information, see the [Envoy keepalive documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/core/v3/address.proto.html#config-core-v3-tcpkeepalive). - -##### Upstream idle timeout - -* `cluster_idle_timeout_ms` sets the default idle timeout for upstream connections (by default, one hour). - -If set, this specifies the timeout (in milliseconds) after which an idle connection upstream is closed. The idle timeout can be completely disabled by setting `cluster_idle_timeout_ms: 0`, which risks idle upstream connections never getting closed. - -If not set, the default idle timeout is one hour. - -You can override this setting with [`idle_timeout_ms` on a `Mapping`](../../using/timeouts/). - -##### Upstream max lifetime - -* `cluster_max_connection_lifetime_ms` sets the default maximum lifetime of an upstream connection. - -If set, this specifies the maximum amount of time (in milliseconds) after which an upstream connection is drained and closed, regardless of whether it is idle or not. Connection recreation incurs additional overhead when processing requests. The overhead tends to be nominal for plaintext (HTTP) connections within the same cluster, but may be more significant for secure HTTPS connections or upstreams with high latency. For this reason, it is generally recommended to set this value to at least 10000 ms to minimize the amortized cost of connection recreation while providing a reasonable bound for connection lifetime. - -If not set (or set to zero), then upstream connections may remain open for arbitrarily long. - -You can override this setting with [`cluster_max_connection_lifetime_ms` on a `Mapping`](../../using/timeouts/). - -##### Request timeout - -* `cluster_request_timeout_ms` sets the default end-to-end timeout for a single request. - -If set, this specifies the default end-to-end timeout for every request. - -If not set, the default is three seconds. - -You can override this setting with [`timeout_ms` on a `Mapping`](../../using/timeouts/). - -##### Readiness and liveness probes - -* `readiness_probe` sets whether `/ambassador/v0/check_ready` is automatically mapped -* `liveness_probe` sets whether `/ambassador/v0/check_alive` is automatically mapped - -By default, $productName$ creates `Mapping`s that support readiness and liveness checks at `/ambassador/v0/check_ready` and `/ambassador/v0/check_alive`. To disable the readiness `Mapping` entirely, set `readiness_probe.enabled` to `false`: - - -```yaml -readiness_probe: - enabled: false -``` - -Likewise, to disable the liveness `Mapping` entirely, set `liveness_probe.enabled` to `false`: - - -```yaml -liveness_probe: - enabled: false -``` - -A disabled probe endpoint will respond with 404; however, the service is still running, and will be accessible on localhost port 8877 from inside the $productName$ Pod. - -You can change these to route requests to some other service. For example, to have the readiness probe map to the `quote` application's health check: - -```yaml -readiness_probe: - enabled: true - service: quote - rewrite: /backend/health -``` - -The liveness and readiness probes both support `prefix` and `rewrite`, with the same meanings as for [Mappings](../../using/mappings). - -##### Retry policy - -This lets you add resilience to your services in case of request failures by performing automatic retries. - -```yaml -retry_policy: - retry_on: "5xx" -``` - ---- - -## Traffic management - -##### Circuit breaking - -* `circuit_breakers` sets the global circuit breaking configuration defaults - -You can override the circuit breaker settings for individual `Mapping`s. By default, $productName$ does not configure any circuit breakers. For more information, see the [circuit breaking reference](../../using/circuit-breakers). - -##### Default label domain and labels - -* `default_labels` sets default domains and labels to apply to every request. - -For more on how to use the default labels, , see the [Rate Limit reference](../../using/rate-limits/#attaching-labels-to-requests). - -##### Default load balancer - -* `load_balancer` sets the default load balancing type and policy - -For example, to set the default load balancer to `least_request`: - -```yaml -load_balancer: - policy: least_request -``` - -If not set, the default is to use round-robin load balancing. For more information, see the [load balancer reference](../load-balancer). diff --git a/content/en/docs/pre-release/topics/running/custom-error-responses.md b/content/en/docs/pre-release/topics/running/custom-error-responses.md deleted file mode 100644 index b0ad9877..00000000 --- a/content/en/docs/pre-release/topics/running/custom-error-responses.md +++ /dev/null @@ -1,217 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Custom error responses - -Custom error responses set overrides for HTTP response statuses generated either -by $productName$ or upstream services. - -They can be configured either on the $productName$ -[`Module`](../ambassador) -or on an [`Mapping`](../../using/intro-mappings/), the schema is identical. See -below for more information on [rule precedence](#rule-precedence). - -- `on_status_code`: HTTP status code to match for this rewrite - rule. Only 4xx and 5xx classes are supported. -- `body`: Describes the response body contents and format. - + `content_type`: A string that sets the content type of the - response. - + `text_format`: A string whose value will be used as the new - response body. `Content-Type` will default to `text/plain` if - unspecified. - + `json_format`: A config object whose keys and values will be - serialized as JSON and used as the new response body. - + `text_format_source`: Describes a file to be used as the - response. If used, `filename` must be set and the file must exist - on the $productName$ pod. - * `filename`: A file path on the $productName$ pod that will be used - as the new response body. - -Only one of `text_format`, `json_format`, or `text_format_source` may be provided. - -Custom response bodies are subject to Envoy's AccessLog substitution syntax -and variables, see [Envoy's documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#config-access-log-format-strings) for more information. - -Note that the AccessLog substitutions use `%` as a delimiter (for example, -`%RESPONSE_CODE%`). To include a literal `%` in a custom response body, use `%%`. -For example, - -``` -%%RESPONSE_CODE%% %RESPONSE_CODE% -``` - -would render as - -``` -%RESPONSE_CODE% 401 -``` - -for a request that resulted in a response code of 401. - - - If the % 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. - - -## Simple response bodies - -Simple responses can be be added quickly for convenience. They are inserted into -the manifest as either text or JSON: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador - namespace: ambassador -spec: - config: - error_response_overrides: - - on_status_code: 404 - body: - text_format: "File not found" - - on_status_code: 500 - body: - json_format: - error: "Application error" - status: "%RESPONSE_CODE%" - cluster: "%UPSTREAM_CLUSTER%" -``` -## File response bodies - -For more complex response bodies a file can be returned as the response. -This could be used for a customer friendly HTML document for example. Use -`text_format_source` with a `filename` set as a path on the $productName$ pod. -`content_type` should be used set the specific file type, such as `text/html`. - -First configure the $productName$ module: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador - namespace: ambassador -spec: - config: - error_response_overrides: - - on_status_code: 404 - body: - content_type: "text/html" - text_format_source: - filename: '/ambassador/ambassador-errorpages/404.html' -``` - -Then create the config map containing the HTML file: - -```yaml ---- -apiVersion: v1 -kind: ConfigMap -metadata: - name: ambassador-errorpages - namespace: ambassador -data: - 404.html: | - -

File not found

-

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/content/en/docs/pre-release/topics/running/debugging.md b/content/en/docs/pre-release/topics/running/debugging.md deleted file mode 100644 index bd376483..00000000 --- a/content/en/docs/pre-release/topics/running/debugging.md +++ /dev/null @@ -1,192 +0,0 @@ -# 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. - - - Enabling debug-level logging can produce a lot of log output — enough to - potentially impact the performance of $productName$. We don't recommend running with debug - logging enabled as a matter of course; it's usually better to enable it only when needed, - then reset logging to normal once you're finished debugging. - - -### $productName$ debug logging - -Much of $productName$'s logging is concerned with the business of noticing changes to -Kubernetes resources that specify the $productName$ configuration, and generating new -Envoy configuration in response to those changes. Enabling debug logging for this part -of the system is under the control of two environment variables: - -- Set `AES_LOG_LEVEL=debug` to debug the early boot sequence and $productName$'s interactions - with the Kubernetes cluster (finding changed resources, etc.). -- Set `AMBASSADOR_DEBUG=diagd` to debug the process of generating an Envoy configuration from - the input resources. - -### $productName$ Envoy logging - -Envoy logging is concerned with the actions Envoy is taking for incoming requests. -Typically, Envoy will only output access logs, and certain errors, but enabling Envoy -debug logging will show very verbose information about the actions Envoy is actually -taking. It can be useful for understanding why connections are being closed, or whether -an error status is coming from Envoy or from the upstream service. - -It is possible to enable Envoy logging at boot, but for the most part, it's safer to -enable it at runtime, right before sending a request that is known to have problems. -To enable Envoy debug logging, use `kubectl exec` to get a shell on the $productName$ -pod, then: - - ``` - curl -XPOST http://localhost:8001/logging?level=trace && \ - sleep 10 && \ - curl -XPOST http://localhost:8001/logging?level=warning - ``` - -This will turn on Envoy debug logging for ten seconds, then turn it off again. - -### Viewing logs - -To view the logs from $productName$: - -1. Use the following command to target an individual $productName$ Pod: `kubectl get pods -n $productNamespace$` - - The terminal will print something similar to the following: - - ``` - $ kubectl get pods -n $productNamespace$ - NAME READY STATUS RESTARTS AGE - $productDeploymentName$-85c4cf67b-4pfj2 1/1 Running 0 3m - ``` - -2. Then, run the following: `kubectl logs -n $productNamespace$ <$productDeploymentName$-pod-name>` - -The terminal will print something similar to the following: - - ``` - $ kubectl logs -n $productNamespace$ $productDeploymentName$-85c4cf67b-4pfj2 - 2018-10-10 12:26:50 kubewatch 0.40.0 INFO: generating config with gencount 1 (0 changes) - /usr/lib/python3.6/site-packages/pkg_resources/__init__.py:1235: UserWarning: /ambassador is writable by group/others and vulnerable to attack when used with get_resource_filename. Consider a more secure location (set with .set_extraction_path or the PYTHON_EGG_CACHE environment variable). - warnings.warn(msg, UserWarning) - 2018-10-10 12:26:51 kubewatch 0.40.0 INFO: Scout reports {"latest_version": "0.40.0", "application": "ambassador", "notices": [], "cached": false, "timestamp": 1539606411.061929} - - 2018-10-10 12:26:54 diagd 0.40.0 [P15TMainThread] INFO: thread count 3, listening on 0.0.0.0:8877 - [2018-10-10 12:26:54 +0000] [15] [INFO] Starting gunicorn 19.8.1 - [2018-10-10 12:26:54 +0000] [15] [INFO] Listening at: http://0.0.0.0:8877 (15) - [2018-10-10 12:26:54 +0000] [15] [INFO] Using worker: threads - [2018-10-10 12:26:54 +0000] [42] [INFO] Booting worker with pid: 42 - 2018-10-10 12:26:54 diagd 0.40.0 [P42TMainThread] INFO: Starting periodic updates - [2018-10-10 12:27:01.977][21][info][main] source/server/drain_manager_impl.cc:63] shutting down parent after drain - ``` - -Note that many deployments will have multiple logs, and the logs are independent for each Pod. - -## Examine Pod and container contents - -You can examine the contents of the $productName$ Pod for issues, such as if volume mounts are correct and TLS certificates are present in the required directory, to determine if the Pod has the latest $productName$ configuration, or if the generated Envoy configuration is correct or as expected. In these instructions, we will look for problems related to the Envoy configuration. - -1. To look into an $productName$ Pod, get a shell on the Pod using `kubectl exec`. For example, - - ``` - kubectl exec -it -n $productNamespace$ <$productDeploymentName$-pod-name> -- bash - ``` - -2. Determine the latest configuration. If you haven't overridden the configuration directory, the latest configuration will be in `/ambassador/snapshots`. If you have overridden it, $productName$ saves configurations in `$AMBASSADOR_CONFIG_BASE_DIR/snapshots`. - - In the snapshots directory: - - * `snapshot.yaml` contains the full input configuration that $productName$ has found; - * `aconf.json` contains the $productName$ configuration extracted from the snapshot; - * `ir.json` contains the IR constructed from the $productName$ configuration; and - * `econf.json` contains the Envoy configuration generated from the IR. - - In the snapshots directory, the current configuration will be stored in files with no digit suffix, and older configurations have increasing numbers. For example, `ir.json` is current, `ir-1.json` is the next oldest, then `ir-2.json`, etc. - -3. If something is wrong with `snapshot` or `aconf`, there is an issue with your configuration. If something is wrong with `ir` or `econf`, you should [open an issue on Github](https://github.com/emissary-ingress/emissary/issues/new/choose). - -4. The actual input provided to Envoy is split into `$AMBASSADOR_CONFIG_BASE_DIR/bootstrap-ads.json` and `$AMBASSADOR_CONFIG_BASE_DIR/envoy/envoy.json`. - - - The `bootstrap-ads.json` file contains details about Envoy statistics, logging, authentication, etc. - - The `envoy.json` file contains information about request routing. - - You may generally find it simplest to just look at the `econf.json` files in the `snapshot` - directory, which includes both kinds of configuration. diff --git a/content/en/docs/pre-release/topics/running/diagnostics.md b/content/en/docs/pre-release/topics/running/diagnostics.md deleted file mode 100644 index 20506304..00000000 --- a/content/en/docs/pre-release/topics/running/diagnostics.md +++ /dev/null @@ -1,54 +0,0 @@ -# Diagnostics - -With $productName$ Diagnostics and Ambassador Cloud, you get a summary of the current status and Mappings of your cluster and it's services, which gets displayed -in [Diagnostics Overview](https://www.getambassador.io/docs/cloud/latest/diagnostics-ui/view-diagnostics/). - -## Troubleshooting - -### Can't access $productName$ Diagnostics Overview? - -Create an Ambassador `Module` if one does not already exist, and add the following config to enable diagnostics data. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - diagnostics: - enabled: true -``` -Next, ensure that the 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/content/en/docs/pre-release/topics/running/environment.md b/content/en/docs/pre-release/topics/running/environment.md deleted file mode 100644 index 265fcedd..00000000 --- a/content/en/docs/pre-release/topics/running/environment.md +++ /dev/null @@ -1,366 +0,0 @@ -# $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/content/en/docs/pre-release/topics/running/gzip.md b/content/en/docs/pre-release/topics/running/gzip.md deleted file mode 100644 index e3005c83..00000000 --- a/content/en/docs/pre-release/topics/running/gzip.md +++ /dev/null @@ -1,55 +0,0 @@ -# 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/content/en/docs/pre-release/topics/running/host-crd.md b/content/en/docs/pre-release/topics/running/host-crd.md deleted file mode 100644 index cd187ebe..00000000 --- a/content/en/docs/pre-release/topics/running/host-crd.md +++ /dev/null @@ -1,279 +0,0 @@ -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` - - - Remember that Listener resources are required for a functioning - $productName$ installation!
- Learn more about Listener. - - - - Remember than $productName$ does not make sure that a wildcard Host exists! If the - wildcard behavior is needed, a Host with a hostname of "*" - must be defined by the user. - - -A minimal `Host` resource, assuming no TLS configuration, would be: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: minimal-host -spec: - hostname: host.example.com -``` - -This `Host` tells $productName$ to expect to be reached at `host.example.com`, -with no TLS termination, and only associating with `Mapping`s that also set a -`hostname` that matches `host.example.com`. - -Remember that a 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/content/en/docs/pre-release/topics/running/http3.md b/content/en/docs/pre-release/topics/running/http3.md deleted file mode 100644 index 9aeb6cac..00000000 --- a/content/en/docs/pre-release/topics/running/http3.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -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`. - - -The protocolStack elements need to be entered in the specific order of TLS, HTTP, UDP. - - -The `Listener` configured for HTTP/3 can be bound to the same address and port (`0.0.0.0:8443`) as the `Listener` that supports HTTP/2 and HTTP/1.1. This is not required, but it allows $productName$ to inject the default `alt-svc: h3=":443"; ma=86400, h3-29=":443"; ma=86400` header into the responses returned over the TCP connection with no additional configuration needed. **Most clients such as browsers require the `alt-svc` header to upgrade to HTTP/3**. - - -The current default of 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. - - -```yaml -# This is a standard Listener that leverages TCP to serve HTTP/2 and HTTP/1.1 traffic. -# It is bound to the same address and port (0.0.0.0:8443) as the UDP listener. -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: $productDeploymentName$-https-listener - namespace: $productNamespace$ -spec: - port: 8443 - protocol: HTTPS - securityModel: XFP - hostBinding: - namespace: - from: ALL ---- -# This is a Listener that leverages UDP and HTTP to serve HTTP/3 traffic. -# NOTE: Raw UDP traffic is not supported. UDP and HTTP must be used together. -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: $productDeploymentName$-https-listener-udp - namespace: $productNamespace$ -spec: - port: 8443 - # Order is important here. HTTP is required. - protocolStack: - - TLS - - HTTP - - UDP - securityModel: XFP - hostBinding: - namespace: - from: ALL -``` - -### Configuring the Host resource - -Because the QUIC network requires TLS, the certificate needs to be valid so the client can upgrade a connection to HTTP/3. See the [Host documentation](./host-crd.md) for more information on how to configure TLS for a `Host`. - -### Certificate verification - -Clients can only upgrade to an HTTP/3 connection with a valid certificate. If the client won’t upgrade to HTTP/3, verify that you have a valid TLS certificate and that your client can speak **TLS v1.3**. Your `Host` resource should be configured similar to the following: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: my-domain-host -spec: - hostname: your-hostname - # acme isn't required but just shown as an example of how to manage a valid TLS cert - acmeProvider: - email: your-email@example.com - authority: https://acme-v02.api.letsencrypt.org/directory - tls: - # QUIC requires TLS v1.3 version. Verify your client supports it. - min_tls_version: v1.3 - # Either protocol can be upgraded, but http/2 is recommended. - alpn_protocols: h2,http/1.1 -``` - -### External load balancers - -The two most common service types to expose traffic outside of a Kubernetes cluster are: - -- `LoadBalancer`: A load balancer controller generates and manages the cloud provider-specific external load balancer. -- `NodePort`: The platform administrator has to manually set up things like the external load balancer, firewall rules, and health checks. - -#### LoadBalancer setup - -The ideal setup would be to configure a single service of type `LoadBalancer`, but this comes with some current restrictions: -- You need version 1.24 or later of Kubernetes with the [`MixedProtocolLBService` feature enabled](https://kubernetes.io/docs/concepts/services-networking/service/#load-balancers-with-mixed-protocol-types). -- Your cloud service provider needs to support the creation of an external load balancer with mixed protocol types (TCP/UDP), port reuse, and port forwarding. Support for Kubernetes feature flags may vary between cloud service providers. Refer to your provider’s documentation to see if they support this scenario. - -An example `LoadBalancer` configuration that fits the criteria listed above: - -```yaml - -# note: extra fields such as labels and selectors removed for clarity -apiVersion: v1 -kind: Service -metadata: - name: $productDeploymentName$ - namespace: $productNamespace$ -spec: - ports: - - name: http - port: 80 - targetPort: 8080 - protocol: TCP - - name: https - port: 443 - targetPort: 8443 - protocol: TCP - - name: http3 - port: 443 - targetPort: 8443 - protocol: UDP - type: LoadBalancer -``` - -## Cloud service provider setup - -Once you've completed the steps above, you need to configure HTTP/3 support through your cloud service provider. The configuration processes for each provider can be found here: - -- HTTP/3 setup for [Amazon Elastic Kubernetes Service (EKS)](../../../howtos/http3-eks) -- HTTP/3 setup for [Azure Kubernetes Service (AKS)](../../../howtos/http3-aks) -- HTTP/3 setup for [Google Kubernetes Engine (GKE)](../../../howtos/http3-gke) diff --git a/content/en/docs/pre-release/topics/running/index.md b/content/en/docs/pre-release/topics/running/index.md deleted file mode 100644 index 6eb7af94..00000000 --- a/content/en/docs/pre-release/topics/running/index.md +++ /dev/null @@ -1,16 +0,0 @@ -# Running $productName$ in production - -This section of the documentation is designed for operators and site reliability engineers who are managing the deployment of $productName$. Learn more below: - -* *Global Configuration:* The [Ambassador module](ambassador) is used to set system-wide configuration. -* *Exposing $productName$ to the Internet:* The [`Listener` CRD](listener) defines which ports are exposed, including their protocols and security models. The [`Host` CRD](host-crd) defines how $productName$ manages TLS, domains, and such. -* *Load Balancing:* $productName$ supports a number of different [load balancing strategies](load-balancer) as well as different ways to configure [service discovery](resolvers) -* [Gzip Compression](gzip) -* *Deploying $productName$:* On [Amazon Web Services](ambassador-with-aws) | [Google Cloud](ambassador-with-gke) | [general security and operational notes](running), including running multiple $productNamePlural$ on a cluster -* *TLS/SSL:* [Simultaneously Routing HTTP and HTTPS](tls/cleartext-redirection#cleartext-routing) | [HTTP -> HTTPS Redirection](tls/cleartext-redirection#http-https-redirection) | [Mutual TLS](tls/mtls) | [TLS origination](tls/origination) -* *Statistics and Monitoring:* [Integrating with Prometheus, DataDog, and other monitoring systems](statistics) -* *Extending $productName$* $productName$ can be extended with custom plug-ins that connect via HTTP/gRPC interfaces. [Custom Authentication](services/auth-service) | [The External Auth protocol](services/ext-authz) | [Custom Logging](services/log-service) | [Rate Limiting](services/rate-limit-service) | [Distributed Tracing](services/tracing-service) -* *Troubleshooting:* [Diagnostics](diagnostics) | [Debugging](debugging) -* *Scaling $productName$:* [Scaling $productName$](scaling) -* *Ingress:* $productName$ can function as an [Ingress Controller](ingress-controller) -* *Error Response Overrides:* $productName$ can override 4xx and 5xx responses with [custom response bodies](custom-error-responses) diff --git a/content/en/docs/pre-release/topics/running/ingress-controller.md b/content/en/docs/pre-release/topics/running/ingress-controller.md deleted file mode 100644 index 9b7afb82..00000000 --- a/content/en/docs/pre-release/topics/running/ingress-controller.md +++ /dev/null @@ -1,325 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Ingress controller - -
-

Contents

- -- [When and how to use the Ingress resource](#when-and-how-to-use-the-ingress-resource) -- [What is required to use the Ingress resource?](#what-is-required-to-use-the-ingress-resource) -- [When to use an Ingress instead of annotations or CRDs](#when-to-use-an-ingress-instead-of-annotations-or-crds) -- [Ingress support](#ingress-support) -- [Examples of Ingress configs vs Mapping configs](#examples-of-ingress-configs-vs-mapping-configs) -- [Ingress routes and mappings](#ingress-routes-and-mappings) -- [The Minimal Ingress](#the-minimal-ingress) -- [Name based virtual hosting with an Ambassador ID](#name-based-virtual-hosting-with-an-ambassador-id) -- [TLS Termination](#tls-termination) - -
- -An Ingress resource is a popular way to expose Kubernetes services to the Internet. In order to use Ingress resources, you need to install an [ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/). $productName$ can function as a fully-fledged Ingress controller, making it easy to work with other Ingress-oriented tools within the Kubernetes ecosystem. - -## When and how to use the Ingress resource - -If you're new to $productName$ and to Kubernetes, we'd recommend you start with our [quickstart](../../../tutorials/getting-started/) instead of this Ingress guide. If you're a power user and need to integrate with other software that leverages the Ingress resource, read on. The Ingress specification is very basic and does not support many of the features of $productName$, so you'll be using both the Ingress resource and $productName$'s Mapping resource to manage your Kubernetes services. - -### What is required to use the Ingress resource? - -- Know what version of Kubernetes you are using. - - - In Kubernetes 1.13 and below, the Ingress was only included in the `extensions` API. - - - Starting in Kubernetes 1.14, the Ingress was added to the new `networking.k8s.io` API. - - - Kubernetes 1.18 introduced the IngressClass resource to the existing `networking.k8s.io/v1beta1` API. - - If you are using 1.14 and above, it is recommended to use 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. - - -- You will need RBAC permissions to create Ingress resources in either - the `extensions` `apiGroup` (present in all supported versions of - Kubernetes) or the `networking.k8s.io` `apiGroup` (introduced in - Kubernetes 1.14). - -- $productName$ will need RBAC permissions to get, list, watch, and update Ingress resources. - - You can see this in the [`aes-crds.yaml`](https://app.getambassador.io/yaml/ambassador-docs/latest/aes.yaml) - file, but this is the critical rule to add to $productName$'s `Role` or `ClusterRole`: - - ```yaml - - apiGroups: ['extensions', 'networking.k8s.io'] - resources: ['ingresses', 'ingressclasses'] - verbs: ['get', 'list', 'watch'] - - apiGroups: ['extensions', 'networking.k8s.io'] - resources: ['ingresses/status'] - verbs: ['update'] - ``` - - - This is included by default in all $productName$ installations. - - -- You must create your Ingress resource with the correct `ingress.class`. - - $productName$ will automatically read Ingress resources with the annotation - `kubernetes.io/ingress.class: ambassador`. - -- You may need to set your Ingress resource's `ambassador-id`. - - If you are [using `amabssador-id` on your Module](../running/#ambassador_id), you'll need to add the `getambassador.io/ambassador-id` - annotation to your Ingress. See the [examples below](#name-based-virtual-hosting-with-an-ambassador-id). - -- You must create a Service resource with the correct `app.kubernetes.io/component` label. - - $productName$ will automatically load balance Ingress resources using the endpoint exposed - from the Service with the annotation `app.kubernetes.io/component: ambassador-service`. - - ```yaml - --- - kind: Service - apiVersion: v1 - metadata: - name: ingress-ambassador - labels: - app.kubernetes.io/component: ambassador-service - spec: - externalTrafficPolicy: Local - type: LoadBalancer - selector: - service: ambassador - ports: - - name: http - port: 80 - targetPort: http - - name: https - port: 443 - targetPort: https - ``` - -### When to use an Ingress instead of annotations or CRDs - -We recommend that $productName$ be configured using CRDs. The Ingress resource is available to users who need it for integration with other ecosystem tools, or who feel that it more closely matches their workflows. However, it is important to recognize that the Ingress resource is rather more limited than the $productName$ Mapping is (for example, the Ingress spec has no support for rewriting or for TLS origination). **When in doubt, use CRDs.** - -## Ingress support - -$productName$ supports basic core functionality of the Ingress resource, as defined by the [Ingress resource](https://kubernetes.io/docs/concepts/services-networking/ingress/) itself: - -- Basic routing is supported, including the `route` specification and the default backend functionality. It's particularly easy to use a minimal Ingress to the $productName$ diagnostic UI. -- [TLS termination](../tls/) is supported. You can use multiple Ingress resources for SNI. -- Using the Ingress resource in concert with $productName$ CRDs or annotations is supported. This includes $productName$ annotations on the Ingress resource itself. - -$productName$ does **not** extend the basic Ingress specification with the following exceptions: - -- The `getambassador.io/ambassador-id` annotation allows you to set [the Ambassador ID](../running/#ambassador_id) for the Ingress itself. - -- The `getambassador.io/config` annotation can be provided on the Ingress resource, just as on a Service. - -Note that if you need to set `getambassador.io/ambassador-id` on the Ingress, you will also need to set `ambassador-id` on resources within the annotation. - -## Examples of Ingress configs vs Mapping configs - -### Ingress routes and Mappings - -$productName$ actually creates Mapping objects from the Ingress route rules. These Mapping objects interact with Mappings defined in CRDs **exactly** as they would if the Ingress route rules had been specified with CRDs originally. - -For example, this Ingress resource routes traffic to `/foo/` to `service1`: - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: test-ingress -spec: - rules: - - http: - paths: - - path: /foo/ - backend: - serviceName: service1 - servicePort: 80 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: test-ingress-0-0 -spec: - hostname: '*' - prefix: /foo/ - service: service1:80 -``` - -This YAML will set up $productName$ to do canary routing where 50% of the traffic will go to `service1` and 50% will go to `service2`. - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: test-ingress -spec: - rules: - - http: - paths: - - path: /foo/ - backend: - serviceName: service1 - servicePort: 80 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: my-mapping -spec: - hostname: '*' - prefix: /foo/ - service: service2 -``` - -### The minimal Ingress - -An Ingress resource must provide at least some routes or a [default backend](https://kubernetes.io/docs/concepts/services-networking/ingress/#default-backend). The default backend provides for a simple way to direct all traffic to some upstream service: - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: test-ingress -spec: - backend: - serviceName: exampleservice - servicePort: 8080 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: test-ingress -spec: - hostname: '*' - prefix: / - service: exampleservice:8080 -``` - -### Name based virtual hosting with an Ambassador ID - -This Ingress resource will result in all requests to `foo.bar.com` going to `service1`, and requests to `bar.foo.com` going to `service2`: - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - getambassador.io/ambassador-id: externalid - name: name-virtual-host-ingress -spec: - rules: - - host: foo.bar.com - http: - paths: - - backend: - serviceName: service1 - servicePort: 80 - - host: bar.foo.com - http: - paths: - - backend: - serviceName: service2 - servicePort: 80 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: host-foo-mapping -spec: - ambassador_id: ['externalid'] - prefix: / - host: foo.bar.com - service: service1 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: host-bar-mapping -spec: - ambassador_id: ['externalid'] - prefix: / - host: bar.foo.com - service: service2 -``` - -Read more on the [Kubernetes documentation on name based virtual routing](https://kubernetes.io/docs/concepts/services-networking/ingress/#name-based-virtual-hosting). - -### TLS termination - -```yaml ---- -apiVersion: extensions/v1beta1 -kind: Ingress -metadata: - annotations: - kubernetes.io/ingress.class: ambassador - name: tls-example-ingress -spec: - tls: - - hosts: - - sslexample.foo.com - secretName: testsecret-tls - rules: - - host: sslexample.foo.com - http: - paths: - - path: / - backend: - serviceName: service1 - servicePort: 80 -``` - -This is the equivalent configuration using a Mapping instead: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: sslexample-termination-context -spec: - hosts: - - sslexample.foo.com - secret: testsecret-tls ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: sslexample-mapping -spec: - host: sslexample.foo.com - prefix: / - service: service1 -``` - -Note that this shows TLS termination, not origination: the Ingress spec does not support origination. Read more on the [Kubernetes docs on TLS termination](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls). diff --git a/content/en/docs/pre-release/topics/running/listener.md b/content/en/docs/pre-release/topics/running/listener.md deleted file mode 100644 index 152e1b74..00000000 --- a/content/en/docs/pre-release/topics/running/listener.md +++ /dev/null @@ -1,218 +0,0 @@ -# The `Listener` CRD - -The `Listener` CRD defines where, and how, $productName$ should listen for requests from the network, and which `Host` definitions should be used to process those requests. For further examples of how to use `Listener`, see [Configuring $productName$ Communications](../../../howtos/configure-communications). - -**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. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 # int32, port number on which to listen - protocol: HTTPS # HTTP, HTTPS, HTTPPROXY, HTTPSPROXY, TCP - securityModel: XFP # XFP (for X-Forwarded-Proto), SECURE, INSECURE - statsPrefix: example-listener # default depends on protocol; see below - l7Depth: 0 # int32 - hostBinding: - namespace: - from: SELF # SELF, ALL - selector: ... # Kubernetes label selector -``` - -| Element | Type | Definition | -| :------ | :--- | :--------- | -| `port` | `int32` | The network port on which $productName$ should listen. *Required.* | -| `protocol` | `enum`; see below | A high-level protocol type, like "HTTPS". *Exactly one of `protocol` and `protocolStack` must be supplied.* | -| `protocolStack` | array of `enum`; see below | A sequence of low-level protocols to layer together. *Exactly one of `protocol` and `protocolStack` must be supplied.* | -| `securityModel` | `enum`; see below | How does $productName$ decide whether requests here are secure? *Required.* | -| `statsPrefix` | `string`; see below | Under what name do statistics for this `Listener` appear? *Optional; default depends on protocol.* | -| `l7Depth` | `int32` | How many layer 7 load balancers are between the edge of the network and $productName$? *Optional; default is 0.*| -| `hostBinding` | `struct`, see below | Mechanism for determining which `Host`s will be associated with this `Listener`. *Required* | - -### `protocol` and `protocolStack` - -`protocol` is the **recommended** way to tell $productName$ that a `Listener` expects connections using a well-known protocol. When using `protocol`, `protocolStack` may not also be supplied. - -Valid `protocol` values are: - -| `protocol` | Description | -| :--------- | :---------- | -| `HTTP` | Cleartext-only HTTP. HTTPS is not allowed. | -| `HTTPS` | Either HTTPS or HTTP -- Envoy's TLS support can tell whether or not TLS is in use, and it will set `X-Forwarded-Proto` correctly for later decision-making. | -| `HTTPPROXY` | Cleartext-only HTTP, using the HAProxy `PROXY` protocol. | -| `HTTPSPROXY` | Either HTTPS or HTTP, using the HAProxy `PROXY` protocol. | -| `TCP` | TCP sessions without HTTP at all. You will need to use `TCPMapping`s to route requests for this `Listener`. | -| `TLS` | TLS sessions without HTTP at all. You will need to use `TCPMapping`s to route requests for this `Listener`. | - -### `securityModel` - -`securityModel` defines how the `Listener` will decide whether a request is secure or insecure: - -| `securityModel` | Description | -| :--------- | :---------- | -| `XFP` | Requests are secure if, and only if, `X-Forwarded-Proto` indicates HTTPS. This is common; see below. | -| `SECURE` | Requests are always secure. You might set this if your load balancer always terminates TLS for you, and you can trust the clients. | -| `INSECURE` | Requests are always insecure. You might set this for an HTTP-only `Listener`, or a `Listener` for clients that are expected to be hostile. | - -The `X-Forwarded-Proto` header mentioned above is meant to reflect the protocol the _original client_ -used to contact $productName$. When no layer 7 proxies are in use, Envoy will make certain that the -`X-Forwarded-Proto` header matches the wire protocol of the connection the client made to Envoy, -which allows $productName$ to trust `X-Forwarded-Proto` for routing decisions such as deciding to -redirect requests made using HTTP over to HTTPS for greater security. When using $productName$ as an -edge proxy or a typical API gateway, this is a desirable configuration; setting `securityModel` to -`XFP` makes this easy. - -When layer proxies _are_ in use, the `XFP` setting is often still desirable; however, you will also -need to set `l7Depth` to allow it to function. See below. - -`SECURE` and `INSECURE` are helpful for cases where something downstream of $productName$ should be -allowing only one kind of request to reach $productName$. For example, a `Listener` behind a load -balancer that terminates TLS and checks client certificates might use -`SecurityModel: SECURE`, then use `Host`s to reject insecure requests if one somehow -arrives. - -### `l7Depth` - -When layer 7 (L7) proxies are in use, the connection to $productName$ comes from the L7 proxy itself -rather than from the client. Examining the protocol and IP address of that connection is useless, and -instead you need to configure the L7 proxy to pass extra information about the client to $productName$ -using the `X-Forwarded-Proto` and `X-Forwarded-For` headers. - -However, if $productName$ always trusted `X-Forwarded-Proto` and `X-Forwarded-For`, any client could -use them to lie about itself to $productName$. As a security mechanism, therefore, you must _also_ -set `l7Depth` in the `Listener` to the number of trusted L7 proxies in front of $productName$. If -`l7Depth` is not set in the `Listener`, the `xff_num_trusted_hops` value from the `ambassador` `Module` -will be used. If neither is set, the default `l7Depth` is 0. - -When `l7Depth` is 0, any incoming `X-Forwarded-Proto` is stripped: Envoy always provides an -`X-Forwarded-Proto` matching the wire protocol of the incoming connection, so that `X-Forwarded-Proto` -can be trusted. When `l7Depth` is non-zero, `X-Forwarded-Proto` is accepted from the L7 proxy, and -trusted. The actual wire protocol in use from the L7 proxy to $productName$ is ignored. - -`l7Depth` also affects $productName$'s view of the client's source IP address, which is used as the -`remote_address` field when rate limiting, and for the `X-Envoy-External-Address` header: - -- When `l7Depth` is 0, $productName$ uses the IP address of the incoming connection. -- When `l7Depth` is some value N that is non-zero, the behavior is determined by the value of - `use_remote_address` in the `ambassador` `Module`: - - - When `use_remote_address` is true (the default) then the trusted client address will be the Nth - address from the right end of the `X-Forwarded-For` header. (If the XFF contains fewer than N - addresses, Envoy falls back to using the immediate downstream connection’s source address as a - trusted client address.) - - - When `use_remote_address` is false, the trusted client address is the (N+1)th address from the - right end of XFF. (If the XFF contains fewer than N+1 addresses, Envoy falls back to using the - immediate downstream connection’s source address as a trusted client address.) - - For more detailed examples of this interaction, refer to [Envoy's documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers.html#x-forwarded-for). - - -### `hostBinding` - -`hostBinding` specifies how this `Listener` should determine which `Host`s are associated with it: - -- `namespace.from` allows filtering `Host`s by the namespace of the `Host`: - - `namespace.from: SELF` accepts only `Host`s in the same namespace as the `Listener`. - - `namespace.from: ALL` accepts `Host`s in any namespace. -- `selector` accepts only `Host`s that has labels matching the selector. - -`hostBinding` is mandatory, and at least one of `namespace.from` and `selector` must be set. If both are set, both must match for a `Host` to be accepted. - -### `statsPrefix` - -$productName$ produces detailed [statistics](../statistics) which can be monitored in a variety of ways. Statistics have hierarchical names, and the `Listener` will cause a set of statistics to be logged under the name specified by `statsPrefix`. - -The default `statsPrefix` depends on the protocol for this `Listener`: - -- If the `Listener` speaks HTTPS, the default is `ingress-https`. -- Otherwise, if the `Listener` speaks HTTP, the default is `ingress-http`. -- Otherwise, if the `Listener` speaks TLS, the default is `ingress-tls-$port`. -- Otherwise, the default is `ingress-$port`. - -Note that it doesn't matter whether you use `protocol` or `protocolStack`: what matters is what protocol is actually configured. Also note that the default doesn't take the HAProxy `PROXY` protocol into account. - -Some examples: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 - protocol: HTTPS - ... -``` - -will use a `statsPrefix` of `ingress-https`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 - protocol: TCP - ... -``` - -will use `statsPrefix` of `ingress-8080`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Listener -metadata: - name: example-listener -spec: - port: 8080 - protocol: HTTPSPROXY - statsPrefix: proxy-8080 - ... -``` - -would also use `ingress-https`, but it explicitly overrides `statsPrefix` to `proxy-8080`. - -For complete information on which statistics will appear for the `Listener`, see [the Envoy listener statistics documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/listeners/stats.html). Some important statistics include - -| Statistic name | Type | Description | -| :-----------------------------------------------| :-------- | :-------------------------------- | -| `listener.$statsPrefix.downstream_cx_total` | Counter | Total connections | -| `listener.$statsPrefix.downstream_cx_active` | Gauge | Total active connections | -| `listener.$statsPrefix.downstream_cx_length_ms` | Histogram | Connection length in milliseconds | - -### `protocolStack` - -**`protocolStack` is not recommended if you can instead use `protocol`.** - -Where `protocol` allows configuring the `Listener` to use well-known protocol stacks, `protocolStack` allows configuring exactly which protocols will be layered together. If `protocol` allows what you need, it is safer to use `Protocol` than to risk having the stack broken with an incorrect `protocolStack`. - -The possible stack elements are: - -| `ProtocolStack` Element | Description | -| :---------------------- | :---------- | -| `HTTP` | Cleartext-only HTTP; must be layered with `TLS` for HTTPS | -| `PROXY` | The HAProxy `PROXY` protocol | -| `TLS` | TLS | -| `TCP` | Raw TCP | - -`protocolStack` supplies a list of these elements to describe the protocol stack. **Order matters.** Some examples: - -| `protocolStack` | Description | -| :-------------- | :---------- | -| [ `HTTP`, `TCP` ] | Cleartext-only HTTP, exactly equivalent to `protocol: HTTP`. | -| [ `TLS`, `HTTP`, `TCP` ] | HTTPS or HTTP, exactly equivalent to `protocol: HTTPS`. | -| [ `PROXY`, `TLS`, `TCP` ] | The `PROXY` protocol, wrapping `TLS` _afterward_, wrapping raw TCP. This isn't equivalent to any `protocol` setting, and may be nonsensical. | - -## Examples - -For further examples of how to use `Listener`, see [Configuring $productName$ to Communicate](../../../howtos/configure-communications). diff --git a/content/en/docs/pre-release/topics/running/load-balancer.md b/content/en/docs/pre-release/topics/running/load-balancer.md deleted file mode 100644 index 987a910b..00000000 --- a/content/en/docs/pre-release/topics/running/load-balancer.md +++ /dev/null @@ -1,209 +0,0 @@ -# Load balancing - -Load balancing configuration can be set for all $productName$ mappings in the [`ambassador` `Module`](../ambassador), or set per [`Mapping`](../../using/mappings). If nothing is set, simple round robin balancing is used via Kubernetes services. - -To use advanced load balancing, you must first configure a [resolver](../resolvers) that supports advanced load balancing (e.g., the Kubernetes Endpoint Resolver or Consul Resolver). Once a resolver is configured, you can use the `load_balancer` attribute. The following fields are supported: - -```yaml -load_balancer: - policy: -``` - -Supported load balancer policies: - -- `round_robin` -- `least_request` -- `ring_hash` -- `maglev` - -For more information on the different policies and the implications, see [load balancing strategies in Kubernetes](https://blog.getambassador.io/load-balancing-strategies-in-kubernetes-l4-round-robin-l7-round-robin-ring-hash-and-more-6a5b81595d6c). - -## Round robin -When `policy` is set to `round_robin`, $productName$ discovers healthy endpoints for the given mapping, and load balances the incoming L7 requests with round robin scheduling. To specify this: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - resolver: my-resolver - load_balancer: - policy: round_robin -``` - -or, per mapping: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - resolver: my-resolver - hostname: '*' - load_balancer: - policy: round_robin -``` - -Note that load balancing may not appear to be "even" due to Envoy's threading model. For more details, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/faq/load_balancing/concurrency_lb). - -## Least request - -When `policy` is set to `least_request`, $productName$ discovers healthy endpoints for the given mapping, and load balances the incoming L7 requests to the endpoint with the fewest active requests. To specify this: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - resolver: my-resolver - load_balancer: - policy: least_request -``` - -or, per mapping: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend/ -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: least_request -``` - -## Sticky sessions / session affinity - -Configuring sticky sessions makes $productName$ route requests to a specific pod providing your service in a given session. One pod serves all requests from a given session, eliminating the need for session data to be transferred between pods. $productName$ lets you configure session affinity based on the following parameters in an incoming request: - -- Cookie -- Header -- Source IP - -**NOTE:** $productName$ supports sticky sessions using two load balancing policies, `ring_hash` and `maglev`. - -### Cookie - -```yaml -load_balancer: - policy: ring_hash - cookie: - name: - ttl: - path: -``` - -If the cookie you wish to set affinity on is already present in incoming requests, then you only need the `cookie.name` field. However, if you want $productName$ to generate and set a cookie in response to the first request, then you need to specify a value for the `cookie.ttl` field which generates a cookie with the given expiration time. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - hostname: '*' - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - cookie: - name: sticky-cookie - ttl: 60s -``` - -### Header - -```yaml -load_balancer: - policy: ring_hash - header:
-``` - -$productName$ allows header based session affinity if the given header is present on incoming requests. - -Example: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - header: STICKY_HEADER -``` - -#### Source IP - -```yaml -load_balancer: - policy: ring_hash - source_ip: -``` - -$productName$ allows session affinity based on the source IP of incoming requests. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - source_ip: true -``` - -Load balancing can be configured both globally, and overridden on a per mapping basis. The following example configures the default load balancing policy to be round robin, while using header-based session affinity for requests to the `/backend/` endpoint of the quote application: - -Load balancing can be configured both globally, and overridden on a per mapping basis. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - resolver: my-resolver - load_balancer: - policy: round_robin -``` - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - resolver: my-resolver - load_balancer: - policy: ring_hash - header: STICKY_HEADER -``` diff --git a/content/en/docs/pre-release/topics/running/resolvers.md b/content/en/docs/pre-release/topics/running/resolvers.md deleted file mode 100644 index 1ace9a86..00000000 --- a/content/en/docs/pre-release/topics/running/resolvers.md +++ /dev/null @@ -1,128 +0,0 @@ -# Service discovery and resolvers - -Service discovery is how cloud applications and their microservices are located on the network. In a cloud environment, services are ephemeral, existing only as long as they are needed and in use, so a real-time service discovery mechanism is required. $productName$ uses information from service discovery to determine where to route incoming requests. - -## $productName$ support for service discovery - -$productName$ supports different mechanisms for service discovery. These mechanisms are: - -* Kubernetes service-level discovery (default). -* Kubernetes endpoint-level discovery. -* Consul endpoint-level discovery. - -### Kubernetes service-level discovery - -By default, $productName$ uses Kubernetes DNS and service-level discovery. In a `Mapping` resource, specifying `service: foo` will prompt $productName$ to look up the DNS address of the `foo` Kubernetes service. Traffic will be routed to the `foo` service. Kubernetes will then load balance that traffic between multiple pods. For more details on Kubernetes networking and how this works, see our blog post on [Session affinity, load balancing controls, gRPC-Web, and $productName$](https://blog.getambassador.io/session-affinity-load-balancing-controls-grpc-web-and-ambassador-0-52-2b916b396d0c). - -### Kubernetes endpoint-level discovery - -$productName$ can also watch Kubernetes endpoints. This bypasses the Kubernetes service routing layer and enables the use of advanced load balancing controls such as session affinity and maglev. For more details, see the [load balancing reference](../load-balancer). - -### Consul endpoint-level discovery - -$productName$ natively integrates with [Consul](https://www.consul.io) for endpoint-level service discovery. In this mode, $productName$ obtains endpoint information from Consul. One of the primary use cases for this architecture is in hybrid cloud environments that run a mixture of Kubernetes services as well as VMs, as Consul can serve as the single global registry for all services. - -## The Resolver resource - -The `Resolver` resource is used to configure the discovery service strategy for $productName$. - -### The Kubernetes service resolver - -The Kubernetes Service Resolver configures $productName$ to use Kubernetes services. If no resolver is specified, this behavior is the default. When this resolver is used, the `service.namespace` value from a `Mapping` is handed to the Kubernetes cluster's DNS resolver to determine where requests are sent. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: KubernetesServiceResolver -metadata: - name: kubernetes-service -``` - -### The Kubernetes endpoint resolver - -The Kubernetes Endpoint Resolver configures $productName$ to resolve Kubernetes endpoints. This enables the use of more a [advanced load balancing configuration](../load-balancer). When this resolver is used, the endpoints for the `service` defined in a `Mapping` are resolved and used to determine where requests are sent. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: KubernetesEndpointResolver -metadata: - name: endpoint -``` - -### The Consul resolver - -The Consul Resolver configures $productName$ to use Consul for service discovery. When this resolver is used, the `service` defined in a `Mapping` is passed to Consul, along with the datacenter specified, to determine where requests are sent. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: ConsulResolver -metadata: - name: consul-dc1 -spec: - address: consul-server.default.svc.cluster.local:8500 - datacenter: dc1 -``` -- `address`: The fully-qualified domain name or IP address of your Consul server. This field also supports environment variable substitution. -- `datacenter`: The Consul data center where your services are registered - -You may want to use an environment variable if you're running a Consul agent on each node in your cluster. In this setup, you could do the following: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: ConsulResolver -metadata: - name: consul-dc1 -spec: - address: "${HOST_IP}" - datacenter: dc1 -``` - -and then add the `HOST_IP` environment variable to your Kubernetes deployment: - -```yaml -containers: - - name: example - image: docker.io/datawire/ambassador:$version$ - env: - - name: HOST_IP - valueFrom: - fieldRef: - fieldPath: status.hostIP -``` - -## Using resolvers - -Once a resolver is defined, you can use them in a given `Mapping`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: "*" - prefix: /backend/ - service: quote - resolver: endpoint - load_balancer: - policy: round_robin ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: bar -spec: - hostname: "*" - prefix: /bar/ - service: https://bar:9000 - tls: client-context - resolver: consul-dc1 - load_balancer: - policy: round_robin -``` - -The YAML configuration above will configure $productName$ to use Kubernetes Service Discovery to route to the Consul Service Discovery to route to the `bar` service on requests with `prefix: /bar/`. diff --git a/content/en/docs/pre-release/topics/running/running.md b/content/en/docs/pre-release/topics/running/running.md deleted file mode 100644 index 40767c02..00000000 --- a/content/en/docs/pre-release/topics/running/running.md +++ /dev/null @@ -1,381 +0,0 @@ -# Running and deployment - -This section is intended for operators running $productName$, and covers various aspects of deploying and configuring the $productName$ in production. - -## $productName$ and Kubernetes - -$productName$ relies on Kubernetes for reliability, availability, and scalability. This means that features such as Kubernetes readiness and liveness probes, rolling updates, and the Horizontal Pod Autoscaling should be utilized to manage $productName$. - -## Default configuration - -The default configuration of $productName$ includes default [resource limits](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-requests-and-limits-of-pod-and-container), as well as [readiness and liveness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/). These values should be adjusted for your specific environment. - -## Accessing the Admin Endpoint - -$productName$ exposes access to Envoy's admin endpoint which can be used to set runtime flags, dump the envoy config, and much more. - -1. Port-forward to a $productName$ pod: `kubectl port-forward -n ambassador 8001:8001` - -2. In a web browser, visit `http://127.0.0.1:8001/` - -### Apply Runtime Flags - -1. Visit `http://127.0.0.1:8001/runtime` to view all the active runtime flags for the pod. By default there should not be any. Note that this configuration is specific -to the pod you are port-forwarding. If you have multiple pods then you will need to access them separately. - -2. Make requests to `http://127.0.0.1:19000/runtime_modify` to set runtime flags. - ex: `http://127.0.0.1:19000/runtime_modify?envoy.restart_features.send_goaway_for_premature_rst_streams=true` - -Runtime Flags: - -- `http.max_requests_per_io_cycle`: Sets the limit on the number of HTTP requests processed -from a single connection in a single I/O cycle. Requests over this limit are processed in subsequent I/O cycles. This -mitigates CPU starvation by connections that simultaneously send high number of requests by allowing requests from other -connections to make progress. This runtime value can be set to 1 in the presence of abusive HTTP/2 or HTTP/3 connections. -By default this limit is disabled. - -- `overload.premature_reset_min_stream_lifetime_seconds`: determines the interval where received stream - reset is considered premature (with 1 second default). - -- `overload.premature_reset_total_stream_count`: Determines the number of requests received from a connection before the check for premature - resets is applied. The connection is disconnected if more than 50% of resets are premature. The default value is 500 and is enaled by default. - -- `envoy.restart_features.send_goaway_for_premature_rst_streams`: Defaults to true and enables checking connections for premature resets. - -### Dump the Envoy Config - -1. Visit `http://127.0.0.1:8001/config_dump` - - - If you are in Firefox or a similar browser, click on the `Raw Data` button at the top - -2. Right click the page and save the contents as something like `config_dump.json` so you can explore it using an editor of your choice. - -3. There are plenty of other functions in Envoy's Admin interface you can take advantage of while the port-forward is active -if you are comfortable exploring and debugging Envoy Proxy. Visit `http://127.0.0.1:19000/` in a web browser to check out some of the other functions. - -## Running as non-root - -Starting with $productName$ 0.35, we support running $productName$ as non-root. This is the recommended configuration, and will be the default configuration in future releases. We recommend you configure $productName$ to run as non-root as follows: - -* Have Kubernetes run $productName$ as non-root. This may happen by default (e.g., OpenShift) or you can set a `securityContext` in your Deployment as shown below in this abbreviated example: - -```yaml ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: ambassador -spec: - replicas: 1 - selector: - matchLabels: - service: ambassador - template: - metadata: - labels: - service: ambassador - spec: - containers: - image: docker.io/datawire/aes:$version$ - name: ambassador - restartPolicy: Always - securityContext: - runAsUser: 8888 - serviceAccountName: ambassador -``` - -* Set the `service_port` element in the `ambassador Module` to 8080 (cleartext) or 8443 (TLS). This is the port that $productName$ will use to listen to incoming traffic. Note that any port number above 1024 will work; $productName$ will use 8080/8443 as its defaults in the future. - -* Make sure that incoming traffic to $productName$ is configured to route to the `service_port`. If you're using the default $productName$ configuration, this means configuring the `targetPort` to point to the `service_port` above. - -* If you are using `redirect_cleartext_from`, change the value of this field to point to your cleartext port (e.g., 8080) and set `service_port` to be your TLS port (e.g., 8443). - -## Changing the configuration directory - -While running, $productName$ needs to use a directory within its container for generated configuration data. Normally this is `/ambassador`, but in some situations - especially if running as non-root - it may be necessary to change to a different directory. To do so, set the environment variable `AMBASSADOR_CONFIG_BASE_DIR` to the full pathname of the directory to use, as shown below in this abbreviated example: - -```yaml -env: -- name: AMBASSADOR_CONFIG_BASE_DIR - value: /tmp/ambassador-config -``` - -With `AMBASSADOR_CONFIG_BASE_DIR` set as above, $productName$ will create and use the directory `/tmp/ambassador-config` for its generated data. (Note that, while the directory will be created if it does not exist, attempts to turn an existing file into a directory will fail.) - -## Running as DaemonSet - -$productName$ can be deployed as a DaemonSet to have one pod per node in a Kubernetes cluster. This setup is especially helpful when you have a Kubernetes cluster running on a private cloud. - -* In an ideal example scenario, you are running containers on Kubernetes alongside with your non-containerized applications running exposed via VIP using BIG-IP or similar products. In such cases, east-west traffic is routed based on iRules to certain a set of application pools consisting of application or web servers. In this setup, alongside traditional application servers, two or more $productName$ pods can also be part of the application pools. In case of failure there is at least one $productName$ pod available to BIG-IP that can take care of routing traffic to the Kubernetes cluster. - -* In manifest files `kind: Deployment` needs to be updated to `kind: DaemonSet` and `replicas` should be removed in `spec` section. - -## Namespaces - -$productName$ supports multiple namespaces within Kubernetes. To make this work correctly, you need to set the `AMBASSADOR_NAMESPACE` environment variable in $productName$'s container. By far the easiest way to do this is using Kubernetes' downward API (this is included in the YAML files from `getambassador.io`): - -```yaml -env: -- name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace -``` - -Given that `AMBASSADOR_NAMESPACE` is set, $productName$ [`Mappings`](../../using/mappings) can operate within the same namespace, or across namespaces. **Note well** that `Mappings` will have to explicitly include the namespace with the service to cross namespaces; see the [`Mapping`](../../using/mappings) documentation for more information. - -If you want $productName$ to only work within a single namespace, set `AMBASSADOR_SINGLE_NAMESPACE` as an environment variable. - -```yaml -env: -- name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace -- name: AMBASSADOR_SINGLE_NAMESPACE - value: "true" -``` - -With $productName$, if you set `AMBASSADOR_NAMESPACE` or `AMBASSADOR_SINGLE_NAMESPACE`, set it in the deployment container. - -If you want to set a certificate for your `TLScontext` from another namespace, you can use the following: - -```yaml -env: -- name: AMBASSADOR_SINGLE_NAMESPACE - value: "YES" -- name: AMBASSADOR_CERTS_SINGLE_NAMESPACE - value: "YES" -- name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: - apiVersion: v1 - fieldPath: metadata.namespace -``` - -## `AMBASSADOR_ID` - -$productName$ supports running multiple $productNamePlural$ in the same cluster, without restricting a given $productName$ to a single namespace. This is done with the `AMBASSADOR_ID` setting. In the `ambassador Module`, set the `ambassador_id`, e.g., - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - ambassador_id: [ "ambassador-1" ] - config: - ... -``` - -Then, assign each $productName$ pod a unique `AMBASSADOR_ID` with the environment variable as part of your deployment: - -```yaml -env: -- name: AMBASSADOR_ID - value: ambassador-1 -``` - -With $productName$, if you set `AMBASSADOR_ID`, you will need to set it in the deployment container. - -$productName$ will then only use YAML objects that include an appropriate `ambassador_id` attribute. For example, if $productName$ is given the ID `ambassador-1` as above, only the first two YAML objects below will be used: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-used -spec: - ambassador_id: [ "ambassador-1" ] - prefix: /demo1/ - service: demo1 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-used-2 -spec: - ambassador_id: [ "ambassador-1", "ambassador-2" ] - prefix: /demo2/ - service: demo2 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-skipped -spec: - prefix: /demo3/ - service: demo3 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-skipped-2 -spec: - ambassador_id: [ "ambassador-2" ] - prefix: /demo4/ - service: demo4 -``` - -`ambassador_id` is always a list, and may (as shown in `mapping-used-2` above) include multiple IDs to allow a given object in the configuration for multiple $productName$ instances. In this case, `mapping-used-2` will be included in the configuration for `ambassador-1` and also for `ambassador-2`. - -**Note well that _any_ $productName$ configuration resource can have an `ambassador_id` included** so, for example, it is _fully supported_ to use `ambassador_id` to qualify the `ambassador Module`, `TLSContext`, and `AuthService` objects. You will need to set `ambassador_id` in all resources you want to use for $productName$. - -If no `AMBASSADOR_ID` is assigned to an $productName$, it will use the ID `default`. If no `ambassador_id` is present in a YAML object, it will also use the ID `default`. - -## `AMBASSADOR_ENVOY_BASE_ID` - -$productName$ supports running side-by-side with other envoy-based projects in a single pod. An example of this is running with an `istio` sidecar. This is done with the `AMBASSADOR_ENVOY_BASE_ID` environment variable as part of your deployment: - -```yaml -env: -- name: AMBASSADOR_ENVOY_BASE_ID - value: 1 -``` - -If no `AMBASSADOR_ENVOY_BASE_ID` is provided then it will use the ID `0`. For more information on the Envoy base-id option please see the [Envoy command line documentation](https://www.envoyproxy.io/docs/envoy/latest/operations/cli.html?highlight=base%20id#cmdoption-base-id). - -## `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. - -## `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. - -## `AMBASSADOR_LEGACY_MODE` - -Setting `AMBASSADOR_LEGACY_MODE` to `true` will result in $productName$ disabling certain features -and reverting to older codepaths which may be better preserve certain older behaviors. Legacy mode -currently has the following effects: - -- $productName$ will switch back to the $productName$ 1.6 input-resource validator (which can significantly -increase configuration latency for $productName$ installations with many resources). -- $productName$ will use the shell boot sequence that was the default up through 1.9.1, rather than the Golang boot sequence that became the default in 1.10.0. -- `AMBASSADOR_FAST_RECONFIGURE` (see below) is not supported in legacy mode. - -## `AMBASSADOR_FAST_RECONFIGURE` - -Setting `AMBASSADOR_FAST_RECONFIGURE` to "true" enables incremental reconfiguration. When enabled, $productName$ will track deltas from one configuration to the next and recalculate only what is necessary to follow the change. When disabled (the default), $productName$ will recompute the entire configuration at every change. - -**`AMBASSADOR_FAST_RECONFIGURE` is not supported when `AMBASSADOR_LEGACY_MODE` is active.** - -## Configuration from the filesystem - -If desired, $productName$ can be configured from YAML files in the directory `$AMBASSADOR_CONFIG_BASE_DIR/ambassador-config` (by default, `/ambassador/ambassador-config`, which is empty in the images built by Datawire). You could volume mount an external configuration directory here, for example, or use a custom Dockerfile to build configuration directly into a Docker image. - -Note well that while $productName$ will read its initial configuration from this directory, configuration loaded from Kubernetes annotations will _replace_ this initial configuration. If this is not what you want, you will need to set the environment variable `AMBASSADOR_NO_KUBEWATCH` so that $productName$ will not try to update its configuration from Kubernetes resources. - -Also note that the YAML files in the configuration directory must contain the $productName$ resources, not Kubernetes resources with annotations. - -## Log levels and debugging - -The $OSSproductName$ and $AESproductName$ support more verbose debugging levels. If using $OSSproductName$, the [diagnostics](../diagnostics) service has a button to enable debug logging. Be aware that if you're running $productName$ on multiple pods, the debug log levels are not enabled for all pods -- they are configured on a per-pod basis. - -If using $AESproductName$, you can 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 format - -By default, $productName$ writes its own logs in a plain text format. To produce logs as JSON instead, set the `AMBASSADOR_JSON_LOGGING` environment variable: - -```yaml -env: -- name: AMBASSADOR_JSON_LOGGING - value: "true" -``` - -## Port assignments - -$productName$ uses some TCP ports in the range 8000-8499 internally, as well as port 8877. Third-party software integrating with $productName$ should not use ports in this range on the $productName$ pod. - -## $productName$ update checks (Scout) - -$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 $productName$ will run regardless of the status of Scout (i.e., our uptime has zero impact on your uptime.) - -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. - -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. - -Unless disabled, $productName$ will also report the following anonymized information back to Datawire: - -| Attribute | Type | Description | -| :------------------------ | :---- | :------------------------ | -| `cluster_count` | int | total count of clusters in use | -| `cluster_grpc_count` | int | count of clusters using GRPC upstream | -| `cluster_http_count` | int | count of clusters using HTTP or HTTPS upstream | -| `cluster_routing_envoy_rh_count` | int | count of clusters routing using Envoy `ring_hash` | -| `cluster_routing_envoy_maglev_count` | int | count of clusters routing using Envoy `maglev` | -| `cluster_routing_envoy_lr_count` | int | count of clusters routing using Envoy `least_request` | -| `cluster_routing_envoy_rr_count` | int | count of clusters routing using Envoy `round_robin` | -| `cluster_routing_kube_count` | int | count of clusters routing using Kubernetes | -| `cluster_tls_count` | int | count of clusters originating TLS | -| `custom_ambassador_id` | bool | has the `ambassador_id` been changed from 'default'? | -| `custom_listener_port` | bool | has the listener port been changed from 80/443? | -| `diagnostics` | bool | is the diagnostics service enabled? | -| `endpoint_grpc_count` | int | count of endpoints to which $productName$ will originate GRPC | -| `endpoint_http_count` | int | count of endpoints to which $productName$ will originate HTTP or HTTPS | -| `endpoint_routing` | bool | is endpoint routing enabled? | -| `endpoint_routing_envoy_rh_count` | int | count of endpoints being routed using Envoy `ring_hash` | -| `endpoint_routing_envoy_maglev_count` | int | count of endpoints being routed using Envoy `maglev` | -| `endpoint_routing_envoy_lr_count` | int | count of endpoints being routed using Envoy `least_request` | -| `endpoint_routing_envoy_rr_count` | int | count of endpoints being routed using Envoy `round_robin` | -| `endpoint_routing_kube_count` | int | count of endpoints being routed using Kubernetes | -| `endpoint_tls_count` | int | count of endpoints to which $productName$ will originate TLS | -| `extauth` | bool | is extauth enabled? | -| `extauth_allow_body` | bool | will $productName$ send the body to extauth? | -| `extauth_host_count` | int | count of extauth hosts in use | -| `extauth_proto` | str | extauth protocol in use ('http', 'grpc', or `null` if not active) | -| `group_canary_count` | int | count of Mapping groups that include more than one Mapping | -| `group_count` | int | total count of Mapping groups in use (length of the route table) | -| `group_header_match_count` | int | count of groups using header matching (including `host` and `method`) | -| `group_host_redirect_count` | int | count of groups using host_redirect | -| `group_host_rewrite_count` | int | count of groups using host_rewrite | -| `group_http_count` | int | count of HTTP Mapping groups | -| `group_precedence_count` | int | count of groups that explicitly set the precedence of the group | -| `group_regex_header_count` | int | count of groups using regex header matching | -| `group_regex_prefix_count` | int | count of groups using regex prefix matching | -| `group_resolver_consul` | int | count of groups using the Consul resolver | -| `group_resolver_kube_endpoint` | int | count of groups using the Kubernetes endpoint resolver | -| `group_resolver_kube_service` | int | count of groups using the Kubernetes service resolver | -| `group_shadow_count` | int | count of groups using shadows | -| `group_shadow_weighted_count` | int | count of groups using shadows but not shadowing all traffic | -| `group_tcp_count` | int | count of TCP Mapping groups | -| `host_count` | int | count of Host resources in use | -| `k8s_ingress_class_count` | int | count of IngressClass resources in use | -| `k8s_ingress_count` | int | count of Ingress resources in use | -| `listener_count` | int | count of active listeners (1 unless `redirect_cleartext_from` or TCP Mappings are in use) | -| `liveness_probe` | bool | are liveness probes enabled? | -| `managed_by` | string | tool that manages the $productName$ deployment, if any (e.g. helm, edgectl, etc.) | -| `mapping_count` | int | count of Mapping resources in use | -| `ratelimit` | bool | is rate limiting in use? | -| `ratelimit_custom_domain` | bool | has the rate limiting domain been changed from 'ambassador'? | -| `ratelimit_data_plane_proto` | bool | is rate limiting using the data plane proto? | -| `readiness_probe` | bool | are readiness probes enabled? | -| `request_4xx_count` | int | lower bound for how many requests have gotten a 4xx response | -| `request_5xx_count` | int | lower bound for how many requests have gotten a 5xx response | -| `request_bad_count` | int | lower bound for how many requests have failed (either 4xx or 5xx) | -| `request_elapsed` | float | seconds over which the request_ counts are valid | -| `request_hr_elapsed` | string | human-readable version of `request_elapsed` (e.g. "3 hours 35 minutes 20 seconds" | -| `request_ok_count` | int | lower bound for how many requests have succeeded (not a 4xx or 5xx) | -| `request_total_count` | int | lower bound for how many requests were handled in total | -| `statsd` | bool | is StatsD enabled? | -| `server_name` | bool | is the `server_name` response header overridden? | -| `service_resource_total` | int | total count of service resources loaded from all discovery sources | -| `tls_origination_count` | int | count of TLS origination contexts | -| `tls_termination_count` | int | count of TLS termination contexts | -| `tls_using_contexts` | bool | are new TLSContext resources in use? ? | -| `tls_using_module` | bool |is the old TLS module in use | -| `tracing` | bool | is tracing in use? | -| `tracing_driver` | str | tracing driver in use ('zipkin', 'lightstep', 'datadog', or `null` if not active) | -| `use_proxy_proto` | bool | is the `PROXY` protocol in use? | -| `use_remote_address` | bool | is $productName$ honoring remote addresses? | -| `x_forwarded_proto_redirect` | bool | is $productName$ redirecting based on `X-Forwarded-Proto`? | -| `xff_num_trusted_hops` | int | what is the count of trusted hops for `X-Forwarded-For`? | - -The `request_*` counts are always incremental: they contain only information about the last `request_elapsed` seconds. Additionally, they only provide a lower bound -- notably, if an $productName$ pod crashes or exits, no effort is made to ship out a final update, so it's very easy for counts to never be reported. - -To completely disable feature reporting, set the environment variable `AMBASSADOR_DISABLE_FEATURES` to any non-empty value. diff --git a/content/en/docs/pre-release/topics/running/scaling.md b/content/en/docs/pre-release/topics/running/scaling.md deleted file mode 100644 index 22fa743e..00000000 --- a/content/en/docs/pre-release/topics/running/scaling.md +++ /dev/null @@ -1,194 +0,0 @@ -# Performance and scaling $productName$ - -Scaling any cloud native application is inherently domain specific, however the content here -reflects common issues, tips, and tricks that come up frequently. - -## Performance dimensions - -The performance of $productName$'s control plane can be characterized along a number of -different dimensions: - - - The number of `TLSContext` resources. - - The number of `Host` resources. - - The number of `Mapping` resources per `Host` resource. - - The number of `Mapping` resources that will span all `Host` resources (either because they're using `host_regex`, or because they're using `hostname: "*"`). - -If your application involves a larger than average number of any of the above resources, you may -find yourself in need of some of the content in this section. - -## Mysterious pod restarts (aka pushing the edge of the envelope) - -Whether your application is growing organically or whether you are deliberately scale testing, it's -helpful to recognize how $productName$ behaves as it reaches the edge of its performance -envelope along any of these dimensions. - -As $productName$ approaches the edge of its performance envelope, it will often manifest as -mysterious pod restarts triggered by Kubernetes. This does not always mean there is a problem, it -could just mean you need to tune some of the resource limits set in your deployment. When it comes -to scaling, Kubernetes will generally kill an $productName$ pod for one of two reasons: exceeding -memory limits or failed liveness/readiness probes. See the [Memory Limits](#memory-limits), -[Liveness Probes](#liveness-probes), and [Readiness Probes](#readiness-probes) -sections for more on how to cope with these situations. - -## Memory limits - -$productName$ can grow in memory usage and be killed by Kubernetes if it exceeds the limits -defined in its pod spec. When this happens it is confusing and difficult to catch because the only -indication that this has occurred is the pod transitioning momentarily into the `OOMKilled` -state. The only way to actually observe this is if you are lucky enough to be running the following -command (or have similar monitoring configured) when $productName$ gets `OOMKilled`: - -``` - kubectl get pods -n ambassador -w -``` - -In order to take the luck out of the equation, $productName$ will periodically log its -memory usage so you can see in the logs if memory limits might be a problem and require adjustment: - -``` -2020/11/26 22:35:20 Memory Usage 0.56Gi (28%) - PID 1, 0.22Gi: busyambassador entrypoint - PID 14, 0.04Gi: /usr/bin/python /usr/bin/diagd /ambassador/snapshots /ambassador/bootstrap-ads.json /ambassador/envoy/envoy.json --notices /ambassador/notices.json --port 8004 --kick kill -HUP 1 - PID 16, 0.12Gi: /ambassador/sidecars/amb-sidecar - PID 37, 0.07Gi: /usr/bin/python /usr/bin/diagd /ambassador/snapshots /ambassador/bootstrap-ads.json /ambassador/envoy/envoy.json --notices /ambassador/notices.json --port 8004 --kick kill -HUP 1 - PID 48, 0.08Gi: envoy -c /ambassador/bootstrap-ads.json --base-id 0 --drain-time-s 600 -l error -``` - -In general you should try to keep $productName$'s memory usage below 50% of the pod's limit. This may -seem like a generous safety margin, but when reconfiguration occurs, $productName$ requires additional -memory to avoid disrupting active connections. At each reconfiguration, $productName$ keeps around the -old version for the duration of the configured drain time. See -[AMBASSADOR_DRAIN_TIME](#ambassador_drain_time) for more details on how to tune this -behavior. - -$productName$'s exact memory usage depends on (among other things) how many `Host` and -`Mapping` resources are defined in your cluster. If this number has grown over time, you may need to -increase the memory limit defined in your deployment. - -## Liveness probes - -$productName$ defines the `/ambassador/v0/check_alive` endpoint on port `8877` for use with Kubernetes -liveness probes. See the Kubernetes documentation for more details on [HTTP liveness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-a-liveness-http-request). - -Kubernetes will restart the $productName$ pod if it fails to get a 200 result from the endpoint. If -this happens it won't necessarily show up in an easily recognizable way in the pod logs. You can -look for Kubernetes events to see if this is happening. Use `kubectl describe pod -n ambassador` or -`kubectl get events -n ambassador` or equivalent. - -The purpose of liveness probes is to rescue an $productName$ instance that is wedged, however if -liveness probes are too sensitive they can take out $productName$ instances that are functioning -normally. This is more prone to happen as the number of $productName$ inputs increase. The -`timeoutSeconds` and `failureThreshold` fields of the $productName$ deployment's liveness Probe -determines how tolerant Kubernetes is with its probes. If you observe pod restarts along with -`Unhealthy` events, try tuning these fields upwards from their default values. See the Kubernetes documentation for more details on [tuning probes](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#probe-v1-core). - -Note that whatever changes you make to $productName$'s liveness probes should most likely be made to -its readiness probes also. - -## Readiness probes - -$productName$ defines the `/ambassador/v0/check_ready` endpoint on port `8877` for use with Kubernetes -readiness probes. See the Kubernetes documentation for more details on [readiness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-readiness-probes). - -Kubernetes uses readiness checks to prevent traffic from going to pods that are not ready to handle -requests. The only time $productName$ cannot usefully handle requests is during initial startup when it -has not yet loaded all the routing information from Kubernetes and/or consul. During this bootstrap -period there is no guarantee $productName$ would know where to send a given request. The `check_ready` -endpoint will only return 200 when all routing information has been loaded. After the initial -bootstrap period it behaves identically to the `check_alive` endpoint. - -Generally $productName$'s readiness probes should be configured with the same settings as its liveness -probes. - -## `AMBASSADOR_FAST_RECONFIGURE` and `AMBASSADOR_LEGACY_MODE` flags - -`AMBASSADOR_FAST_RECONFIGURE` is a feature flag that enables a higher performance implementation of -the code $productName$ uses to validate and generate envoy configuration. It will eventually be enabled -by default, but if you are experiencing performance problems you should try setting -`AMBASSADOR_FAST_RECONFIGURE` to `true` to see if this helps. - -`AMBASSADOR_LEGACY_MODE` is **not** recommended when performance is critical. - -## `AMBASSADOR_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. - -## Unconstrained Mappings with many hosts - -When working with a large number of `Host` resources, it's important to understand the impact of -unconstrained `Mapping`s. An unconstrained `Mapping` is one that is not restricted to a specific -`Host`. Such a `Mapping` will create a route for all of your `Host`s. If this is what you want then -it is the appropriate thing to do, however if you do not intend to do this, then you can end up with -many more routes than you had intended and this can adversely impact performance. - -## Inspecting $productName$ performance - -$productName$ internally tracks a number of key performance indicators. You can inspect these via the -debug endpoint at `localhost:8877/debug`. Note that the `AMBASSADOR_FAST_RECONFIGURE` flag needs to -be set to `"true"` for this endpoint to be present: - -``` -$ kubectl exec -n ambassador -it ${POD} curl localhost:8877/debug -{ - "timers": { - # These two timers track how long it takes to respond to liveness and readiness probes. - "check_alive": "7, 45.411495ms/61.85999ms/81.358927ms", - "check_ready": "7, 49.951304ms/61.976205ms/86.279038ms", - - # These two timers track how long we spend updating our in-memory snapshot when our Kubernetes - # watches tell us something has changed. - "consulUpdate": "0, 0s/0s/0s", - "katesUpdate": "3382, 28.662µs/102.784µs/95.220222ms", - - # These timers tell us how long we spend notifying the sidecars if changed input. This - # includes how long the sidecars take to process that input. - "notifyWebhook:diagd": "2, 1.206967947s/1.3298432s/1.452718454s", - "notifyWebhooks": "2, 1.207007216s/1.329901037s/1.452794859s", - - # This timer tells us how long we spend parsing annotations. - "parseAnnotations": "2, 21.944µs/22.541µs/23.138µs", - - # This timer tells us how long we spend reconciling changes to consul inputs. - "reconcileConsul": "2, 50.104µs/55.499µs/60.894µs", - - # This timer tells us how long we spend reconciling secrets related changes to $productName$ - # inputs. - "reconcileSecrets": "2, 18.704µs/20.786µs/22.868µs" - }, - "values": { - "envoyReconfigs": { - "times": [ - "2020-11-06T13:13:24.218707995-05:00", - "2020-11-06T13:13:27.185754494-05:00", - "2020-11-06T13:13:28.612279777-05:00" - ], - "staleCount": 2, - "staleMax": 0, - "synced": true - }, - "memory": "39.73Gi of Unlimited (0%)" - } -} -``` - -## Running profiles - -$productName$ exposes endpoints at `localhost:8877/debug/pprof` to run Golang profiles to aid in live debugging. The endpoints are equivalent to those found in the [http/pprof](https://pkg.go.dev/net/http/pprof) package. `/debug/pprof/` returns an HTML page listing the available profiles. - -The following are the different types of profiles you can run: - -| Profile | Function | -| :------- | :-------- | -| /debug/pprof/allocs | Returns a sampling of all past memory allocations. | -| /debug/pprof/block | Returns stack traces of goroutines that led to blocking on sychronization primitives. | -| /debug/pprof/cmdline | Returns the command line that was invoked by the current program. | -| /debug/pprof/goroutine | Returns stack traces of all current goroutines. | -| /debug/pprof/heap | Returns a sampling of memory allocations of live objects. | -| /debug/pprof/mutex | Returns stack traces of goroutines holding contended mutexes. | -| /debug/pprof/profile | Returns pprof-formatted cpu profile. You can specify the duration using the seconds `GET` parameter. The default duration is 30 seconds. | -| /debug/pprof/symbol | Returns the program counters listed in the request. | -| /debug/pprof/threadcreate | Returns stack traces that led to creation of new OS threads. | -| /debug/pprof/trace | Returns the execution trace in binary form. You can specify the duration using the seconds `GET` parameter. The default duration is 1 second. | diff --git a/content/en/docs/pre-release/topics/running/services/auth-service.md b/content/en/docs/pre-release/topics/running/services/auth-service.md deleted file mode 100644 index adfb77e4..00000000 --- a/content/en/docs/pre-release/topics/running/services/auth-service.md +++ /dev/null @@ -1,150 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Authentication service - -$productName$ provides a highly flexible mechanism for authentication, -via the `AuthService` resource. An `AuthService` configures -$productName$ to use an external service to check authentication and -authorization for incoming requests. Each incoming request is -authenticated before routing to its destination. - -All requests are validated by the `AuthService` (unless the `Mapping` -applied to the request sets `bypass_auth`). It is not possible to -combine multiple `AuthServices`. While it is possible to create -multiple `AuthService` resources, $productName$ load-balances between -them in a round-robin fashion. This is useful for canarying an -`AuthService` change, but is not useful for deploying multiple -distinct `AuthServices`. In order to combine multiple external -services (either having multiple services apply to the same request, -or selecting between different services for the different requests), -instead of using an `AuthService`, use an [$AESproductName$ `External` -`Filter`](/docs/edge-stack/latest/topics/using/filters/). - - - -Because of the limitations described above, **$AESproductName$ does -not support `AuthService` resources, and you should instead use an -[`External` -`Filter`](/docs/edge-stack/latest/topics/using/filters/external),** -which is mostly a drop-in replacement for an `AuthService`. The -`External` `Filter` relies on the $AESproductName$ `AuthService`. -Make sure the $AESproductName$ `AuthService` is deployed before -configuring `External` `Filters`. - - - -The currently supported version of the `AuthService` resource is -`getambassador.io/v3alpha1`. Earlier versions are deprecated. - -## Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: AuthService -metadata: - name: authentication -spec: - ambassador_id: [ "ambassador-1" ] - auth_service: "example-auth.authentication:3000" - tls: true - proto: http - timeout_ms: 5000 - include_body: - max_bytes: 4096 - allow_partial: true - status_on_error: - code: 403 - failure_mode_allow: false - - # proto: grpc only, default is v2. If upgrading from 2.x then you must set this to v3. - protocol_version: v3 - - # proto: http only - path_prefix: "/path" - allowed_request_headers: - - "x-example-header" - allowed_authorization_headers: - - "x-qotm-session" - add_auth_headers: - x-added-auth: auth-added - add_linkerd_headers: false -``` - -## Fields - -`auth_service` is the only required field, all others are optional. - -| Attribute | Default value | Description | -| ---------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `ambassador_id` | `[ "default" ]` | Which [Ambassador ID](../../running/#ambassador_id) the `AuthService` should apply to. | -| `auth_service` | (none; a value is required) | Identifies the external auth service to talk to. The format of this field is `scheme://host:port` where `scheme://` and `:port` are optional. The scheme-part, if present, must be either `http://` or `https://`; if the scheme-part is not present, it behaves as if `http://` is given. The scheme-part controls whether TLS or plaintext is used and influences the default value of the port-part. The host-part must be the [namespace-qualified DNS name](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#namespaces-of-services) of the service you want to use for authentication. | -| `tls` | `""` | This field is populated with the name of the defined TLSContext, which determines the TLS certificate presented to external auth services. | -| `proto` | `http` | Specifies which variant of the [`ext_authz` protocol](../ext-authz/) to use when communicating with the external auth service. Valid options are `http` or `grpc`. | -| `timeout_ms` | `5000` | The total maximum duration in milliseconds for the request to the external auth service, before triggering `status_on_error` or `failure_mode_allow`. | -| `include_body` | `null` | Controls how much to buffer the request body to pass to the external auth service, for use cases such as computing an HMAC or request signature. If `include_body` is `null` or unset, then the request body is not buffered at all, and an empty body is passed to the external auth service. If `include_body` is not `null`, the `max_bytes` and `allow_partial` subfields are required. | -| `include_body.max_bytes` | (none; a value is required if `include_body` is not `null`) | Controls the amount of body data that is passed to the external auth service. | -| `include_body.allow_partial` | (none; a value is required if `include_body` is not `null`) | Controls what happens to requests with bodies larger than `max_bytes`. If `allow_partial` is `true`, the first `max_bytes` of the body are sent to the external auth service. If `false`, the message is rejected with HTTP 413 ("Payload Too Large"). | -| `status_on_error.code` | `403` | Controls the status code returned when unable to communicate with external auth service. This is ignored if `failure_mode_allow: true`. | -| `failure_mode_allow` | `false` | Controls whether to allow or reject requests when there is an error communicating with the external auth service; a value of `true` allows the request through to the upstream backend service, a value of `false` returns a `status_on_error.code` response to the client. | -| `stats_name` | the `auth_service` value with non-alphanumeric characters replaced with underscores | See [Overriding Statistics Names](../../statistics/#overriding-statistics-names). | -| `circuit_breakers` | the value set in the [`ambassador` `Module`](../../../using/defaults) | See [Circuit Breakers](../../../using/circuit-breakers/). | - -The following field is only used if `proto` is set to `grpc`. It is -ignored if `proto` is `http`. - -| Attribute | Default value | Description | -| ------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `protocol_version` | `v3` | Allowed values are `v3` and `v2`(defualt). `protocol_version` was used in previous versions of $productName$ to control the protocol used by the gRPC service. $productName$ 3.x is running an updated version of Envoy that has dropped support for the `v2` protocol, so starting in 3.x, if `protocol_version` is not specified, 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. | - -The following fields are only used if `proto` is set to `http`. They -are ignored if `proto` is `grpc`. - -| Attribute | Default value | Description | -| ------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `path_prefix` | `""` | Prepends a string to the request path of the request when sending it to the external auth service. By default this is empty, and nothing is prepended. For example, if the client makes a request to `/foo`, and `path_prefix: /bar`, then the path in the request made to the external auth service will be `/foo/bar`. | -| `allowed_request_headers` | `[]` | Lists the headers (case-insensitive) that are copied from the incoming request to the request made to the external auth service. In addition to the headers listed in this field, the following headers are always included: `Authorization`, `Cookie`, `From`, `Proxy-Authorization`, `User-Agent`, `X-Forwarded-For`, `X-Forwarded-Host`, and `X-Forwarded-Proto`. | -| `allowed_authorization_headers` | `[]` | Lists the headers (case-insensitive) that are copied from the response from the external auth service to the request sent to the upstream backend service (if the external auth service indicates that the request to the upstream backend service should be allowed). In addition to the headers listed in this field, the following headers are always included: `Authorization`, `Location`, `Proxy-Authenticate`, `Set-cookie`, `WWW-Authenticate` | -| `add_auth_headers` | `{}` | A dictionary of `header: value` pairs that are added to the request made to the external auth service. | -| `add_linkerd_headers` | Defaults to the value set in the [`ambassador` `Module`](../../ambassador) | When true, in the request to the external auth service, adds an `l5d-dst-override` HTTP header that is set to the hostname and port number of the external auth service. | - -## Canarying multiple `AuthServices` - -You may create multiple `AuthService` manifests to round-robin -authentication requests among multiple services. **All services must -use the same `path_prefix` and header definitions.** If you try to -have different values, you'll see an error in the [diagnostics -service](../../ambassador/#diagnostics), telling you which value is -being used. - -## Configuring public `Mappings` - -An `AuthService` can be disabled for a `Mapping` by setting -`bypass_auth` to `true`. This will tell $productName$ to allow all -requests for that `Mapping` through without interacting with the -external auth service. - - - -## Transport Protocol Migration - - -> **Note:** The following information is only applicable to `AuthServices` using `proto: grpc` -As of $productName$ version 2.3, the `v2` transport protocol is deprecated and any AuthServices making use -of it should migrate to `v3` before support for `v2` is removed in a future release. - -The following imports simply need to be updated to migrate an AuthService - -`v2` Imports: -``` - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" -``` - -`v3` Imports: -``` - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" -``` diff --git a/content/en/docs/pre-release/topics/running/services/ext-authz.md b/content/en/docs/pre-release/topics/running/services/ext-authz.md deleted file mode 100644 index d850ba4b..00000000 --- a/content/en/docs/pre-release/topics/running/services/ext-authz.md +++ /dev/null @@ -1,83 +0,0 @@ -# ExtAuth protocol - -By design, the ExtAuth protocol used by [the AuthService](../auth-service) and by [External Filters](/docs/edge-stack/latest/topics/using/filters/external) is highly flexible. The authentication service is the first external service invoked on an incoming request (e.g., it runs before the rate limit filter). Because the logic of authentication is encapsulated in an external service, you can use this to support a wide variety of use cases. For example: - -* Supporting traditional SSO authentication protocols, e.g., OAuth, OpenID Connect, etc. -* Supporting HTTP basic authentication ([see a sample implementation](https://github.com/datawire/ambassador-auth-httpbasic)). -* Only authenticating requests that are under a rate limit and rejecting authentication requests above the rate limit. -* Authenticating specific services (URLs), and not others. - -For each request, the ExtAuth service may either: - 1. return a direct HTTP *response*, intended to be sent back to the requesting HTTP client (normally *denying* the request from being forwarded to the upstream backend service) or - 2. return a modification to make to the HTTP *request* before sending it to the upstream backend service (normally *allowing* the request to be forwarded to the upstream backend service with modifications). - -The ExtAuth service receives information about every request through $productName$ and must indicate whether the request is to be allowed or not. If not, the ExtAuth service provides the HTTP response which is to be handed back to the client. A potential control flow for Authentication is shown in the image below. - -Giving the ExtAuth service the ability to control the response allows many different types of auth mechanisms, for example: - -- The ExtAuth service can simply return an error page with an HTTP 401 response. -- The ExtAuth service can choose to include a `WWW-Authenticate` header in the 401 response, to ask the client to perform HTTP Basic Auth. -- The ExtAuth service can issue a 301 `Redirect` to divert the client into an OAuth or OIDC authentication sequence. The control flow of this is shown below. ![Authentication flow](../../../images/auth-flow.png) - -There are two variants of the ExtAuth: gRPC and plain HTTP. - -### The gRPC protocol - -When `proto: grpc` is set, the ExtAuth service must implement the `Authorization` gRPC interface, defined in [Envoy's `external_auth.proto`](https://github.com/emissary-ingress/emissary/blob/master/api/envoy/service/auth/v3/external_auth.proto). - -### The HTTP protocol - -External services for `proto: http` are often easier to implement, but have several limitations compared to `proto: grpc`. - - The list of headers that the ExtAuth service is interested in reading must be known ahead of time, in order to set `allow_request_headers`. Inspecting headers that are not known ahead of time requires instead using `proto: grpc`. - - The list of headers that the ExtAuth service would like to set or modify must be known ahead of time, in order to set `allow_authorization_headers`. Setting headers that are not known ahead of time requires instead using `proto: grpc`. - - When returning a direct HTTP response, the HTTP status code cannot be 200 or in the 5XX range. Intercepting with a 200 or 5XX response requires instead using `proto: grpc`. - -#### The request From $productName$ to the ExtAuth service - -For every incoming request, a similar request is made to the ExtAuth service that mimics the: - - HTTP request method - - HTTP request path, potentially modified by `path_prefix` - - HTTP request headers that are either named in `allowed_request_headers` or in the fixed list of headers that are always included - - first `include_body.max_bytes` of the HTTP request body. - -The `Content-Length` HTTP header is set to the number of bytes in the body of the request sent to the ExtAuth service (`0` if `include_body` is not set). - -**ALL** request methods will be proxied, which implies that the ExtAuth service must be able to handle any request that any client could make. - -Take this incoming request for example: - -``` -PUT /path/to/service HTTP/1.1 -Host: myservice.example.com:8080 -User-Agent: curl/7.54.0 -Accept: */* -Content-Type: application/json -Content-Length: 27 - -{ "greeting": "hello world!", "spiders": "OMG no" } -``` - -The request $productName$ will make of the auth service is: - -``` -PUT /path/to/service HTTP/1.1 -Host: extauth.example.com:8080 -User-Agent: curl/7.54.0 -Accept: */* -Content-Type: application/json -Content-Length: 0 -``` - -#### The response returned from the ExtAuth service to $productName$ - - - If the HTTP response returned from the ExtAuth service to $productName$ has an HTTP status code of 200, then the request is allowed through to the upstream backend service. **Only** 200 indicates this; other 2XX status codes will prevent the request from being allowed through. - - The 200 response should not contain anything in the body, but may contain arbitrary headers. Any header present in the ExtAuth service' response that is also either listed in the `allow_authorization_headers` attribute of the AuthService resource or in the fixed list of headers that are always included will be copied from the ExtAuth service's response into the request going to the upstream backend service. This allows the ExtAuth service to inject tokens or other information into the request, or to modify headers coming from the client. - - The big limitation here is that the list of headers to be set must be known ahead of time, in order to set `allow_request_headers`. Setting headers that are not known ahead of time requires instead using `proto: grpc`. - - - If $productName$ cannot reach the ExtAuth service at all, if the ExtAuth service does not return a valid HTTP response, or if the HTTP response has an HTTP status code in the 5XX range, then the communication with the ExtAuth service is considered to have failed, and the `status_on_error` or `failure_mode_allow` behavior is triggered. - - - Any HTTP status code other than 200 or 5XX from the ExtAuth service tells $productName$ to **not** allow the request to continue to the upstream backend service, but that the ExtAuth service is instead intercepting the request. The entire HTTP response from the ExtAuth service--including the status code, the headers, and the body--is handed back to the client verbatim. This gives the ExtAuth service **complete** control over the entire response presented to the client. - - The big limitation here is that you cannot directly return a 200 or 5XX response. Intercepting with a 200 of 5XX response requires instead using `proto: grpc`. diff --git a/content/en/docs/pre-release/topics/running/services/index.md b/content/en/docs/pre-release/topics/running/services/index.md deleted file mode 100644 index 1646aa5a..00000000 --- a/content/en/docs/pre-release/topics/running/services/index.md +++ /dev/null @@ -1,11 +0,0 @@ -# Available plugins - -You may need an API Gateway to enforce policies specific to your organization. $productName$ supports custom policies through external service plugins. The policy logic specific to your organization is implemented in the external service, and $productName$ is configured to send RPC requests to your service. - -Currently, $productName$ supports plugins for authentication, -access logging, rate limiting, and tracing. - -* [AuthService](auth-service) Plugin -* [LogService](log-service) Plugin -* [RateLimitService](rate-limit-service) Plugin -* [TracingService](tracing-service) Plugin diff --git a/content/en/docs/pre-release/topics/running/services/log-service.md b/content/en/docs/pre-release/topics/running/services/log-service.md deleted file mode 100644 index b3e90c7c..00000000 --- a/content/en/docs/pre-release/topics/running/services/log-service.md +++ /dev/null @@ -1,116 +0,0 @@ -# Log service - -By default, $productName$ puts the access logs on stdout; such -that the can be read using `kubectl logs`. The format of those logs, -and the local destination of them, can be configured using the -[`envoy_log_` settings in the `ambassador -Module`](../../ambassador). However, the -options there only allow for logging local to $productName$'s Pod. By -configuring a `LogService`, you can configure $productName$ to -report its access logs to a remote service, in addition to the usual -`ambassador Module` configured logging. - -The remote access log service (or ALS) must implement the -`AccessLogService` gRPC interface, defined in [Envoy's `als.proto`][als.proto]. - -[als.proto]: https://github.com/emissary-ingress/emissary/blob/master/api/envoy/service/accesslog/v3/als.proto - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: LogService -metadata: - name: example-log-service -spec: - # Common to all $productName$ resources - ambassador_id: []string # optional; default is ["default"] - - # LogService specific - service: "string" # required - driver: "enum-string:[tcp, http]" # required - driver_config: # required - additional_log_headers: # optional; default is [] (only for `driver: http`) - - header_name: string # required - during_request: boolean # optional; default is true - during_response: boolean # optional; default is true - during_trailer: boolean # optional; default is true - flush_interval_time: int-seconds # optional; default is 1 - flush_interval_byte_size: integer # optional; default is 16384 - grpc: boolean # optional; default is false - protocol_version: enum # optional; default is v2 -``` - - - `service` is where to route the access log gRPC requests to - - - `driver` identifies which type of accesses to log; HTTP requests (`"http"`) or - TLS connections (`"tcp"`). - - - `driver_config` stores the configuration that is specific to the `driver`: - - * `driver: tcp` has no additional configuration; the config must - be set as `driver_config: {}`. - - * `driver: http` - - - `additional_log_headers` identifies HTTP headers to include in - the access log, and when in the logged-request's lifecycle to - include them. - - - `flush_interval_time` is the maximum number of seconds to buffer - accesses for before sending them to the ALS. The logs will be - flushed to the ALS every time this duration is reached, or when the - buffered data reaches `flush_interval_byte_size`, whichever comes - first. See the [Envoy documentation on - `buffer_flush_interval`][buffer_flush_interval] for more - information. - - - `flush_interval_byte_size` is a soft size limit for the access log - buffer. The logs will be flushed to the ALS every time the - buffered data reaches this size, or whenever `flush_interval_time` - elapses, whichever comes first. See the [Envoy documentation on - `buffer_size_bytes`][buffer_size_bytes] for more information. - - - `grpc` must be `true`. - -[buffer_flush_interval]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/access_loggers/grpc/v3/als.proto.html#extensions-access-loggers-grpc-v3-commongrpcaccesslogconfig -[buffer_size_bytes]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/access_loggers/grpc/v3/als.proto.html#extensions-access-loggers-grpc-v3-commongrpcaccesslogconfig - - - `protocol_version` was used in previous versions of $productName$ to control the gRPC service name used to communicate with the `LogService`. $productName$ 3.x is running an updated version of Envoy that has dropped support for the `v2` protocol, so starting in 3.x, if `protocol_version` is not specified, 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. - -## Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: LogService -metadata: - name: als -spec: - service: "als.default:3000" - driver: http - driver_config: {} # NB: driver_config must be set, even if it's empty - grpc: true # NB: grpc must be true and it will use the V3 transport protocol -``` - -## Transport Protocol Migration - - -> **Note:** The following information is only applicable to `AuthServices` using `proto: grpc` -As of $productName$ version 2.3, the `v2` transport protocol is deprecated and any AuthServices making use -of it should migrate to `v3` before support for `v2` is removed in a future release. - -The following imports simply need to be updated to migrate an AuthService - -`v2` Imports: -``` - envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core" - envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2" - envoyType "github.com/datawire/ambassador/pkg/api/envoy/type" -``` - -`v3` Imports: -``` - envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3" - envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3" - envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3" -``` diff --git a/content/en/docs/pre-release/topics/running/services/rate-limit-service.md b/content/en/docs/pre-release/topics/running/services/rate-limit-service.md deleted file mode 100644 index 39c2b0ce..00000000 --- a/content/en/docs/pre-release/topics/running/services/rate-limit-service.md +++ /dev/null @@ -1,118 +0,0 @@ -# Rate limit service - -Rate limiting is a powerful technique to improve the [availability and -resilience of your -services](https://blog.getambassador.io/rate-limiting-a-useful-tool-with-distributed-systems-6be2b1a4f5f4). -In $productName$, each request can have one or more _labels_. These labels are -exposed to a third-party service via a gRPC API. The third-party service can -then rate limit requests based on the request labels. - -**Note that `RateLimitService` is only applicable to $OSSproductName$, -and not $AESproductName$, as $AESproductName$ includes a -built-in rate limit service.** - -## Request labels - -See [Attaching labels to -requests](../../../using/rate-limits#attaching-labels-to-requests) -for how to configure the labels that are attached to a request. - -## Domains - -In $productName$, each engineer (or team) can be assigned its own _domain_. A -domain is a separate namespace for labels. By creating individual domains, each -team can assign their own labels to a given request, and independently set the -rate limits based on their own labels. - -See [Attaching labels to -requests](../../../using/rate-limits/#attaching-labels-to-requests) -for how to labels under different domains. - -## External rate limit service - -In order for $productName$ to rate limit, you need to implement a -gRPC `RateLimitService`, as defined in [Envoy's `v3/rls.proto`] -interface. If you do not have the time or resources to implement your own rate -limit service, $AESproductName$ integrates a high-performance rate -limiting service. - -[envoy's `v3/rls.proto`]: https://github.com/emissary-ingress/emissary/tree/master/api/envoy/service/ratelimit/v3/rls.proto - -$productName$ generates a gRPC request to the external rate limit -service and provides a list of labels on which the rate limit service can base -its decision to accept or reject the request: - -``` -[ - {"source_cluster", ""}, - {"destination_cluster", ""}, - {"remote_address", ""}, - {"generic_key", ""}, - {"", ""} -] -``` - -If $productName$ cannot contact the rate limit service, it will -allow the request to be processed as if there were no rate limit service -configuration. - -It is the external rate limit service's responsibility to determine whether rate -limiting should take place, depending on custom business logic. The rate limit -service must simply respond to the request with an `OK` or `OVER_LIMIT` code: - -- If Envoy receives an `OK` response from the rate limit service, then $productName$ allows the client request to resume being processed by - the normal flow. -- If Envoy receives an `OVER_LIMIT` response, then $productName$ - will return an HTTP 429 response to the client and will end the transaction - flow, preventing the request from reaching the backing service. - -The headers injected by the [AuthService](../auth-service) can also be passed to -the rate limit service since the `AuthService` is invoked before the -`RateLimitService`. - -## Configuring the rate limit service - -A `RateLimitService` manifest configures $productName$ to use an -external service to check and enforce rate limits for incoming requests: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: RateLimitService -metadata: - name: ratelimit -spec: - service: 'example-rate-limit.default:5000' - protocol_version: # default is v2, if upgrading from 2.x then you must set this to v3. - failure_mode_deny: false # when set to true envoy will return 500 error when unable to communicate with RateLimitService -``` - -- `service` gives the URL of the rate limit service. If using a Kubernetes service, this should be the [namespace-qualified DNS name](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#namespaces-of-services) of that service. -- `protocol_version` Allowed values are `v3` and `v2`(default). `protocol_version` was used in previous versions of $productName$ to control the protocol used by the gRPC service to communicate with the `RateLimitService`. $productName$ 3.x is running an updated version of Envoy that has dropped support for the `v2` protocol, so starting in 3.x, if `protocol_version` is not specified, 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. -- `failure_mode_deny` By default, Envoy will fail open when unable to communicate with the service due to it becoming unvailable or due to timeouts. When this happens the upstream service that is being protected by a rate limit may be overloaded due to this behavior. When set to `true` Envoy will be configured to return a `500` status code when it is unable to communicate with the RateLimit service and will fail closed by rejecting request to the upstream service. - -You may only use a single `RateLimitService` manifest. - -## Rate limit service and TLS - -You can tell $productName$ to use TLS to talk to your service by -using a `RateLimitService` with an `https://` prefix. However, you may also -provide a `tls` attribute: if `tls` is present and `true`, $productName$ will originate TLS even if the `service` does not have the `https://` -prefix. - -If `tls` is present with a value that is not `true`, the value is assumed to be the name of a defined TLS context, which will determine the certificate presented to the upstream service. - -## Example - -The [$OSSproductName$ Rate Limiting -Tutorial](../../../../howtos/rate-limiting-tutorial) has a simple rate limiting -example. For a more advanced example, read the [advanced rate limiting -tutorial](../../../../../2.0/howtos/advanced-rate-limiting), which uses the rate limit -service that is integrated with $AESproductName$. - -## Further reading - -- [Rate limiting: a useful tool with distributed systems](https://blog.getambassador.io/rate-limiting-a-useful-tool-with-distributed-systems-6be2b1a4f5f4) -- [Rate limiting for API Gateways](https://blog.getambassador.io/rate-limiting-for-api-gateways-892310a2da02) -- [Implementing a Java Rate Limiting Service for $productName$](https://blog.getambassador.io/implementing-a-java-rate-limiting-service-for-the-ambassador-api-gateway-e09d542455da) -- [Designing a Rate Limit Service for $productName$](https://blog.getambassador.io/designing-a-rate-limiting-service-for-ambassador-f460e9fabedb) diff --git a/content/en/docs/pre-release/topics/running/services/tracing-service.md b/content/en/docs/pre-release/topics/running/services/tracing-service.md deleted file mode 100644 index b46e6870..00000000 --- a/content/en/docs/pre-release/topics/running/services/tracing-service.md +++ /dev/null @@ -1,139 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Tracing Service - -Applications that consist of multiple services can be difficult to debug, as a single request can span multiple services. Distributed tracing tells the story of your request as it is processed through your system. Distributed tracing is a powerful tool to debug and analyze your system in addition to request logging and metrics. - -When enabled, the `TracingService` will instruct $productName$ to initiate a trace on requests by generating and populating an `x-request-id` HTTP header. Services can make use of this `x-request-id` header in logging and forward it in downstream requests for tracing. $productName$ also integrates with external trace visualization services, including Zipkin-compatible APIs such as [Zipkin](https://zipkin.io/) and [Jaeger](https://github.com/jaegertracing/) to allow you to store and visualize traces. You can read further on [Envoy's Tracing capabilities](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/tracing). - -A `TracingService` manifest configures $productName$ to use an external trace visualization service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TracingService -metadata: - name: tracing -spec: - service: "example-zipkin:9411" - driver: zipkin - config: {} - custom_tags: # optional - - tag: host - request_header: - name: ":authority" - default_value: "unknown" - - tag: path - request_header: - name: ":path" - default_value: "unknown" - sampling: - overall: 100 -``` - -| Field | Description | values | -| --------- | ----------- | ------------- | -| `service` | gives the URL of the external HTTP trace service. | ex. `example-zipkin:9411` | -| `driver` | provides the driver information that handles communicating with the service | enum:
`zipkin`
`datadog`
`opentelemetry` | -| `config` | provides additional configuration options for the selected `driver`. Supported configuration for each driver is found below. | | -| `tag_headers` | **Deprecated** - it is recommend that you switch to using `custom_tags`| | -| `custom_tags` | configure tags to attach to traces. See section below for more details. | | -| `propagation_modes` | (optional) if present, specifies a list of the propogation modes to be used | enum:
`ENVOY`
`B3`
`TRACE_CONTEXT` | -| `sampling` | (optional) if present, specifies some target percentages of requests that will be traced. | | - -Please note that you must use the HTTP/2 pseudo-header names. For example: - -- the `host` header should be specified as the `:authority` header; and -- the `method` header should be specified as the `:method` header. - - -$productName$ supports a single Global 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. - - -## Supported Tracing Drivers - -The `TracingService` currently supports the following drivers: - -- `zipkin` -- `datadog` -- `opentelemetry` - - -In Envoy 1.24, support for the 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 - - - -In $productName$ 3.5.0, support for Envoy's native OpenTelemetry driver was added to the TracingService. Envoy still considers this driver experimental. - - -## Sampling - -Configuring `sampling` will specify some target percentages of requests that will be traced. This is beneficial for high-volume services to control the amount of tracing data collected. Sampling can be configured with the following fields: - -- `client`: percentage of requests that will be force traced if the `x-client-trace-id` header is set. Defaults to 100. -- `random`: percentage of requests that will be randomly traced. Defaults to 100. -- `overall`: percentage of requests that will be traced after all other checks have been applied (force tracing, sampling, etc.). -This field functions as an upper limit on the total configured sampling rate. For instance, setting `client` -to `100%` but `overall` to `1%` will result in only `1%` of client requests with the appropriate headers to be force -traced. Defaults to 100. - -## Custom Tags and Tag Headers - -When collecting traces, $productName$ will attach tags to the `span`'s that are generated which are useful for observability. See the [Envoy Tracing Docs](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/observability/tracing#what-data-each-trace-contains) for the default list of data collected. - -Previous versions of $productName$ only supported adding additional tags through the use of the `tag_headers` field. This field is now **deprecated** and it is recommended to use `custom_tags` which supports a more powerful set of features for adding additional tags to a span. - - -If both tag_headers and custom_tags are set then tag_headers will be ignored. - - -`custom_tags` provides support for configuring additional tags based on [Envoy Custom Tags](https://www.envoyproxy.io/docs/envoy/latest/api-v3/type/tracing/v3/custom_tag.proto%23custom-tag). The following custom tag kinds supported are: - -- `request_header` - set tag from header in the request -- `environment` - set tag from an environment variable -- `literal` - set tag based on a configured literal value - -Each custom_tag supports setting oneOf `request_header`, `literal` or `environment`. Each tag should have its own entry in `custom_tags`. - -For example: - -```yaml -custom_tags: - - tag: host - request_header: - name: ":authority" - default_value: "unknown host" # optional - - tag: path - request_header: ":path" - name: ":authority" - default_value: "unknown path" # optional - - tag: cluster - literal: - value: "us-east-cluster" - - tag: nodeID - environment: - name: SERVER_ID - default_value: "unknown" # optional -``` - -## Zipkin Driver Configurations - -- `collector_endpoint` gives the API endpoint of the Zipkin service where the spans will be sent. The default value is `/api/v2/spans` -- `collector_endpoint_version` gives the transport version used when sending data to your Zipkin collector. The default value is `HTTP_JSON` and it must be one of `HTTP_JSON` or `HTTP_PROTO`. -- `collector_endpoint_hostname` sets the hostname Envoy will use when sending data to your Zipkin collector. The default value is the name of the underlying Envoy cluster. -- `trace_id_128bit` whether a 128-bit `trace id` will be used when creating a new trace instance. Defaults to `true`. Setting to `false` will result in a 64-bit trace id being used. -- `shared_span_context` whether client and server spans will share the same `span id`. The default value is `true`. - -## Datadog Driver Configurations - -- `service_name` the name of the service which is attached to the traces. The default value is `ambassador`. - -## OpenTelemetry Driver Configurations - -- `service_name` the name of the service which is attached to traces. The default value is `ambassador`. - -## Example - -Check out the [DataDog](../../../../howtos/tracing-datadog) and [Zipkin](../../../../howtos/tracing-zipkin) HOWTOs. diff --git a/content/en/docs/pre-release/topics/running/statistics/8877-metrics.md b/content/en/docs/pre-release/topics/running/statistics/8877-metrics.md deleted file mode 100644 index 94bd2043..00000000 --- a/content/en/docs/pre-release/topics/running/statistics/8877-metrics.md +++ /dev/null @@ -1,64 +0,0 @@ -# The metrics endpoint - -> For an overview of other options for gathering statistics on -> $productName$, see the [Statistics and Monitoring](../) overview. - -Each $productName$ pod exposes statistics and metrics for that pod at -`http://{POD}:8877/metrics`. The response is in the text-based -Prometheus [exposition format][]. - -[exposition format]: https://prometheus.io/docs/instrumenting/exposition_formats/ - -## Understanding the statistics - -The Prometheus exposition format includes special "HELP" lines that -make the file self-documenting as to what specific statistics mean. - - - -- `envoy_*`: See the [Envoy documentation][`GET /stats/prometheus`]. -- `ambassador_*`: - - `ambassador_edge_stack_*` (not present in $OSSproductName$): - - `ambassador_edge_stack_go_*`: See [`promethus.NewGoCollector()`][]. - - `ambassador_edge_stack_promhttp_*` See [`promhttp.Handler()`][]. - - `ambassador_edge_stack_process_*`: See [`promethus.NewProcessCollector()`][].. - - `ambassador_*_time_seconds` (for `*` = one of `aconf`, `diagnostics`, `econf`, `fetcher`, `ir`, or `reconfiguration`): - Gauges of how long the various core operations take in the diagd - process. - - `ambassador_diagnostics_(errors|notices)`: The number of - diagnostics errors and notices that would be shown in the - diagnostics UI or the Edge Policy Console. - - `ambassador_diagnostics_info`: [Info][`prometheus_client.Info`] - about the $productName$ install; all information is presented in - labels; the value of the Gauge is always "1". - - `ambassador_process_*`: See [`prometheus_client.ProcessCollector`][]. - -[`GET /stats/prometheus`]: https://www.envoyproxy.io/docs/envoy/v1.23.0/operations/admin.html#get--stats-prometheus -[`prometheus.NewProcessCollector`]: https://godoc.org/github.com/prometheus/client_golang/prometheus#NewProcessCollector -[`prometheus.NewGoCollector`]: https://godoc.org/github.com/prometheus/client_golang/prometheus#NewGoCollector -[`promhttp.Handler()`]: https://godoc.org/github.com/prometheus/client_golang/prometheus/promhttp#Handler -[`prometheus_client.Info`]: https://github.com/prometheus/client_python#info -[`prometheus_client.ProcessCollector`]: https://github.com/prometheus/client_python#process-collector - -## Polling the `:8877/metrics` endpoint with Prometheus - -To scrape metrics directly, follow the instructions for [Monitoring -with Prometheus and Grafana](../../../../howtos/prometheus). - -### Using Grafana to visualize statistics gathered by Prometheus - -#### Sample dashboard - -We provide a [sample Grafana dashboard](https://grafana.com/grafana/dashboards/4698-ambassador-edge-stack/) -that displays information collected by Prometheus from the -`:8877/metrics` endpoint. - -![Screenshot of a Grafana dashboard that displays just information from Envoy](../../../images/grafana.png) diff --git a/content/en/docs/pre-release/topics/running/statistics/envoy-statsd.md b/content/en/docs/pre-release/topics/running/statistics/envoy-statsd.md deleted file mode 100644 index 7cbcc208..00000000 --- a/content/en/docs/pre-release/topics/running/statistics/envoy-statsd.md +++ /dev/null @@ -1,109 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Envoy statistics with StatsD - -> For an overview of other options for gathering statistics on -> $productName$, see the [Statistics and Monitoring](../) overview. - -At the core of $productName$ is [Envoy Proxy], which has built-in -support for exporting a multitude of statistics about its own -operations to StatsD (or to the modified DogStatsD used by Datadog). - -[Envoy Proxy]: https://www.envoyproxy.io - -If enabled, then $productName$ has Envoy expose this information via the -[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: - -```diff - spec: - containers: - - env: -+ - name: STATSD_ENABLED -+ value: "true" - - name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: -``` - -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. - -We have included a few example configurations in -[the `statsd-sink/` directory](https://github.com/emissary-ingress/emissary/tree/master/deployments/statsd-sink) -to help you get started. Clone or download the -repository to get local, editable copies and open a terminal -window in the `emissary/deployments/` folder. - -## Using Graphite as the StatsD sink - -[Graphite] is a web-based real-time graphing system. Spin up an -example Graphite setup: - -[Graphite]: http://graphite.readthedocs.org/ - -``` -kubectl apply -f statsd-sink/graphite/graphite-statsd-sink.yaml -``` - -This sets up the `statsd-sink` service and a deployment that contains -Graphite and its related infrastructure. Graphite's web interface is -available at `http://statsd-sink/` from within the cluster. Use port -forwarding to access the interface from your local machine: - -``` -SINKPOD=$(kubectl get pod -l service=statsd-sink -o jsonpath="{.items[0].metadata.name}") -kubectl port-forward $SINKPOD 8080:80 -``` - -This sets up Graphite access at `http://localhost:8080/`. - -## Using Datadog DogStatsD as the StatsD sink - -If you are a user of the [Datadog] monitoring system, pulling in the -Envoy statistics from $productName$ is very easy. - -[Datadog]: https://www.datadoghq.com/ - -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: - -```diff - spec: - containers: - - env: -+ - name: STATSD_ENABLED -+ value: "true" -+ - name: DOGSTATSD -+ value: "true" - - name: AMBASSADOR_NAMESPACE - valueFrom: - fieldRef: -``` - -Then, you will need to deploy the DogStatsD agent in to your cluster -to act as the StatsD sink. To do this, replace the sample API key in -our [sample YAML file][`dd-statsd-sink.yaml`] with your own, then -apply that YAML: - -[`dd-statsd-sink.yaml`]: https://github.com/emissary-ingress/emissary/blob/master/deployments/statsd-sink/datadog/dd-statsd-sink.yaml - -``` -kubectl apply -f statsd-sink/datadog/dd-statsd-sink.yaml -``` - -This sets up the `statsd-sink` service and a deployment of the -DogStatsD agent that forwards the $productName$ statistics to your -Datadog account. - -Additionally, $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). diff --git a/content/en/docs/pre-release/topics/running/statistics/index.md b/content/en/docs/pre-release/topics/running/statistics/index.md deleted file mode 100644 index ab44009f..00000000 --- a/content/en/docs/pre-release/topics/running/statistics/index.md +++ /dev/null @@ -1,84 +0,0 @@ -# Statistics and monitoring - -$productName$ collects many statistics internally, and makes it easy to -direct this information to a statistics and monitoring tool of your -choice. - -As an example, here are some interesting statistics to investigate: - -- `upstream_rq_total` is the total - number of requests that a particular service has received via $productName$. The rate of change of this value is one basic measure of - service utilization, i.e. requests per second. -- `upstream_rq_xx` is the total number - of requests to which a service responded with a given status code. - This value divided by the prior one, taken on - a rolling window basis, represents the recent response rate of the - service. There are corresponding classes for `2xx`, `3xx`, `4xx` and `5xx` counters that can - help clarify the nature of responses. -- `upstream_rq_time` is a Prometheus histogram or StatsD timer - that tracks the latency in milliseconds of a given service from $productName$'s perspective. - -## Overriding Statistics Names - -The optional `stats_name` element of every CRD that references a service (`Mapping`, `TCPMapping`, -`AuthService`, `LogService`, `RateLimitService`, and `TracingService`) can override the name under which cluster statistics -are logged (`usersvc` above). If not set, the default is the `service` value, with non-alphanumeric characters replaced by -underscores: - -- `service: foo` will just use `foo` -- `service: foo:8080` will use `foo_8080` -- `service: http://foo:8080` will use `http___foo_8080` -- `service: foo.othernamespace` will use `foo_othernamespace` - -The last example is worth special mention: a resource in a different namespace than the one in which $productName$ is running will automatically be qualified with the namespace of the resource itself. So, for example, if $productName$ is running in the `ambassador` namespace, and this `Mapping` is present in the `default` namespace: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: default-mapping - namespace: default -spec: - prefix: /default/ - service: default-service -``` - -then the `service` will be qualified to `default-service.default`, so the `stats_name` will be `default_service_default` rather than simply `default_service`. To change this behavior, set `stats_name` explicitly. - -## Monitoring Statistics - -There are several ways to get different statistics out of $productName$: - -- [The `:8877/metrics` endpoint](./8877-metrics) can be polled for - aggregated statistics (in a Prometheus-compatible format). This is - our recommended method as both Envoy metrics and $productName$ control plane - metrics are collected. -- $productName$ can push [Envoy statistics](./envoy-statsd) over the - StatsD or DogStatsD protocol. - -## The Four Golden Signals - -The [Four Golden Signals](https://sre.google/sre-book/monitoring-distributed-systems/) are four generally-accepted metrics -that are important to monitor for good information about service health: - -### Latency - -The time it takes to service a request as a histogram of time taken by individual requests, which can be an effective latency metric. -In StatsD, this stat would be expressed as `cluster.$name.upstream_rq_time`. -While in Prometheus format, this metric would be expressed as `envoy_cluster_upstream_rq_time_bucket{envoy_cluster_name="$name"}`. - -### Traffic - -The amount of demand being placed on your system as a gauge that shows the number of active outstanding requests, which can be a good proxy for traffic. -In StatsD, this stat would be expressed as `cluster.$name.upstream_rq_active`. -While in Prometheus format, this metric would be expressed as `envoy_cluster_upstream_rq_active{envoy_cluster_name="$name"}`. - -### Errors - -The number of failing requests. Some errors (e.g. a request succeeds, but gives the wrong answer) can only be detected by application-specific monitoring; however, many errors can be spotted simply by looking at the HTTP status code of requests. Monitoring it over time can show error rates. -In StatsD, `cluster.$name.upstream_rq_5xx` is a counter of HTTP `5xx` responses. -While in Prometheus, `envoy_cluster_upstream_rq_xx{envoy_response_code_class="5", envoy_cluster_name="$name"}` is a counter of HTTP `5xx` responses. - -### Saturation - -The hardest metric to measure, saturation describes how much of the total capability of the system to respond to requests is being used. Fully measuring saturation often requires application-specific monitoring, but looking at the 99th percentile of latency over a short window - perhaps a minute - can often give an early indication of saturation problems. diff --git a/content/en/docs/pre-release/topics/running/tls/cleartext-redirection.md b/content/en/docs/pre-release/topics/running/tls/cleartext-redirection.md deleted file mode 100644 index 7144b1a3..00000000 --- a/content/en/docs/pre-release/topics/running/tls/cleartext-redirection.md +++ /dev/null @@ -1,76 +0,0 @@ -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`. - - - The 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. - - -## Cleartext Routing - -To allow cleartext to be routed, set the `requestPolicy.insecure.action` of a `Host` to `Route`: - -```yaml -requestPolicy: - insecure: - action: Redirect -``` - -This allows routing for either HTTP and HTTPS, or _only_ HTTP, depending on `tlsSecret` configuration: - -- If the `Host` does not specify a `tlsSecret`, it will only route HTTP, not terminating TLS at all. -- If the `Host` does specify a `tlsSecret`, it will route both HTTP and HTTPS. - - - The 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. - - -## HTTP->HTTPS redirection - -Most websites that force HTTPS will also automatically redirect any -requests that come into it over HTTP: - -``` -Client $productName$ -| | -| http:///api | -| --------------------------> | -| | -| 301: https:///api | -| <-------------------------- | -| | -| https:///api | -| --------------------------> | -| | -``` - -In $productName$, this is configured by setting the `insecure.action` in a `Host` to `Redirect`. - -```yaml -requestPolicy: - insecure: - action: Redirect -``` - -$productName$ determines which requests are secure and which are insecure using the -`securityModel` of the [`Listener`] that accepts the request. - -[`Listener`]: ../../listener - - - The 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. - diff --git a/content/en/docs/pre-release/topics/running/tls/index.md b/content/en/docs/pre-release/topics/running/tls/index.md deleted file mode 100644 index 850fb5c0..00000000 --- a/content/en/docs/pre-release/topics/running/tls/index.md +++ /dev/null @@ -1,487 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Transport Layer Security (TLS) - -$productName$'s robust TLS support exposes configuration options -for many different TLS use cases, using the [`Host`](#host) and -[`TLSContext`](#host-and-tlscontext) resources in concert. - -## Certificates and Secrets - -Properly-functioning TLS requires the use of [TLS certificates] to prove that the -various systems communicating are who they say they are. At minimum, $productName$ -must have a server certificate that identifies it to clients; when [mTLS] or -[client certificate authentication] are in use, additional certificates are needed. - -You supply certificates to $productName$ in Kubernetes [TLS Secrets]. These Secrets -_must_ contain valid X.509 certificates with valid PKCS1, PKCS8, or Elliptic Curve private -keys. If a Secret does not contain a valid certificate, an error message will be logged, for -example: - -``` -tls-broken-cert.default.1 2 errors:; 1. K8sSecret secret tls-broken-cert.default tls.key cannot be parsed as PKCS1 or PKCS8: asn1: syntax error: data truncated; 2. K8sSecret secret tls-broken-cert.default tls.crt cannot be parsed as x.509: x509: malformed certificate -``` - -If you set the `AMBASSADOR_FORCE_SECRET_VALIDATION` environment variable, the invalid -Secret will be rejected, and a `Host` or `TLSContext` resource attempting to use an invalid -certificate will be disabled entirely. **Note** that in $productName$ $version$, this -includes disabling cleartext communication for such a `Host`. - -[TLS Certificates]: https://protonmail.com/blog/tls-ssl-certificate/ -[mTLS]: mtls -[client certificate authentication]: ../../../howtos/client-cert-validation/ -[TLS Secrets]: https://kubernetes.io/docs/concepts/configuration/secret/#tls-secrets - -## `Host` - -A `Host` represents a domain in $productName$ and defines how the domain manages TLS. For more information on the Host resource, see [The Host CRD reference documentation](../host-crd). - -**If no `Host`s are present**, $productName$ synthesizes a `Host` that -allows only cleartext routing. You will need to explictly define `Host`s to enable -TLS termination. - - - The examples below do not define a requestPolicy; however, most real-world - usage of $productName$ will require defining the requestPolicy.
-
- For more information, please refer to the Host documentation. - - -### Bring your own certificate - -The `Host` can read a certificate from a Kubernetes Secret and use that certificate -to terminate TLS on a domain. - -The following example shows the certificate contained in the Kubernetes Secret named -`host-secret` configured to have $productName$ terminate TLS on the `host.example.com` -domain: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: host-secret -``` - -By default, `tlsSecret` will only look for the named secret in the same namespace as the `Host`. -In the above example, the secret `host-secret` will need to exist within the `default` namespace -since that is the namespace of the `Host`. - -To reference a secret that is in a different namespace from the `Host`, the `namespace` field is required. -The below example will configure the `Host` to use the `host-secret` secret from the `example` namespace. - -```yaml ---- -apiVersion: getambassador.io/v2 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - acmeProvider: - authority: none - tlsSecret: - name: host-secret - namespace: example -``` - - - - The Kubernetes Secret named by 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. - - - -### Advanced TLS configuration with the `Host` - -You can specify TLS configuration directly in the `Host` via the `tls` field. This is the -recommended method to do more advanced TLS configuration for a single `Host`. - -For example, the configuration to enforce a minimum TLS version on the `Host` looks as follows: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: min-secret - tls: - min_tls_version: v1.2 -``` - - - - The Kubernetes Secret named by 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. - - - -The following fields are accepted in the `tls` field: -```yaml -tls: - cert_chain_file: # string - private_key_file: # string - ca_secret: # string - cacert_chain_file: # string - alpn_protocols: # string - cert_required: # bool - min_tls_version: # string - max_tls_version: # string - cipher_suites: # array of strings - ecdh_curves: # array of strings - sni: # string - crl_secret: # string -``` - -These fields have the same function as in the [`TLSContext`](#tlscontext) resource, -as described below. - -### `Host` and `TLSContext` - -You can link a `Host` to a [`TLSContext`](#tlscontext) instead of defining `tls` -settings in the `Host` itself. This is primarily useful for sharing settings between -multiple `Host`s. - -#### Link a `TLSContext` to the `Host` - - - It is invalid to use both the 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. - - -To link a [`TLSContext`](#tlscontext) with a `Host`, create a [`TLSContext`](#tlscontext) -with the desired configuration and link it to the `Host` by setting the `tlsContext.name` -field in the `Host`. For example, to enforce a minimum TLS version on the `Host` above, -create a `TLSContext` with any name with the following configuration: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: min-tls-context -spec: - hosts: - - host.example.com - secret: min-secret - min_tls_version: v1.2 -``` - -Next, link it to the `Host` via the `tlsContext` field as shown: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: min-secret - tlsContext: - name: min-tls-context -``` - - - - The `Host` and the `TLSContext` must name the same Kubernetes Secret; if not, - $productName$ will disable TLS for the `Host`. - - - - - - The Kubernetes Secret named by 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. - - - - - - The `Host`'s `hostname` and the `TLSContext`'s `hosts` must have compatible settings. If - they do not, requests may not be accepted. - - - -See [`TLSContext`](#tlscontext) below to read more on the description of these fields. - -#### Create a `TLSContext` with the name `{{AMBASSADORHOST}}-context` (DEPRECATED) - - - This implicit 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. - - -The `Host` will implicitly link to the `TLSContext` when a `TLSContext` exists with the following: - -- the name `{{NAME_OF_AMBASSADORHOST}}-context` -- `hosts` in the `TLSContext` set to the same value as `hostname` in the `Host`, and -- `secret` in the `TLSContext` set to the same value as `tlsSecret` in the `Host` - -**As noted above, this implicit linking is deprecated.** - -For example, another way to enforce a minimum TLS version on the `Host` above would -be to simply create the `TLSContext` with the name `example-host-context` and then not modify the `Host`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-host-context -spec: - hosts: - - host.example.com - secret: host-secret - min_tls_version: v1.2 -``` - - - - The `Host` and the `TLSContext` must name the same Kubernetes Secret; if not, - $productName$ will disable TLS for the `Host`. - - - - - - The Kubernetes Secret named by 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. - - - - - - The `Host`'s `hostname` and the `TLSContext`'s `hosts` must have compatible settings. If - they do not, requests may not be accepted. - - - -Full reference for all options available to the `TLSContext` can be found [below](#tlscontext). - -## TLSContext - -The `TLSContext` is used to configure advanced TLS options in $productName$. -Remember, a `TLSContext` must always be paired with a `Host`. - -A full schema of the `TLSContext` can be found below with descriptions of the -different configuration options. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: example-host-context -spec: - # 'hosts' defines the hosts for which this TLSContext is relevant. - # It ties into SNI. A TLSContext without "hosts" is useful only for - # originating TLS. - # type: array of strings - # - # hosts: [] - - # 'sni' defines the SNI string to use on originated connections. - # type: string - # - # sni: None - - # 'secret' defines a Kubernetes Secret that contains the TLS certificate we - # use for origination or termination. If not specified, $productName$ will look - # at the value of cert_chain_file and private_key_file. - # type: string - # - # secret: None - - # 'ca_secret' defines a Kubernetes Secret that contains the TLS certificate we - # use for verifying incoming TLS client certificates. - # type: string - # - # ca_secret: None - - # Tells $productName$ whether to interpret a "." in the secret name as a "." or - # a namespace identifier. - # type: boolean - # - # secret_namespacing: true - - # 'cert_required' can be set to true to _require_ TLS client certificate - # authentication. - # type: boolean - # - # cert_required: false - - # 'alpn_protocols' is used to enable the TLS ALPN protocol. It is required - # if you want to do GRPC over TLS; typically it will be set to "h2" for that - # case. - # type: string (comma-separated list) - # - # alpn_protocols: None - - # 'min_tls_version' sets the minimum acceptable TLS version: v1.0, v1.1, - # v1.2, or v1.3. It defaults to v1.0. - # min_tls_version: v1.0 - - # 'max_tls_version' sets the maximum acceptable TLS version: v1.0, v1.1, - # v1.2, or v1.3. It defaults to v1.3. - # max_tls_version: v1.3 - - # Tells $productName$ to load TLS certificates from a file in its container. - # type: string - # - # cert_chain_file: None - # private_key_file: None - # cacert_chain_file: None -``` - - - - `secret` and (if used) `ca_secret` must specify Kubernetes Secrets containing valid TLS - certificates. If `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and either Secret contains - an invalid certificate, $productName$ will reject the Secret, which will also completely - disable any `Host` using the `TLSContext`; see [**Certificates and Secrets**](#certificates-and-secrets) - above. - - - -### ALPN protocols - -The `alpn_protocols` setting configures the TLS ALPN protocol. To use gRPC over -TLS, set `alpn_protocols: h2`. If you need to support HTTP/2 upgrade from -HTTP/1, set `alpn_protocols: h2,http/1.1` in the configuration. - -#### HTTP/2 support - -The `alpn_protocols` setting is also required for HTTP/2 support. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls -spec: - secret: ambassador-certs - hosts: ["*"] - alpn_protocols: h2[, http/1.1] -``` -Without setting alpn_protocols as shown above, HTTP2 will not be available via -negotiation and will have to be explicitly requested by the client. - -If you leave off http/1.1, only HTTP2 connections will be supported. - -### TLS parameters - -The `min_tls_version` setting configures the minimum TLS protocol version that -$productName$ will use to establish a secure connection. When a client -using a lower version attempts to connect to the server, the handshake will -result in the following error: `tls: protocol version not supported`. - -The `max_tls_version` setting configures the maximum TLS protocol version that -$productName$ will use to establish a secure connection. When a client -using a higher version attempts to connect to the server, the handshake will -result in the following error: -`tls: server selected unsupported protocol version`. - -The `cipher_suites` setting configures the supported ciphers found below using the -[configuration parameters for BoringSSL](https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#Cipher-suite-configuration) when negotiating a TLS 1.0-1.2 connection. -This setting has no effect when negotiating a TLS 1.3 connection. When a client does not -support a matching cipher a handshake error will result. - -The `ecdh_curves` setting configures the supported ECDH curves when negotiating -a TLS connection. When a client does not support a matching ECDH a handshake -error will result. - -``` - - AES128-SHA - - AES256-SHA - - AES128-GCM-SHA256 - - AES256-GCM-SHA384 - - ECDHE-RSA-AES128-SHA - - ECDHE-RSA-AES256-SHA - - ECDHE-RSA-AES128-GCM-SHA256 - - ECDHE-RSA-AES256-GCM-SHA384 - - ECDHE-RSA-CHACHA20-POLY1305 - - ECDHE-ECDSA-AES128-SHA - - ECDHE-ECDSA-AES256-SHA - - ECDHE-ECDSA-AES128-GCM-SHA256 - - ECDHE-ECDSA-AES256-GCM-SHA384 - - ECDHE-ECDSA-CHACHA20-POLY1305 - - ECDHE-PSK-AES128-CBC-SHA - - ECDHE-PSK-AES256-CBC-SHA - - ECDHE-PSK-CHACHA20-POLY1305 - - PSK-AES128-CBC-SHA - - PSK-AES256-CBC-SHA - - DES-CBC3-SHA -``` - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls -spec: - hosts: ["*"] - secret: ambassador-certs - min_tls_version: v1.0 - max_tls_version: v1.3 - cipher_suites: - - "[ECDHE-ECDSA-AES128-GCM-SHA256|ECDHE-ECDSA-CHACHA20-POLY1305]" - - "[ECDHE-RSA-AES128-GCM-SHA256|ECDHE-RSA-CHACHA20-POLY1305]" - ecdh_curves: - - X25519 - - P-256 -``` - - -The `crl_secret` field allows you to reference a Kubernetes Secret that contains a certificate revocation list. -If specified, $productName$ will verify that the presented peer certificate has not been revoked by this CRL even if they are otherwise valid. This provides a way to reject certificates before they expire or if they become compromised. -The `crl_secret` field takes a PEM-formatted [Certificate Revocation List](https://en.wikipedia.org/wiki/Certificate_revocation_list) in a `crl.pem` entry. - -Note that if a CRL is provided for any certificate authority in a trust chain, a CRL must be provided for all certificate authorities in that chain. Failure to do so will result in verification failure for both revoked and unrevoked certificates from that chain. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls-crl -spec: - hosts: ["*"] - secret: ambassador-certs - min_tls_version: v1.0 - max_tls_version: v1.3 - crl_secret: 'ambassador-crl' ---- -apiVersion: v1 -kind: Secret -metadata: - name: ambassador-crl - namespace: ambassador -type: Opaque -data: - crl.pem: | - {BASE64 CRL CONTENTS} ---- -``` diff --git a/content/en/docs/pre-release/topics/running/tls/mtls.md b/content/en/docs/pre-release/topics/running/tls/mtls.md deleted file mode 100644 index 1b039cf8..00000000 --- a/content/en/docs/pre-release/topics/running/tls/mtls.md +++ /dev/null @@ -1,88 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Mutual TLS (mTLS) - -Many organizations have security concerns that require all network traffic -throughout their cluster be encrypted. With traditional architectures, -this was not that complicated of a requirement since internal network traffic -was fairly minimal. With microservices, we are making many more requests over -the network that must all be authenticated and secured. - -In order for services to authenticate with each other, they will each need to -provide a certificate and key that the other trusts before establishing a -connection. This action of both the client and server providing and validating -certificates is referred to as mutual TLS. - -## mTLS with $productName$ - -Since $productName$ is a reverse proxy acting as the entry point to your cluster, -$productName$ is acting as the client as it proxies requests to services upstream. - -It is trivial to configure $productName$ to simply originate TLS connections as -the client to upstream services by setting -`service: https://{{UPSTREAM_SERVICE}}` in the `Mapping` configuration. -However, in order to do mTLS with services upstream, $productName$ must also -have certificates to authenticate itself with the service. - -To do this, we can use the `TLSContext` object to get certificates from a -Kubernetes `Secret` and use those to authenticate with the upstream service. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: upstream-context -spec: - hosts: [] - secret: upstream-certs -``` - -We use `hosts: []` for this `TLSContext` since we do not want to use it to terminate -TLS connections from the client. We are just using this to load certificates for -requests upstream. - - - - The Kubernetes Secret must contain a valid TLS certificate. If the environment - variable `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) in the TLS overview. - - - -After loading the certificates, we can tell $productName$ when to use them by -setting the `tls` parameter in a `Mapping`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: upstream-mapping -spec: - hostname: "*" - prefix: /upstream/ - service: upstream-service - tls: upstream-context -``` - -Now, when $productName$ proxies a request to `upstream-service`, it will provide -the certificates in the `upstream-certs` secret for authentication when -encrypting traffic. - -## Service mesh - -As you can imagine, when you have many services in your cluster all -authenticating with each other, managing all of those certificates can become a -very big challenge. - -For this reason, many organizations rely on a service mesh for their -service-to-service authentication and encryption. - -$productName$ integrates with multiple service meshes and makes it easy to -configure mTLS to upstream services for all of them. Click the links below to -see how to configure $productName$ to do mTLS with any of these service meshes: - -- [Consul Connect](../../../../howtos/consul/) - -- [Istio](../../../../howtos/istio/) diff --git a/content/en/docs/pre-release/topics/running/tls/origination.md b/content/en/docs/pre-release/topics/running/tls/origination.md deleted file mode 100644 index b15dd5f8..00000000 --- a/content/en/docs/pre-release/topics/running/tls/origination.md +++ /dev/null @@ -1,82 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# TLS origination - -Sometimes you may want traffic from $productName$ to your services to be encrypted. For the cases where terminating TLS at the ingress is not enough, $productName$ can be configured to originate TLS connections to your upstream services. - -## Basic configuration - -Telling $productName$ to talk to your services over HTTPS is easily configured in the `Mapping` definition by setting `https://` in the `service` field. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: basic-tls -spec: - hostname: "*" - prefix: / - service: https://example-service -``` - -## Advanced configuration using a `TLSContext` - -If your upstream services require more than basic HTTPS support (for example, providing a client certificate or -setting the minimum TLS version support) you must create a `TLSContext` for $productName$ to use when -originating TLS. For example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: TLSContext -metadata: - name: tls-context -spec: - secret: self-signed-cert - min_tls_version: v1.3 - sni: some-sni-hostname -``` - - - - The Kubernetes Secret named by `secret` must contain a valid TLS certificate. If the - environment variable `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and the Secret contains - an invalid certificate, $productName$ will reject the `TLSContext` and prevent its use; - see [**Certificates and Secrets**](../#certificates-and-secrets) in the TLS overview. - - - -Configure $productName$ to use this `TLSContext` for connections to upstream services by setting the `tls` attribute of a `Mapping`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-with-tls-context -spec: - hostname: "*" - prefix: / - service: https://example-service - tls: tls-context -``` - -The `example-service` service must now support TLS v1.3 for $productName$ to connect. - - - - The Kubernetes Secret named by `secret` must contain a valid TLS certificate. If the - environment variable `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and the Secret contains - an invalid certificate, $productName$ will reject the `TLSContext` and prevent its use; - see [**Certificates and Secrets**](../#certificates-and-secrets) in the TLS overview. - - - - - - A `TLSContext` requires a certificate be provided, even in cases where the upstream - service does not require it (for origination) and the `TLSContext` is not being used - to terminate TLS. In this case, simply generate and provide a self-signed certificate. - - diff --git a/content/en/docs/pre-release/topics/running/tls/sni.md b/content/en/docs/pre-release/topics/running/tls/sni.md deleted file mode 100644 index 92e4992f..00000000 --- a/content/en/docs/pre-release/topics/running/tls/sni.md +++ /dev/null @@ -1,103 +0,0 @@ -# Server Name Indication (SNI) - -$productName$ supports serving multiple `Host`s behind a single IP address, each -with their own certificate. - -This is as easy to do as creating a `Host` for each domain or subdomain you -want $productName$ to serve, getting a certificate for each, and telling -$productName$ which `Host` the route should be created for. - -The example below configures two `Host`s and assigns routes to them. - -## Configuring a `Host` - -The `Host` resources lets you separate configuration for each distinct domain -and subdomain you plan on serving behind $productName$. - -Let's start by creating a simple `Host` and providing our own certificate in -the `host-cert` secret. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: example-host -spec: - hostname: host.example.com - tlsSecret: - name: host-cert -``` - -Now let's create a second `Host` for a different domain we want to serve behind -$productName$. This second `Host` uses $AESproductName$'s automatic TLS -to get a certificate from Let's Encrypt. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Host -metadata: - name: foo-host -spec: - hostname: host.foo.com - acmeProvider: - email: julian@example.com -``` - -We now have two `Host`s with two different certificates. - - - A minimum version of TLS 1.1 is required to properly use SNI. When setting up your TLS configuration, be sure you are not using TLS 1.0 or older. - - -## Configuring routes - -Now that we have two domains behind $productName$, we can create routes for either -or both of them. - -We do this by setting the `hostname` attribute of a `Mapping` to the domain the -`Mapping` should be created for. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin -spec: - prefix: /httpbin/ - service: httpbin.org:80 - host_rewrite: httpbin.org - hostname: host.example.com -``` - -The above creates a `/httpbin/` endpoint for `host.example.com`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mockbin -spec: - prefix: /foo/ - service: foo-service - hostname: host.foo.com -``` - -The above creates a `/foo/` endpoint for `host.foo.com`. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: frontend -spec: - hostname: "*" - prefix: /bar/ - service: bar-endpoint -``` - -The above creates a `/bar/` endpoint for all `Host`s. diff --git a/content/en/docs/pre-release/topics/using/authservice.md b/content/en/docs/pre-release/topics/using/authservice.md deleted file mode 100644 index 9bc2630f..00000000 --- a/content/en/docs/pre-release/topics/using/authservice.md +++ /dev/null @@ -1,24 +0,0 @@ -# AuthService settings - -A Mapping can pass these settings along to an [AuthService](../../running/services/auth-service). This is helpful to allow these specific configurations to apply only to certain Mappings and not globally. - -## Bypass authentication - -An AuthService can be disabled for a specific Mapping with the `bypass_auth` attribute. This will tell $productName$ to allow all requests for that Mapping through without interacting with the external auth service. This could be helpful, for example, for a public API. - -```yaml -bypass_auth: true -``` - -## Context extensions (gRPC only) - -The `auth_context_extensions` attribute will pass the given values along to the AuthService when authentication happens. This is only supported when the `proto` of the AuthService is `grpc`, which is a restriction of the underlying Envoy implementation. -The values are arbitrary key value pairs formatted as strings. - -```yaml -auth_context_extensions: - foo: bar - baz: zing -``` - -More information is available on [the Envoy documentation on external authentication](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto.html#extensions-filters-http-ext-authz-v3-checksettings). diff --git a/content/en/docs/pre-release/topics/using/canary.md b/content/en/docs/pre-release/topics/using/canary.md deleted file mode 100644 index f99de1a3..00000000 --- a/content/en/docs/pre-release/topics/using/canary.md +++ /dev/null @@ -1,41 +0,0 @@ -# Canary releases - -Canary releasing is a deployment pattern where a small percentage of traffic is diverted to an early ("canary") release of a particular service. This technique lets you test a release on a small subset of users, mitigating the impact of any given bug. Canary releasing also allows you to quickly roll back to a known good version in the event of an unexpected error. Detailed monitoring of core service metrics is an essential part of canary releasing, as monitoring enables the rapid detection of problems in the canary release. - -## Canary releases in Kubernetes - -Kubernetes supports a basic canary release workflow using its core objects. In this workflow, a service owner can create a Kubernetes [service](https://kubernetes.io/docs/concepts/services-networking/service/). This service can then be pointed to multiple [deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/). Each deployment can be a different version. By specifying the number of `replicas` in a given deployment, you can control how much traffic goes between different versions. For example, you could set `replicas: 3` for `v1`, and `replicas: 1` for `v2`, to ensure that 25% of traffic goes to `v2`. This approach works but is fairly coarse-grained unless you have lots of replicas. Moreover, auto-scaling doesn't work well with this strategy. - -## Canary releases in $productName$ - -$productName$ supports fine-grained canary releases. $productName$ uses a weighted round-robin scheme to route traffic between multiple services. Full metrics are collected for all services, making it easy to compare the relative performance of the canary and production. - -### The weight attribute - -The `weight` attribute specifies how much traffic for a given resource will be routed using a given mapping. Its value is an integer percentage between 0 and 100. $productName$ will balance weights to make sure that, for every resource, the mappings for that resource will have weights adding to 100%. (In the simplest case, a single mapping is guaranteed to receive 100% of the traffic no matter whether it's assigned a `weight` or not.) - -Specifying a weight only makes sense if you have multiple mappings for the same resource, and typically you would _not_ assign a weight to the "default" mapping (the mapping expected to handle most traffic): letting $productName$ assign that mapping all the traffic not otherwise spoken for tends to make life easier when updating weights. - -Here's an example, which might appear during a canary deployment: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - prefix: /backend/ - service: quotev2 - weight: 10 -``` - -In this case, the quote-backend2 will receive 10% of the requests for `/backend/`, and $productName$ will assign the remaining 90% to the quote-backend. diff --git a/content/en/docs/pre-release/topics/using/circuit-breakers.md b/content/en/docs/pre-release/topics/using/circuit-breakers.md deleted file mode 100644 index 97b40f57..00000000 --- a/content/en/docs/pre-release/topics/using/circuit-breakers.md +++ /dev/null @@ -1,116 +0,0 @@ -# Circuit breakers - -Circuit breakers are a powerful technique to improve resilience. By preventing additional connections or requests to an overloaded service, circuit breakers limit the ["blast radius"](https://www.ibm.com/garage/method/practices/manage/practice_limited_blast_radius/) of an overloaded service. By design, $productName$ circuit breakers are distributed, i.e., different $productName$ instances do not coordinate circuit breaker information. - -## Circuit breaker configuration - -A default circuit breaking configuration can be set for all -$productName$ resources in the [`ambassador -Module`](../../running/ambassador), or set to a different value on a -per-resource basis for [`Mappings`](../mappings), -[`TCPMappings`](../tcpmappings/), and -[`AuthServices`](../../running/services/auth-service/). - -The `circuit_breakers` attribute configures circuit breaking. The following fields are supported: - -```yaml -circuit_breakers: -- priority: - max_connections: - max_pending_requests: - max_requests: - max_retries: -``` - -|Key|Default value|Description| -|---|---|---| -|`priority`|`default`|Specifies the priority to which the circuit breaker settings apply to; it can be set to either `default` or `high`.| -|`max_connections`|`1024`|Specifies the maximum number of connections that $productName$ will make to the services. In practice, this is more applicable to HTTP/1.1 than HTTP/2.| -|`max_pending_requests`|`1024`|Specifies the maximum number of requests that will be queued while waiting for a connection. In practice, this is more applicable to HTTP/1.1 than HTTP/2.| -|`max_requests`|`1024`|Specifies the maximum number of parallel outstanding requests to an upstream service. In practice, this is more applicable to HTTP/2 than HTTP/1.1.| -|`max_retries`|`3`|Specifies the maximum number of parallel retries allowed to an upstream service.| - -The `max_*` fields can be reduced to shrink the "blast radius," or -increased to enable $productName$ to handle a larger number of -concurrent requests. - -## Examples - -Circuit breakers defined on a single `Mapping`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - circuit_breakers: - - max_connections: 2048 - max_pending_requests: 2048 -``` - -Circuit breakers defined on a single `AuthService`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: AuthService -metadata: - name: dancing-walrus -spec: - auth_service: http://dancing-walrus:8500 - proto: grpc - circuit_breakers: - - max_requests: 4096 -``` - -A global circuit breaker: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - circuit_breakers: - - max_connections: 2048 - max_pending_requests: 2048 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote -``` - -## Circuit breakers and automatic retries - -Circuit breakers are best used in conjunction with [automatic retries](../retries). Here are some examples: - -* You've configured automatic retries for failed requests to a service. Your service is under heavy load, and starting to time out on servicing requests. In this case, automatic retries can exacerbate your problem, increasing the total request volume by 2x or more. By aggressively circuit breaking, you can mitigate failure in this scenario. -* To circuit break when services are slow, you can combine circuit breakers with retries. Reduce the time out for retries, and then set a circuit breaker that detects many retries. In this setup, if your service doesn't respond quickly, a flood of retries will occur, which can then trip the circuit breaker. - -Note that setting circuit breaker thresholds requires careful monitoring and experimentation. We recommend you start with conservative values for circuit breakers and adjust them over time. - -## More about circuit breakers - -Responses from a broken circuit contain the `x-envoy-overloaded` header. - -The following are the default values for circuit breaking if nothing is specified: - -```yaml -circuit_breakers: -- priority: default - max_connections: 1024 - max_pending_requests: 1024 - max_requests: 1024 - max_retries: 3 -``` - -Circuit breaker metrics are exposed in StatsD. For more information about the specific statistics, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/circuit_breaking.html). diff --git a/content/en/docs/pre-release/topics/using/cors.md b/content/en/docs/pre-release/topics/using/cors.md deleted file mode 100644 index 315e4694..00000000 --- a/content/en/docs/pre-release/topics/using/cors.md +++ /dev/null @@ -1,155 +0,0 @@ -# Cross-Origin Resource Sharing (CORS) - -Cross-Origin resource sharing lets users request resources (e.g., images, fonts, videos) from domains outside the original domain. - -CORS configuration can be set for all $productName$ mappings in the [`ambassador Module`](../../running/ambassador), or set per [`Mapping`](../mappings). - -When the CORS attribute is set at either the `Mapping` or `Module` level, $productName$ will intercept the pre-flight `OPTIONS` request and respond with the appropriate CORS headers. This means you will not need to implement any logic in your upstreams to handle these CORS `OPTIONS` requests. - -The flow of the request will look similar to the following: -``` -Client $productName$ Upstream - | OPTIONS | | - | —————————————————> | | - | CORS_RESP | | - | <————————————————— | | - | GET /foo/ | | - | —————————————————> | ————————————> | - | | RESP | - | <————————————————————————————————— | -``` -## The `cors` attribute - -The `cors` attribute enables the CORS filter. The following settings are supported: - -- `origins`: Specifies a list of allowed domains for the `Access-Control-Allow-Origin` header. To allow all origins, use the wildcard `"*"` value. Format can be either of: - - comma-separated list, e.g. - ```yaml - origins: http://foo.example,http://bar.example - ``` - - YAML array, e.g. - ```yaml - origins: - - http://foo.example - - http://bar.example - ``` - -- `methods`: if present, specifies a list of allowed methods for the `Access-Control-Allow-Methods` header. Format can be either of: - - comma-separated list, e.g. - ```yaml - methods: POST, GET, OPTIONS - ``` - - YAML array, e.g. - ```yaml - methods: - - GET - - POST - - OPTIONS - ``` - -- `headers`: if present, specifies a list of allowed headers for the `Access-Control-Allow-Headers` header. Format can be either of: - - comma-separated list, e.g. - ```yaml - headers: Content-Type - ``` - - YAML array, e.g. - ```yaml - headers: - - Content-Type - ``` - -- `credentials`: if present with a true value (boolean), will send a `true` value for the `Access-Control-Allow-Credentials` header. - -- `exposed_headers`: if present, specifies a list of allowed headers for the `Access-Control-Expose-Headers` header. Format can be either of: - - comma-separated list, e.g. - ```yaml - exposed_headers: X-Custom-Header - ``` - - YAML array, e.g. - ```yaml - exposed_headers: - - X-Custom-Header - ``` - -- `max_age`: if present, indicated how long the results of the preflight request can be cached, in seconds. This value must be a string. - -## Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cors -spec: - prefix: /cors/ - service: cors-example - cors: - origins: http://foo.example,http://bar.example - methods: POST, GET, OPTIONS - headers: Content-Type - credentials: true - exposed_headers: X-Custom-Header - max_age: "86400" -``` - -## AuthService and Cross-Origin Resource Sharing - -When you use external authorization, each incoming request is authenticated before routing to its destination, including pre-flight `OPTIONS` requests. - -By default, many [`AuthService`](../../running/services/auth-service) implementations will deny these requests. If this is the case, you will need to add some logic to your `AuthService` to accept all CORS headers. - -For example, a possible configuration for Spring Boot 2.0.1: - -```java -@EnableWebSecurity -class SecurityConfig extends WebSecurityConfigurerAdapter { - - public void configure(final HttpSecurity http) throws Exception { - http - .cors().configurationSource(new PermissiveCorsConfigurationSource()).and() - .csrf().disable() - .authorizeRequests() - .antMatchers("**").permitAll(); - } - - private static class PermissiveCorsConfigurationSource implements CorsConfigurationSource { - /** - * Return a {@link CorsConfiguration} based on the incoming request. - * - * @param request - * @return the associated {@link CorsConfiguration}, or {@code null} if none - */ - @Override - public CorsConfiguration getCorsConfiguration(final HttpServletRequest request) { - final CorsConfiguration configuration = new CorsConfiguration(); - configuration.setAllowCredentials(true); - configuration.setAllowedHeaders(Collections.singletonList("*")); - configuration.setAllowedMethods(Collections.singletonList("*")); - configuration.setAllowedOrigins(Collections.singletonList("*")); - return configuration; - } - } -} -``` - -This is okay since CORS is being handled by $productName$ after authentication. - -The flow of this request will look similar to the following: - -``` -Client $productName$ Auth Upstream - | OPTIONS | | | - | —————————————————> | ————————————> | | - | | CORS_ACCEPT_* | | - | CORS_RESP |<——————————————| | - | <——————————————————| | | - | GET /foo/ | | | - | —————————————————> | ————————————> | | - | | AUTH_RESP | | - | | <———————————— | | - | | AUTH_ALLOW | | - | | ————————————————————————————> | - | | | RESP | - | <————————————————————————————————————————————————— | - ``` diff --git a/content/en/docs/pre-release/topics/using/defaults.md b/content/en/docs/pre-release/topics/using/defaults.md deleted file mode 100644 index d08a84d8..00000000 --- a/content/en/docs/pre-release/topics/using/defaults.md +++ /dev/null @@ -1,32 +0,0 @@ -# Using `ambassador` `Module` defaults - -## The defaults element - -If present, the `ambassador Module` can define a set of defaults that will automatically be applied to certain resources: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - class1: # This is a class. Different resource types will look in different classes. - key1: value1 # Within a class, you can set different keys. - key2: value2 - ... - class2: - ... - top_key1: value1 # If a key isn't found in a resource's class, the system will look in the - top_key2: value2 # toplevel defaults dictionary for it. -``` - -### Mapping - -Currently, only the `Mapping` resource uses the `defaults` mechanism. `Mapping` looks first for defaultable resources in the `httpmapping` class, including: - -- [`add_request_headers`](../../using/headers/add-request-headers) -- [`add_response_headers`](../../using/headers/add-response-headers) -- [`remove_request_headers`](../../using/headers/remove-request-headers) -- [`remove_response_headers`](../../using/headers/remove-response-headers) diff --git a/content/en/docs/pre-release/topics/using/gateway-api.md b/content/en/docs/pre-release/topics/using/gateway-api.md deleted file mode 100644 index 5e92cd0d..00000000 --- a/content/en/docs/pre-release/topics/using/gateway-api.md +++ /dev/null @@ -1,19 +0,0 @@ -# Gateway API - -## Using the Gateway API - -$productName$ now supports a limited subset of the new `v1alpha1` [Gateway API](https://gateway-api.sigs.k8s.io/). -Note that the Gateway API is not supported when `AMBASSADOR_LEGACY_MODE` is set. - -Support is currently limited to the following fields, however this will expand in future releases: - - - `Gateway.spec.listeners.port` - - `HTTPRoute.spec.rules.matches.path.type` (`Exact`, `Prefix`, and `RegularExpression`) - - `HTTPRoute.spec.rules.matches.path.value` - - `HTTPRoute.spec.rules.matches.header.type` (`Exact` and `RegularExpression`) - - `HTTPRoute.spec.rules.matches.header.values` - - `HTTPRoute.spec.rules.forwardTo.serviceName` - - `HTTPRoute.spec.rules.forwardTo.port` - - `HTTPRoute.spec.rules.forwardTo.weight` - -Please see the [specification](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/) for more details. diff --git a/content/en/docs/pre-release/topics/using/headers/add-request-headers.md b/content/en/docs/pre-release/topics/using/headers/add-request-headers.md deleted file mode 100644 index c6ad4956..00000000 --- a/content/en/docs/pre-release/topics/using/headers/add-request-headers.md +++ /dev/null @@ -1,77 +0,0 @@ -# Add request headers - -$productName$ can add a dictionary of HTTP headers that can be added to each request that is passed to a service. - -## The `add_request_headers` attribute - -The `add_request_headers` attribute is a dictionary of `header`: `value` pairs. The `value` can be a `string`, `bool` or `object`. When it is an `object`, the object should have a `value` property, which is the actual header value, and the remaining attributes are additional envoy properties. - -Envoy dynamic values `%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%` and `%PROTOCOL%` are supported, in addition to static values. - -`add_request_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -### Mapping example - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: "*" - prefix: /backend/ - add_request_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-static-2: - value: This the test header #same as above "x-test-static header" - x-test-object: - value: This the value - append: False #True by default - service: quote - ``` - -will add the protocol, client IP, and a static header to `/backend/`. - -### Defaults example - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - add_request_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-static-2: - value: This the test header #same as above "x-test-static header" - x-test-object: - value: This the value - append: False #True by default ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - hostname: "*" - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - hostname: "*" - prefix: /backend2/ - service: quote -``` - -This example will add the same headers for both mappings. diff --git a/content/en/docs/pre-release/topics/using/headers/add-response-headers.md b/content/en/docs/pre-release/topics/using/headers/add-response-headers.md deleted file mode 100644 index 236ace61..00000000 --- a/content/en/docs/pre-release/topics/using/headers/add-response-headers.md +++ /dev/null @@ -1,73 +0,0 @@ -# Add response headers - -$productName$ can add a dictionary of HTTP headers that can be added to each response that is returned to the client. - -## The `add_response_headers` attribute - -The `add_response_headers` attribute is a dictionary of `header`: `value` pairs. The `value` can be a `string`, `bool` or `object`. When it is an `object`, the object should have a `value` property, which is the actual header value, and the remaining attributes are additional envoy properties. - -Envoy dynamic values `%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%` and `%PROTOCOL%` are supported, in addition to static values. - -`add_response_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -### Mapping example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - add_response_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-object: - append: False - value: this is from object header config - service: quote -``` - -will add the protocol, client IP, and a static header to the response returned to the client. - -### Defaults example - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - add_response_headers: - x-test-proto: "%PROTOCOL%" - x-test-ip: "%DOWNSTREAM_REMOTE_ADDRESS_WITHOUT_PORT%" - x-test-static: This is a test header - x-test-object: - append: False - value: this is from object header config ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - hostname: "*" - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - hostname: "*" - prefix: /backend2/ - service: quote -``` - -This example will add the same headers for both mappings. diff --git a/content/en/docs/pre-release/topics/using/headers/headers.md b/content/en/docs/pre-release/topics/using/headers/headers.md deleted file mode 100644 index 126653b0..00000000 --- a/content/en/docs/pre-release/topics/using/headers/headers.md +++ /dev/null @@ -1,76 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Header-based routing - -$productName$ can route to target services based on HTTP headers with the `headers` and `regex_headers` specifications. Multiple mappings with different annotations can be applied to construct more complex routing rules. - -## The `headers` annotation - -The `headers` attribute is a dictionary of `header`: `value` pairs. $productName$ will only allow requests that match the specified `header`: `value` pairs to reach the target service. - -### Example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - headers: - x-quote-mode: backend - x-random-header: datawire -``` - -will allow requests to /backend/ to succeed only if the x-quote-mode header has the value backend and the x-random-header has the value `datawire`. - - - 1.x versions of the Ambassador Edge Stack could test for the existence of a header using x-sample-header:true. Since 2.0, the same functionality is achieved by using regex_headers. - - -## Regex headers - -You can also set the `value` of a regex header to `".*"` to test for the existence of a header. - -### Conditional example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-mode -spec: - prefix: /backend/ - service: quote-mode - regex_headers: - x-quote-mode: ".*" - ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-regular -spec: - prefix: /backend/ - service: quote-regular -``` - -will send requests that contain the x-quote-mode header to the quote-mode target, while routing all other requests to the quote-regular target. - -The following mapping will route mobile requests from Android and iPhones to a mobile service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - regex_headers: - user-agent: ".*(iPhone|(a|A)ndroid).*" - prefix: /backend/ - service: quote -``` diff --git a/content/en/docs/pre-release/topics/using/headers/host.md b/content/en/docs/pre-release/topics/using/headers/host.md deleted file mode 100644 index 5a8dd02c..00000000 --- a/content/en/docs/pre-release/topics/using/headers/host.md +++ /dev/null @@ -1,76 +0,0 @@ -# Host headers - -$productName$ supports several different methods for managing the HTTP `Host` header. - -## Using `host` and `host_regex` - -A mapping that specifies the `host` attribute will take effect _only_ if the HTTP `Host` header matches the value in the `host` attribute. If `host_regex` is `true`, the `host` value is taken to be a regular expression. Otherwise, an exact string match is required. - -You may have multiple mappings listing the same resource but different `host` attributes to effect `Host`-based routing. An example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote1 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend-2 -spec: - prefix: /backend/ - host: quote.datawire.io - service: quote2 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend-3 -spec: - prefix: /backend/ - host: "^quote[2-9]\\.datawire\\.io$" - host_regex: true - service: quote3 -``` - -will map requests for `/` to - -- the `quote2` service if the `Host` header is `quote.datawire.io`; -- the `quote3` service if the `Host` header matches `^quote[2-9]\\.datawire\\.io$`; and to -- the `quote1` service otherwise. - -Note that enclosing regular expressions in quotes can be important to prevent backslashes from being doubled. - -## Using `host_rewrite` - -By default, the `Host` header is not altered when talking to the service -- whatever `Host` header the client gave to $productName$ will be presented to the service. For many microservices, this will be fine, but if you use $productName$ to route to services that use the `Host` header for routing, it's likely to fail (legacy monoliths are particularly susceptible to this, as well as external services). You can use `host_rewrite` to force the `Host` header to whatever value that such target services need. - -An example: the default $productName$ configuration includes the following mapping for `httpbin.org`: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin -spec: - prefix: /httpbin/ - service: httpbin.org:80 - host_rewrite: httpbin.org -``` - -As it happens, `httpbin.org` is virtually hosted, and it simply _will not_ function without a `Host` header of `httpbin.org`, which means that the `host_rewrite` attribute is necessary here. - -## `host` and `method` - -Internally: - -- the `host` attribute becomes a `header` match on the `:authority` header; and -- the `method` attribute becomes a `header` match on the `:method` header. - -You will see these headers in the diagnostic service if you use the `method` or `host` attributes. diff --git a/content/en/docs/pre-release/topics/using/headers/remove-request-headers.md b/content/en/docs/pre-release/topics/using/headers/remove-request-headers.md deleted file mode 100644 index 62603756..00000000 --- a/content/en/docs/pre-release/topics/using/headers/remove-request-headers.md +++ /dev/null @@ -1,57 +0,0 @@ -# Remove request headers - -$productName$ can remove a list of HTTP headers that would be sent to the upstream from the request. - -## The `remove_request_headers` attribute - -The `remove_request_headers` attribute takes a list of keys used to match to the header. - -`remove_request_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -## Mapping example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - remove_request_headers: - - authorization - service: quote -``` - -will drop the header with key `authorization`. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - remove_request_headers: - - authorization ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - prefix: /backend2/ - service: quote -``` - -This is the same as the mapping example, but the headers will be removed for both mappings. diff --git a/content/en/docs/pre-release/topics/using/headers/remove-response-headers.md b/content/en/docs/pre-release/topics/using/headers/remove-response-headers.md deleted file mode 100644 index 16b18569..00000000 --- a/content/en/docs/pre-release/topics/using/headers/remove-response-headers.md +++ /dev/null @@ -1,57 +0,0 @@ -# Remove response headers - -$productName$ can remove a list of HTTP headers that would be sent to the client in the response (e.g. default `x-envoy-upstream-service-time`). - -## The `remove_response_headers` attribute - -The `remove_response_headers` attribute takes a list of keys used to match to the header. - -`remove_request_headers` can be set either in a `Mapping` or using [`ambassador Module defaults`](../../defaults). - -## Mapping example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - remove_response_headers: - - x-envoy-upstream-service-time - service: quote -``` - -will drop the header with key `x-envoy-upstream-service-time`. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - defaults: - httpmapping: - remove_response_headers: - - x-envoy-upstream-service-time ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend1 -spec: - prefix: /backend1/ - service: quote ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend2 -spec: - prefix: /backend2/ - service: quote -``` - -This is the same as the mapping example, but the headers will be removed for both mappings. diff --git a/content/en/docs/pre-release/topics/using/index.md b/content/en/docs/pre-release/topics/using/index.md deleted file mode 100644 index d4f09a83..00000000 --- a/content/en/docs/pre-release/topics/using/index.md +++ /dev/null @@ -1,32 +0,0 @@ -# Using $productName$ - -Application development teams use $productName$ to manage edge policies associated with a specific service. This section of the documentation covers core $productName$ elements that are typically used by the application development team. - -* [Introduction to Mappings](intro-mappings) The `Mapping` resource is the core resource used by every application development team. -* Mapping Configuration: - * [Automatic Retries](retries) - * [Canary Releases](canary) - * [Circuit Breakers](circuit-breakers) - * [Cross Origin Resource Sharing](cors) - * HTTP Headers - * [Header-based Routing](headers/headers) - * [Host Header](headers/host) - * [Adding Request Headers](headers/add-request-headers) - * [Adding Response Headers](headers/add-response-headers) - * [Removing Request Headers](headers/remove-request-headers) - * [Remove Response Headers](headers/remove-response-headers) - * [Query Parameter Based Routing](query-parameters) - * [Keepalive](keepalive) - * Protocols - * [TCP](tcpmappings) - * gRPC, HTTP/1.0, gRPC-Web, WebSockets - * [RegEx-based Routing](prefix-regex) - * [Redirects](redirects) - * [Rewrites](rewrites) - * [Timeouts](timeouts) - * [Traffic Shadowing](shadowing) -* [Advanced Mapping Configuration](mappings) -* Rate Limiting - * [Introduction to Rate Limits](rate-limits/) -* [Developer Portal](../../tutorials/dev-portal-tutorial) -* [Gateway API](gateway-api) diff --git a/content/en/docs/pre-release/topics/using/intro-mappings.md b/content/en/docs/pre-release/topics/using/intro-mappings.md deleted file mode 100644 index 51656052..00000000 --- a/content/en/docs/pre-release/topics/using/intro-mappings.md +++ /dev/null @@ -1,148 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Introduction to the Mapping resource - -$productName$ is designed around a [declarative, self-service management model](../../concepts/gitops-continuous-delivery). The core resource used to support application development teams who need to manage the edge with $productName$ is the `Mapping` resource. - - - Remember that Listener and Host resources are -  required for a functioning $productName$ installation that can route traffic!
- Learn more about Listener.
- Learn more about Host. - - -## Quick example - -At its core a `Mapping` resource maps a `resource` to a `service`: - -| Required attribute | Description | -| :------------------------ | :------------------------ | -| `name` | is a string identifying the `Mapping` (e.g. in diagnostics) | -| [`prefix`](#resources) | is the URL prefix identifying your [resource](#resources) | -| [`service`](#services) | is the name of the [service](#services) handling the resource; must include the namespace (e.g. `myservice.othernamespace`) if the service is in a different namespace than $productName$ | - -These resources are defined as Kubernetes Custom Resource Definitions. Here's a simple example that maps all requests to `/httpbin/` to the `httpbin.org` web service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: httpbin-mapping -spec: - prefix: /httpbin/ - service: http://httpbin.org -``` - -## Applying a Mapping resource - -A `Mapping` resource can be managed using the same workflow as any other Kubernetes resources (e.g., `service`, `deployment`). For example, if the above `Mapping` is saved into a file called `httpbin-mapping.yaml`, the following command will apply the configuration directly to $productName$: - -``` -kubectl apply -f httpbin-mapping.yaml -``` - -For production use, the general recommended best practice is to store the file in a version control system and apply the changes with a continuous deployment pipeline. For more detail, see [the Ambassador Operating Model](../../concepts/gitops-continuous-delivery). - -## Extending Mappings - -`Mapping` resources support a rich set of annotations to customize the specific routing behavior. Here's an example service for implementing the CQRS pattern (using HTTP): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-get -spec: - prefix: /cqrs/ - method: GET - service: getcqrs ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: cqrs-put -spec: - prefix: /cqrs/ - method: PUT - service: putcqrs -``` - -More detail on each of the available annotations are discussed in subsequent sections. - -## Resources - -To $productName$, a `resource` is a group of one or more URLs that all share a common prefix in the URL path. For example: - -``` -https://ambassador.example.com/resource1/foo -https://ambassador.example.com/resource1/bar -https://ambassador.example.com/resource1/baz/zing -https://ambassador.example.com/resource1/baz/zung -``` - -all share the `/resource1/` path prefix, so it can be considered a single resource. On the other hand: - -``` -https://ambassador.example.com/resource1/foo -https://ambassador.example.com/resource2/bar -https://ambassador.example.com/resource3/baz/zing -https://ambassador.example.com/resource4/baz/zung -``` - -share only the prefix `/` -- you _could_ tell $productName$ to treat them as a single resource, but it's probably not terribly useful. - -Note that the length of the prefix doesn't matter: if you want to use prefixes like `/v1/this/is/my/very/long/resource/name/`, go right ahead, $productName$ can handle it. - -Also note that $productName$ does not actually require the prefix to start and end with `/` -- however, in practice, it's a good idea. Specifying a prefix of - -``` -/man -``` - -would match all of the following: - -``` -https://ambassador.example.com/man/foo -https://ambassador.example.com/mankind -https://ambassador.example.com/man-it-is/really-hot-today -https://ambassador.example.com/manohmanohman -``` - -which is probably not what was intended. - -## Services - -$productName$ routes traffic to a `service`. A `service` is defined as: - -``` -[scheme://]service[.namespace][:port] -``` - -Where everything except for the `service` is optional. - -- `scheme` can be either `http` or `https`; if not present, the default is `http`. -- `service` is the name of a service (typically the service name in Kubernetes or Consul); it is not allowed to contain the `.` character. -- `namespace` is the namespace in which the service is running. Starting with $productName$ 1.0.0, if not supplied, it defaults to the namespace in which the Mapping resource is defined. The default behavior can be configured using the [`ambassador` Module](../../running/ambassador). When using a Consul resolver, `namespace` is not allowed. -- `port` is the port to which a request should be sent. If not specified, it defaults to `80` when the scheme is `http` or `443` when the scheme is `https`. Note that the [resolver](../../running/resolvers) may return a port in which case the `port` setting is ignored. - -Note that while using `service.namespace.svc.cluster.local` may work for Kubernetes resolvers, the preferred syntax is `service.namespace`. - -## Best practices for configuration - -$productName$'s configuration is assembled from multiple YAML blocks which are managed by independent application teams. This implies: - -- $productName$'s configuration should be under version control. - - While you can always read back the $productName$'s configuration from Kubernetes or its diagnostic service, the $productName$ will not do versioning for you. - -- Be aware that the $productName$ tries to not start with a broken configuration, but it's not perfect. - - Gross errors will result in $productName$ refusing to start, in which case `kubectl logs` will be helpful. However, it's always possible to e.g. map a resource to the wrong service, or use the wrong `rewrite` rules. $productName$ can't detect that on its own, although its diagnostic pages can help you figure it out. - -- Be careful of mapping collisions. - - If two different developers try to map `/user/` to something, this can lead to unexpected behavior. $productName$'s canary-deployment logic means that it's more likely that traffic will be split between them than that it will throw an error -- again, the diagnostic service can help you here. - -**Note:** Unless specified, mapping attributes cannot be applied to any other resource type. diff --git a/content/en/docs/pre-release/topics/using/keepalive.md b/content/en/docs/pre-release/topics/using/keepalive.md deleted file mode 100644 index d75e96ba..00000000 --- a/content/en/docs/pre-release/topics/using/keepalive.md +++ /dev/null @@ -1,70 +0,0 @@ -# Keepalive - -Keepalive option indicates whether `SO_KEEPALIVE` on the socket should be enabled. - -## Keepalive configuration - -Keepalive configuration can be set for all $productName$ mappings in the [`ambassador Module`](../../running/ambassador) or set per [`Mapping`](../mappings). - -The `keepalive` attribute configures keepalive. The following fields are supported: - -```yaml -keepalive: - idle_time: - interval: - probes: -``` - -### `idle_time` - -(Default: `7200`) The number of seconds a connection needs to be idle before keep-alive probes start being sent. - -### `interval` - -(Default: `75`) The number of seconds between keep-alive probes. - -### `probes` - -(Default: `9`) is the maximum number of keepalive probes to send without response before deciding the connection is dead. - -## Examples - -Keepalive probes defined on a single mapping: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - keepalive: - idle_time: 100 - interval: 10 - probes: 9 -``` - -A global keepalive configuration: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - keepalive: - idle_time: 100 - interval: 10 - probes: 9 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote -``` diff --git a/content/en/docs/pre-release/topics/using/mappings.md b/content/en/docs/pre-release/topics/using/mappings.md deleted file mode 100644 index f930fc62..00000000 --- a/content/en/docs/pre-release/topics/using/mappings.md +++ /dev/null @@ -1,189 +0,0 @@ -# Advanced Mapping configuration - -$productName$ is designed so that the author of a given Kubernetes service can easily and flexibly configure how traffic gets routed to the service. The core abstraction used to support service authors is a mapping, which maps a target backend service to a given host or prefix. For Layer 7 protocols such as HTTP, gRPC, or WebSockets, the `Mapping` resource is used. For TCP, the `TCPMapping` resource is used. - -$productName$ _must_ have one or more mappings defined to provide access to any services at all. The name of the mapping must be unique. - -## System-wide defaults for Mappings - -Certain aspects of mappings can be set system-wide using the `defaults` element of the `ambassador Module`: -see [using defaults](../../using/defaults) for more information. The `Mapping` element will look first in -the `httpmapping` default class. - -## Mapping evaluation order - -$productName$ sorts mappings such that those that are more highly constrained are evaluated before those less highly constrained. The prefix length, the request method, constraint headers, and query parameters are all taken into account. - -If absolutely necessary, you can manually set a `precedence` on the mapping (see below). In general, you should not need to use this feature unless you're using the `regex_headers` or `host_regex` matching features. If there's any question about how $productName$ is ordering rules, the diagnostic service is a good first place to look: the order in which mappings appear in the diagnostic service is the order in which they are evaluated. - -## Optional fallback Mapping - -$productName$ will respond with a `404 Not Found` to any request for which no mapping exists. If desired, you can define a fallback "catch-all" mapping so all unmatched requests will be sent to an upstream service. - -For example, defining a mapping with only a `/` prefix will catch all requests previously unhandled and forward them to an external service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: catch-all -spec: - prefix: / - service: https://www.getambassador.io -``` - -### Using `precedence` - -$productName$ sorts mappings such that those that are more highly constrained are evaluated before those less highly constrained. The prefix length, the request method, and the constraint headers are all taken into account. These mechanisms, however, may not be sufficient to guarantee the correct ordering when regular expressions or highly complex constraints are in play. - -For those situations, a `Mapping` can explicitly specify the `precedence`. A `Mapping` with no `precedence` is assumed to have a `precedence` of 0; the higher the `precedence` value, the earlier the `Mapping` is attempted. - -If multiple `Mapping`s have the same `precedence`, $productName$'s normal sorting determines the ordering within the `precedence`; however, there is no way that $productName$ can ever sort a `Mapping` with a lower `precedence` ahead of one at a higher `precedence`. - -### Using `tls` - -To originate TLS, use a `service` with an `https://` prefix. By itself, this will cause $productName$ to originate TLS without presenting a client certificate to the upstream service: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-no-cert -spec: - prefix: /prefix/ - service: https://upstream/ -``` - -If you do need to supply a client certificate, you will also need to set `tls` to the name of a defined TLS context. The client certificate given in that context will be presented to the upstream service. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: mapping-with-cert -spec: - prefix: /prefix/ - service: https://upstream/ - tls: upstream-cert-context -``` - -(If `tls` is present, $productName$ will originate TLS even if the `service` does not have an `https://` prefix.) - -### Using `cluster_tag` - -If the `cluster_tag` attribute is present, its value will be prepended to cluster names generated from -the `Mapping`. This provides a simple mechanism for customizing the `cluster` name when working with metrics. - -## Using `dns_type` - -If the `dns_type` attribute is present, its value will determine how the DNS is used when locating the upstream service. Valid values are: - -- `strict_dns` (the default): The DNS result is assumed to define the exact membership of the cluster. For example, if DNS returns three IP addresses, the cluster is assumed to have three distinct upstream hosts. If a successful DNS query returns no hosts, the cluster is assumed to be empty. `strict_dns` makes sense for situations like a Kubernetes service, where DNS resolution is fast and returns a relatively small number of IP addresses. - -- `logical_dns`: Instead of assuming that the DNS result defines the full membership of the cluster, every new connection simply uses the first IP address returned by DNS. `logical_dns` makes sense for a service with a large number of IP addresses using round-robin DNS for upstream load balancing: typically each DNS query returns a different first result, and it is not necessarily possible to know the full membership of the cluster. With `logical_dns`, no attempt is made to garbage-collect connections: they will stay open until the upstream closes them. - -If `dns_type` is not given, `strict_dns` is the default, as this is the most conservative choice. When interacting with large web services with many IP addresses, switching to `logical_dns` may be a better choice. For more on the different types of DNS, see the [`strict_dns` Envoy documentation] or the [`logical_dns` Envoy documentation]. - -[`strict_dns` Envoy documentation]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/service_discovery#strict-dns -[`logical_dns` Envoy documentation]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/service_discovery#logical-dns - - -## Namespaces and Mappings - -If `AMBASSADOR_NAMESPACE` is correctly set, $productName$ can map to services in other namespaces by taking advantage of Kubernetes DNS: - -- `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. - -### Linkerd interoperability (`add_linkerd_headers`) - -When using Linkerd, requests going to an upstream service need to include the `l5d-dst-override` header to ensure that Linkerd will route them correctly. Setting `add_linkerd_headers` does this automatically, based on the `service` attribute in the `Mapping`. - -If `add_linkerd_headers` is not specified for a given `Mapping`, the default is taken from the `ambassador`[Module](../../running/ambassador). The overall default is `false`: you must explicitly enable `add_linkerd_headers` for $productName$ to add the header for you (although you can always add it yourself with `add_request_headers`, of course). - -### "Upgrading" to non-HTTP protocols (`allow_upgrade`) - -HTTP has [a mechanism][upgrade-mechanism] where the client can say -`Connection: upgrade` / `Upgrade: PROTOCOL` to switch ("upgrade") from -the current HTTP version to a different one, or even a different -protocol entirely. $productName$ itself understands and can handle the -different HTTP versions, but for other protocols you need to tell -$productName$ to get out of the way, and let the client speak that -protocol directly with your upstream service. You can do this by -setting the `allow_upgrade` field to a case-insensitive list of -protocol names $productName$ will allow switching to from HTTP. After -the upgrade, $productName$ does not interpret the traffic, and behaves -similarly to how it does for `TCPMapping`s. - -[upgrade-mechanism]: https://tools.ietf.org/html/rfc7230#section-6.7 - -This "upgrade" mechanism is a useful way of adding HTTP-based -authentication and access control to another protocol that might not -support authentication; for this reason the designers of the WebSocket -protocol made this "upgrade" mechanism the *only* way of initiating a -WebSocket connection. In a Mapping for an upstream service that -supports WebSockets, you would write - -```yaml -allow_upgrade: -- websocket -``` - -The Kubernetes apiserver itself uses this "upgrade" mechanism to -perform HTTP authentication before switching to SPDY for endpoint used -by `kubectl exec`; if you wanted to use $productName$ to expose the -Kubernetes apiserver such that `kubectl exec` functions, you would -write - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: apiserver -spec: - hostname: "*" - service: https://kubernetes.default - prefix: / - allow_upgrade: - - spdy/3.1 -``` - -There is a deprecated setting `use_websocket`; setting `use_websocket: -true` is equivalent to setting `allow_upgrade: ["websocket"]`. - -## DNS configuration for Mappings - -`respect_dns_ttl` can be set to `true` to force the DNS refresh rate for this `Mapping` to be set to the record’s TTL obtained from DNS resolution. -- Allowed values: `true` or `false` -- Default: `false` - - -`dns_type` can be used to configure the service discovery type between Strict DNS and Logical DNS. You can -- Allowed values: - - `strict_dns`: Ambassador will continuously and asynchronously resolve the specified DNS targets. - - `logical_dns`: Similar to `strict_dns`, but only uses the first IP address returned when a new connection needs to be initiated and Connections are never drained. More optimal for large scale web services that must be accessed via DNS. -- Default: `strict_dns` - - -For more information on the differences between dns types, see [the Envoy documentation for service discovery](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/service_discovery.html). - -> **Note:** When the [endpoint resolver](../../running/resolvers/#the-kubernetes-endpoint-resolver) is used in a `Mapping`, `dns_type` will be ignored in favor of the endpoint resolver's service discovery. - - - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: dnsoverwrite -spec: - service: quote - prefix: /backend/ - dns_type: logical_dns - respect_dns_ttl: true -``` diff --git a/content/en/docs/pre-release/topics/using/method.md b/content/en/docs/pre-release/topics/using/method.md deleted file mode 100644 index 94185dcd..00000000 --- a/content/en/docs/pre-release/topics/using/method.md +++ /dev/null @@ -1,26 +0,0 @@ -# Method-based routing - -$productName$ supports routing based on the HTTP method and regular expression. - -## Using `method` - -The `method` annotation specifies the specific HTTP method for a mapping. The value of the `method` annotation must be in all upper case. - -For example: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: get -spec: - hostname: "*" - prefix: /backend/get_only/ - method: GET - service: quote -``` - -## Using `method_regex` - -When `method_regex` is set to `true`, the value of the `method` annotation will be interpreted as a regular expression. diff --git a/content/en/docs/pre-release/topics/using/prefix-regex.md b/content/en/docs/pre-release/topics/using/prefix-regex.md deleted file mode 100644 index 04a6e4b8..00000000 --- a/content/en/docs/pre-release/topics/using/prefix-regex.md +++ /dev/null @@ -1,25 +0,0 @@ -# Prefix regex - -## Using `prefix` and `prefix_regex` - -When the `prefix_regex` attribute is set to `true`, $productName$ configures a [regex route](https://www.envoyproxy.io/docs/envoy/v1.5.0/api-v1/route_config/route#route) instead of a prefix route in Envoy. **This means the entire path must match the regex specified, not only the prefix.** - -## Example with a version in the URL - -If the version is a path parameter and the resources are served by different services, then - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: qotm -spec: - prefix: "/(v1|v2)/qotm/.*" - prefix_regex: true - service: qotm -``` - -will map requests to both `/v1` and `/v2` to the `qotm` service. - -Note that enclosing regular expressions in quotes can be important to prevent backslashes from being doubled. diff --git a/content/en/docs/pre-release/topics/using/query-parameters.md b/content/en/docs/pre-release/topics/using/query-parameters.md deleted file mode 100644 index 0bd5eb13..00000000 --- a/content/en/docs/pre-release/topics/using/query-parameters.md +++ /dev/null @@ -1,70 +0,0 @@ -# Query parameter-based routing - -$productName$ can route to target services based on HTTP query parameters with the `query_parameters` and `regex_query_parameters` specifications. Multiple mappings with different annotations can be applied to construct more complex routing rules. - -## The `query_parameters` annotation - -The `query_parameters` attribute is a dictionary of `query_parameter`: `value` pairs. $productName$ will only allow requests that match the specified `query_parameter`: `value` pairs to reach the target service. - -You can also set the `value` of a query parameter to `true` to test for the existence of a query parameter. - -### A basic example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - query_parameters: - quote-mode: backend - random-query-parameter: datawire -``` - -This will allow requests to /backend/ to succeed only if the `quote-mode` query parameter has the value `backend` and the `random-query-parameter` has the value `datawire`. - -### A conditional example - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-mode -spec: - prefix: /backend/ - service: quote-mode - query_parameters: - quote-mode: true - ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-regular -spec: - prefix: /backend/ - service: quote-regular -``` - -This will send requests that contain the `quote-mode` query parameter to the `quote-mode` target, while routing all other requests to the `quote-regular` target. - -## `regex_query_parameters` - -The following mapping will route requests with the `quote-mode` header that contain values that match the regex. - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - regex_query_parameters: - quote-mode: "^[a-z].*" - prefix: /backend/ - service: quote -``` diff --git a/content/en/docs/pre-release/topics/using/rate-limits/index.md b/content/en/docs/pre-release/topics/using/rate-limits/index.md deleted file mode 100644 index b65f8c5d..00000000 --- a/content/en/docs/pre-release/topics/using/rate-limits/index.md +++ /dev/null @@ -1,199 +0,0 @@ -import Alert from '@material-ui/lab/Alert'; - -# Basic rate limiting - -Rate limiting in $productName$ is composed of two parts: - -* The [`RateLimitService`](../../running/services/rate-limit-service) resource tells $productName$ what external service - to use for rate limiting. - - If $productName$ cannot contact the rate limit service, it will allow the request to be processed as if there were no rate limit service configuration. - -* _Labels_ that get attached to requests. A label is basic metadata that - is used by the `RateLimitService` to decide which limits to apply to - the request. - - - These labels require Mapping resources with apiVersion - getambassador.io/v2 or newer — if you're updating an old installation, check the - apiVersion! - - -Labels are grouped according to _domain_ and _group_: - -```yaml -labels: - "domain1": - - "group1": - - "my_label_specifier_1" - - "my_label_specifier_2" - - "group2": - - "my_label_specifier_3" - - "my_label_specifier_4" - "domain2": - - ... -``` - -The names of domains and groups are not interpreted by $productName$ in any way: -they are solely there to help configuration authors remember the different groupings. -Note that **at present, rate limiting supports just one domain**: the name of the -domain must be configured in the [`RateLimitService`](../../running/services/rate-limit-service). - - - -## Attaching labels to requests - -There are two ways of setting labels on a request: - -1. You can set labels on an individual [`Mapping`](../mappings). These labels - will only apply to requests that use that `Mapping`. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Mapping - metadata: - name: foo-mapping - spec: - hostname: "*" - prefix: /foo/ - service: foo - labels: - "domain1": - - "group1": - - "my_label_specifier_1" - - "my_label_specifier_2" - - "group2": - - "my_label_specifier_3" - - "my_label_specifier_4" - "domain2": - - ... - ``` - -2. You can set global labels in the [`ambassador` `Module`](../../running/ambassador). - These labels will apply to _every_ request that goes through $productName$. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Module - metadata: - name: ambassador - spec: - config: - default_labels: - "domain1": - defaults: - - "my_label_specifier_a" - - "my_label_specifier_b" - "domain2": - defaults: - - "my_label_specifier_c" - - "my_label_specifier_d" - ``` - - If a `Mapping` and the defaults both give label groups for the same domain, the - default labels are prepended to each label group from the `Mapping`. If the `Mapping` - does not give any labels for that domain, the global labels are placed into a new - label group named "default" for that domain. - -Each label group is a list of labels; each label is a key/value pair. Since the label -group is a list rather than a map: -- it is possible to have multiple labels with the same key, and -- the order of labels matters. - -> Note: The terminology used by the Envoy documentation differs from -> the terminology used by $productName$: -> -> | $productName$ | Envoy | -> |-----------------|-------------------| -> | label group | descriptor | -> | label | descriptor entry | -> | label specifier | rate limit action | - -The `Mapping`s' listing of the groups of specifiers have names for the -groups; the group names are useful for humans dealing with the YAML, -but are ignored by $productName$, all $productName$ cares about are the -*contents* of the groupings of label specifiers. - -There are 5 types of label specifiers in $productName$: - - - -1. `source_cluster` - - ```yaml - source_cluster: - key: source_cluster - ``` - - Sets the label `source_cluster=«Envoy source cluster name»"`. The Envoy - source cluster name is the name of the Envoy cluster that the request came - in on. - - The syntax of this label currently _requires_ `source_cluster: {}`. - -2. `destination_cluster` - - ```yaml - destination_cluster: - key: destination_cluster - ``` - - Sets the label `destination_cluster=«Envoy destination cluster name»"`. The Envoy - destination cluster name is the name of the Envoy cluster to which the `Mapping` - routes the request. You can get the name for a cluster from the - [diagnostics service](../../running/diagnostics). - - The syntax of this label currently _requires_ `destination_cluster: {}`. - -3. `remote_address` - - ```yaml - remote_address: - key: remote_address - ``` - - Sets the label `remote_address=«IP address of the client»"`. The IP address of - the client will be taken from the `X-Forwarded-For` header, to correctly manage - situations with L7 proxies. This requires that $productName$ be correctly - [configured to communicate](../../../howtos/configure-communications). - - The syntax of this label currently _requires_ `remote_address: {}`. - -4. `request_headers` - - ```yaml - request_headers: - header_name: "header-name" - key: mykey - ``` - - If a header named `header-name` is present, set the label `mykey=«value of the header»`. - If no header named `header-name` is present, **the entire label group is dropped**. - -5. `generic_key` - - ```yaml - generic_key: - key: mykey - value: myvalue - ``` - - Sets the label `«mykey»=«myval»`. Note that supplying a `key` is supported only - with the Envoy V3 API. - -## Rate limiting requests based on their labels - -This is determined by your `RateLimitService` implementation. See the -[Basic Rate Limiting tutorial](../../../howtos/rate-limiting-tutorial) for an -example `RateLimitService` implementation for $productName$. - -If you'd rather not write your own `RateLimitService` implementation, -$AESproductName$ provides a `RateLimitService` implementation that is -configured by a `RateLimit` custom resource. See the -[$AESproductName$ RateLimit Reference](/docs/edge-stack/latest/topics/using/rate-limits/rate-limits/) -for more information. diff --git a/content/en/docs/pre-release/topics/using/redirects.md b/content/en/docs/pre-release/topics/using/redirects.md deleted file mode 100644 index f55c467d..00000000 --- a/content/en/docs/pre-release/topics/using/redirects.md +++ /dev/null @@ -1,142 +0,0 @@ -# Redirects - -$productName$ can perform 3xx redirects on `Mapping`s to a different host, with various options to redirect the path and to return a different 3xx response code instead of the default 301. - -## Schema - -| Name | Type | Description | -| --- | --- | --- | -| `spec.host_redirect` | Boolean | This is *required* to be set to `true` to use any type of redirect, otherwise the request will be proxied instead of redirected. | -| `spec.path_redirect` | String | Optional, changes the path for the redirect. | -| `spec.prefix_redirect` | String | Optional, matches the `prefix` value and replaces it with the `prefix_redirect` value. | -| `spec.regex_redirect` | String | Optional, uses regex to match and replace the `prefix` value. | -| `spec.redirect_response_code` | Integer | Optional, changes the response code from the default 301, valid values are 301, 302, 303, 307, and 308. | -| `spec.config. x_forwarded_proto_redirect` | Boolean | Redirect only the originating HTTP requests to HTTPS, allowing the originating HTTPS requests to pass through. | -| `spec.config. use_remote_address` | Boolean | Required to be set to `false` to use the `x_forwarded_proto_redirect` feature. | - -## Examples - -### Basic redirect - -To effect any type of HTTP `Redirect`, the `Mapping` *must* set `host_redirect` to `true`, with `service` set to the host to which the client should be redirected: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - prefix: /redirect/ - service: httpbin.org - host_redirect: true - hostname: '*' -``` - -Using this `Mapping`, a request to `http://$AMBASSADOR_URL/redirect/` will be redirected to `http://httpbin.org/redirect/`. - -> As always with $productName$, the trailing `/` on any URL with a -`Mapping` is required! - -### Path redirect - -The `Mapping` may optionally also set additional properties to customize the behavior of the HTTP redirect response. - -To also change the path portion of the URL during the redirect, set `path_redirect`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - hostname: '*' - prefix: /redirect/ - service: httpbin.org - host_redirect: true - path_redirect: /ip -``` - -Here, a request to `http://$AMBASSADOR_URL/redirect/` will be redirected to `http://httpbin.org/ip/`. - -### Prefix redirect - -To change only a prefix of the path portion of the URL, set `prefix_redirect`: - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - hostname: '*' - prefix: /redirect/path/ - service: httpbin.org - host_redirect: true - prefix_redirect: /ip -``` - -Now, a request to `http://$AMBASSADOR_URL/redirect/path/` will be redirected to `http://httpbin.org/ip/`. The prefix `/redirect/path/` was matched and replaced with `/ip/`. - -### Regex redirect - -`regex_redirect` matches a regular expression to replace instead of a fixed prefix. -[See more information about using regex with $productName$](../rewrites/#regex_rewrite). - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - prefix: /foo/ - service: httpbin.org - host_redirect: true - regex_redirect: - pattern: '/foo/([0-9]*)/list' - substitution: '/bar/\1' -``` -A request to `http://$AMBASSADOR_URL/foo/12345/list` will be redirected to -`http://$AMBASSADOR_URL/bar/12345`. - -### Redirect response code - -To change the HTTP response code return by $productName$, set `redirect_reponse_code`. If this is not set, 301 is returned by default. Valid values include 301, 302, 303, 307, and 308. This -can be used with any type of redirect. - -```yaml -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: redirect -spec: - prefix: /ip/ - service: httpbin.org - host_redirect: true - redirect_response_code: 302 -``` - -A request to `http://$AMBASSADOR_URL/ip/` will result in an HTTP 302 redirect to `http://httpbin.org/ip`. - -### X-FORWARDED-PROTO redirect - -In cases when TLS is being terminated at an external layer 7 load balancer, then you would want to redirect only the originating HTTP requests to HTTPS, and let the originating HTTPS requests pass through. - -This distinction between an originating HTTP request and an originating HTTPS request is done based on the `X-FORWARDED-PROTO` header that the external layer 7 load balancer adds to every request it forwards after TLS termination. - -To enable this `X-FORWARDED-PROTO` based HTTP to HTTPS redirection, add a `x_forwarded_proto_redirect: true` field to `ambassador Module`'s configuration. Note that when this feature is enabled `use_remote_address` MUST be set to false. - -An example configuration is as follows - - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - x_forwarded_proto_redirect: true - use_remote_address: false -``` - -Note: Setting `x_forwarded_proto_redirect: true` will impact all your $productName$ mappings. Every HTTP request to $productName$ will only be allowed to pass if it has an `X-FORWARDED-PROTO: https` header. diff --git a/content/en/docs/pre-release/topics/using/retries.md b/content/en/docs/pre-release/topics/using/retries.md deleted file mode 100644 index d018ab59..00000000 --- a/content/en/docs/pre-release/topics/using/retries.md +++ /dev/null @@ -1,84 +0,0 @@ -# Automatic retries - -Sometimes requests fail. When these requests fail for transient issues, $productName$ can automatically retry the request. - -Retry policy can be set for all $productName$ mappings in the [`ambassador Module`](../../running/ambassador), or set per [`Mapping`](../mappings). Generally speaking, you should set `retry_policy` on a per mapping basis. Global retries can easily result in unexpected cascade failures. - -> Note that when setting `retry_policy`, adjusting `max_retries` in the [circuit breaker](https://www.getambassador.io/docs/edge-stack/pre-release/topics/using/circuit-breakers/) configuration should also be considered in order to account for all desired retries. - -## Configuring retries - -The `retry_policy` attribute configures automatic retries. The following fields are supported: - -```yaml -retry_policy: - retry_on: - num_retries: - per_try_timeout: -``` - -### `retry_on` - -(Required) Specifies the condition under which $productName$ retries a failed request. - -| Value | Description | -| --- | --- | -|`5xx`| Retries if the upstream service responds with any 5xx code or does not respond at all -|`gateway-error`| Similar to a `5xx` but only applies to a 502, 503, or 504 response -|`connect-failure`| Retries on a connection failure to the upstream service (included in `5xx`) -|`retriable-4xx`| Retries on a retriable 4xx response (currently only 409) -|`refused-stream`| Retires if the upstream service sends a REFUSED_STREAM error (included in `5xx`) -|`retriable-status-codes`| Retries based on status codes set in the `x-envoy-retriable-status-codes` header. If that header isn't set, $productName$ will not retry the request. - - For more details on each of these values, see the [Envoy documentation](https://www.envoyproxy.io/docs/envoy/v1.9.0/configuration/http_filters/router_filter#x-envoy-retry-on). - -### `num_retries` - -(Default: 1) Specifies the number of retries to execute for a failed request. - -### `per_try_timeout` - -(Default: global request timeout) Specify the timeout for each retry. Must be in seconds or nanoseconds, e.g., `1s`, `1500ns`. - -## Examples - -A per mapping retry policy: - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - hostname: '*' - prefix: /backend/ - service: quote - retry_policy: - retry_on: "5xx" - num_retries: 10 -``` - -A global retry policy (not recommended): - -```yaml ---- -apiVersion: getambassador.io/v3alpha1 -kind: Module -metadata: - name: ambassador -spec: - config: - retry_policy: - retry_on: "retriable-4xx" - num_retries: 4 ---- -apiVersion: getambassador.io/v3alpha1 -kind: Mapping -metadata: - name: quote-backend -spec: - prefix: /backend/ - service: quote - hostname: '*' -``` diff --git a/content/en/docs/pre-release/topics/using/rewrites.md b/content/en/docs/pre-release/topics/using/rewrites.md deleted file mode 100644 index 44d0a961..00000000 --- a/content/en/docs/pre-release/topics/using/rewrites.md +++ /dev/null @@ -1,100 +0,0 @@ -# Rewrites - -Once $productName$ uses a prefix to identify the service to which a given request should be passed, it can rewrite the URL before handing it off to the service. - -There are two approaches for rewriting: `rewrite` for simpler scenarios and `regex_rewrite` for more advanced rewriting. - -**Please note that** only one of these two can be configured for a mapping **at the same time**. As a result $productName$ ignores `rewrite` when `regex_rewrite` is provided. - -## `rewrite` - -By default, the `prefix` is rewritten to `/`, so e.g., if we map `/backend-api/` to the service `service1`, then - - -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/content/en/docs/pre-release/topics/using/shadowing.md b/content/en/docs/pre-release/topics/using/shadowing.md deleted file mode 100644 index dd95fbba..00000000 --- a/content/en/docs/pre-release/topics/using/shadowing.md +++ /dev/null @@ -1,78 +0,0 @@ -# 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. - -![Shadowing](../../images/shadowing.png) - -## 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/content/en/docs/pre-release/topics/using/tcpmappings.md b/content/en/docs/pre-release/topics/using/tcpmappings.md deleted file mode 100644 index f246e799..00000000 --- a/content/en/docs/pre-release/topics/using/tcpmappings.md +++ /dev/null @@ -1,300 +0,0 @@ -# `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/content/en/docs/pre-release/topics/using/timeouts.md b/content/en/docs/pre-release/topics/using/timeouts.md deleted file mode 100644 index ae004102..00000000 --- a/content/en/docs/pre-release/topics/using/timeouts.md +++ /dev/null @@ -1,66 +0,0 @@ -# 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/content/en/docs/pre-release/tutorials/dev-portal-tutorial.md b/content/en/docs/pre-release/tutorials/dev-portal-tutorial.md deleted file mode 100644 index d3c0d0a8..00000000 --- a/content/en/docs/pre-release/tutorials/dev-portal-tutorial.md +++ /dev/null @@ -1,29 +0,0 @@ -# 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:///docs/` to see the -publicly visible Developer Portal. Make sure you include the trailing `/`. -This is a fully customizable portal that you can share with third parties who -need information about your APIs. diff --git a/content/en/docs/pre-release/tutorials/getting-started.md b/content/en/docs/pre-release/tutorials/getting-started.md deleted file mode 100644 index 1fb11cec..00000000 --- a/content/en/docs/pre-release/tutorials/getting-started.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: "Getting Started with $productName$" -description: "Learn how to install $productName$ with either Helm or kubectl to get started routing traffic from the edge of your Kubernetes cluster to your services..." ---- - -import Alert from '@material-ui/lab/Alert'; -import GettingStartedEmissary21Tabs from './gs-tabs' - -# $productName$ quick start - -
-

Contents

- -- [1. Installation](#1-installation) - - [Connecting your installation to Ambassador Cloud](#connecting-your-installation-to-ambassador-cloud) -- [2. Routing traffic from the edge](#2-routing-traffic-from-the-edge) -- [What's next?](#img-classos-logo-srcimageslogopng-whats-next) - -
- -## 1. Installation - -We'll start by installing $productName$ into your cluster. - -**We recommend using Helm** but there are other options below to choose from. - - - -### Connecting your installation to Ambassador Cloud - -Now is a great moment to connect your new installation to Ambassador Cloud in order to fully leverage the power of $productName$ and the Developer Control Plane (DCP). - -1. Log in to [Ambassador Cloud](https://app.getambassador.io/cloud/services/) with GitHub, GitLab or Google and select your team account. - -2. At the top, click **Add Services** then click **Connection Instructions** in the "Connect your installation" section. - -3. Follow the prompts to name the cluster and click **Generate a Cloud Token**. - -4. Follow the prompts to install the cloud token into your cluster. - -5. When the token installation completes, your services will be listed in the DCP. - -Success! At this point, you have installed $productName$. Now let's get some traffic flowing to your services. - -## 2. Routing traffic from the edge - -$productName$ uses Kubernetes Custom Resource Definitions (CRDs) to declaratively define its desired state. The workflow you are going to build uses a simple demo app, a **`Listener` CRD**, and a **`Mapping` CRD**. The `Listener` CRD tells $productName$ what port to listen on, and the `Mapping` CRD tells $productName$ how to route incoming requests by host and URL path from the edge of your cluster to Kubernetes services. - -1. Start by creating a `Listener` resource for HTTP on port 8080: - - ``` - kubectl apply -f - < - This 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.
-
- Learn more about Listener.
- Learn more about Host. - - -2. Apply the YAML for the "Quote" service. - - ``` - kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/quickstart/qotm.yaml - ``` - - The Service and Deployment are created in your default namespace. You can use 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](#connecting-your-installation-to-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` - - ![](../images/mapping-editor.png) - - 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 - <Victory! You have created your first $productName$ 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/content/en/docs/pre-release/tutorials/gs-tabs.js b/content/en/docs/pre-release/tutorials/gs-tabs.js deleted file mode 100644 index e9b2ad7b..00000000 --- a/content/en/docs/pre-release/tutorials/gs-tabs.js +++ /dev/null @@ -1,134 +0,0 @@ -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 ( - - ); -} - -TabPanel.propTypes = { - children: PropTypes.node, - index: PropTypes.any.isRequired, - value: PropTypes.any.isRequired, -}; - -function a11yProps(index) { - return { - id: `simple-tab-${index}`, - 'aria-controls': `simple-tabpanel-${index}`, - }; -} - -const useStyles = makeStyles((theme) => ({ - root: { - flexGrow: 1, - backgroundColor: 'transparent', - }, -})); - -export default function GettingStartedEmissary21Tabs(props) { - const version = props.version; - const classes = useStyles(); - const [value, setValue] = React.useState(0); - - const handleChange = (event, newValue) => { - setValue(newValue); - }; - - return ( -
- - - } - label="Helm 3" - {...a11yProps(0)} - style={{ minWidth: '10%', textTransform: 'none' }} - /> - } - label="Kubernetes YAML" - {...a11yProps(1)} - style={{ minWidth: '10%', textTransform: 'none' }} - /> - - - - {/*Helm 3 install instructions*/} - - - {'# Add the Repo:' + - '\n' + - 'helm repo add datawire https://app.getambassador.io' + - '\n' + - 'helm repo update' + - '\n \n' + - '# Create Namespace and Install:' + - '\n' + - 'kubectl create namespace emissary && \\' + - '\n' + - `kubectl apply -f https://app.getambassador.io/yaml/emissary/${version}/emissary-crds.yaml` + - '\n \n' + - 'kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system' + - '\n \n' + - 'helm install emissary-ingress --namespace emissary datawire/emissary-ingress && \\' + - '\n' + - 'kubectl -n emissary wait --for condition=available --timeout=90s deploy -lapp.kubernetes.io/instance=emissary-ingress' + - '\n'} - - - - - {/*YAML install instructions*/} - - - {'kubectl create namespace emissary && \\' + - '\n' + - `kubectl apply -f https://app.getambassador.io/yaml/emissary/${version}/emissary-crds.yaml && \\` + - '\n' + - 'kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system' + - '\n \n' + - `kubectl apply -f https://app.getambassador.io/yaml/emissary/${version}/emissary-emissaryns.yaml && \\` + - '\n' + - 'kubectl -n emissary wait --for condition=available --timeout=90s deploy -lproduct=aes' + - '\n'} - - - -
- ); -} diff --git a/content/en/docs/pre-release/tutorials/gs-tabs2.js b/content/en/docs/pre-release/tutorials/gs-tabs2.js deleted file mode 100644 index bfd95047..00000000 --- a/content/en/docs/pre-release/tutorials/gs-tabs2.js +++ /dev/null @@ -1,174 +0,0 @@ -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'; - -function TabPanel(props) { - const { children, value, index, ...other } = props; - - return ( - - ); -} - -TabPanel.propTypes = { - children: PropTypes.node, - index: PropTypes.any.isRequired, - value: PropTypes.any.isRequired, -}; - -function a11yProps(index) { - return { - id: `simple-tab-${index}`, - 'aria-controls': `simple-tabpanel-${index}`, - }; -} - -const useStyles = makeStyles((theme) => ({ - root: { - flexGrow: 1, - backgroundColor: 'transparent', - }, -})); - -export default function SimpleTabs() { - const classes = useStyles(); - const [value, setValue] = React.useState(0); - - const handleChange = (event, newValue) => { - setValue(newValue); - }; - - return ( -
- - - - - - - - - - {/*Helm 3 token install instructions*/} - Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Helm. The slideout contains instructions with a - unique cloud-connect-token that is used to connect your - cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'helm upgrade ambassador --namespace ambassador datawire/ambassador \\' + - '\n' + - ' --set agent.cloudConnectToken=$TOKEN && \\' + - '\n' + - 'kubectl -n ambassador wait --for condition=available --timeout=90s deploy -lproduct=aes'} - - - - - {/*Helm 2 token install instructions*/} - Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Helm. The slideout contains instructions with a - unique cloud-connect-token that is used to connect your - cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'helm upgrade --namespace ambassador ambassador datawire/ambassador \\' + - '\n' + - ' --set crds.create=false --set agent.cloudConnectToken=$TOKEN && \\' + - '\n' + - 'kubectl -n ambassador wait --for condition=available --timeout=90s deploy -lproduct=aes'} - - - - - {/*YAML token install instructions*/} - Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Kubernetes YAML. The slideout contains instructions - with a unique cloud-connect-token that is used to connect - your cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'kubectl create configmap -n ambassador ambassador-agent-cloud-token \\' + - '\n' + - ' --from-literal=CLOUD_CONNECT_TOKEN=$TOKEN'} - - - - - {/*edgectl token install instructions*/} - Connecting $productName$ that was installed via edgectl is - identical to the Kubernetes YAML procedure. -
- Log in to{' '} - Ambassador Cloud. - Click Connect my cluster to Ambassador Cloud, then{' '} - Connect via Kubernetes YAML. The slideout contains instructions - with a unique cloud-connect-token that is used to connect - your cluster to your Ambassador Cloud account. -
- Run the following command, replacing $TOKEN - with your token: - - {'kubectl create configmap -n ambassador ambassador-agent-cloud-token \\' + - '\n' + - ' --from-literal=CLOUD_CONNECT_TOKEN=$TOKEN'} - - -
- ); -} diff --git a/content/en/docs/pre-release/tutorials/quickstart-demo.md b/content/en/docs/pre-release/tutorials/quickstart-demo.md deleted file mode 100644 index 70cbce8b..00000000 --- a/content/en/docs/pre-release/tutorials/quickstart-demo.md +++ /dev/null @@ -1,176 +0,0 @@ -# $productName$ Tutorial - -In this article, you will explore some of the key features of $productName$ by walking through an example workflow and exploring the -Edge Policy Console. - -## Prerequisites - -You must have [$productName$ installed](../getting-started/) in your -Kubernetes cluster. - -## Routing Traffic from the Edge - -Like any other Kubernetes object, Custom Resource Definitions (CRDs) are used to -declaratively define $productName$’s desired state. The workflow you are going to -build uses a sample deployment and the `Mapping` CRD, which is the core resource -that you will use with $productName$ to manage your edge. It enables you to route -requests by host and URL path from the edge of your cluster to Kubernetes services. - -1. Copy the configuration below and save it to a file named `quote.yaml` so that -you can deploy these resources to your cluster. This basic configuration creates -the `quote` deployment and a service to expose that deployment on port 80. - - ```yaml - --- - apiVersion: apps/v1 - kind: Deployment - metadata: - name: quote - namespace: ambassador - spec: - replicas: 1 - selector: - matchLabels: - app: quote - strategy: - type: RollingUpdate - template: - metadata: - labels: - app: quote - spec: - containers: - - name: backend - image: docker.io/datawire/quote:$quoteVersion$ - ports: - - name: http - containerPort: 8080 - --- - apiVersion: v1 - kind: Service - metadata: - name: quote - namespace: ambassador - spec: - ports: - - name: http - port: 80 - targetPort: 8080 - selector: - app: quote - ``` - -1. Apply the configuration to the cluster with the command `kubectl apply -f quote.yaml`. - -1. Copy the configuration below and save it to a file called `quote-backend.yaml` -so that you can create a `Mapping` on your cluster. This `Mapping` tells $productName$ to route all traffic inbound to the `/backend/` path, on any host that can be used to reach $productName$, to the `quote` service. - - ```yaml - --- - apiVersion: getambassador.io/v3alpha1 - kind: Mapping - metadata: - name: quote-backend - namespace: ambassador - spec: - hostname: "*" - prefix: /backend/ - service: quote - ``` - -1. Apply the configuration to the cluster with the command -`kubectl apply -f quote-backend.yaml` - -1. Store the $productName$ `LoadBalancer` address to a local environment variable. -You will use this variable to test accessing your pod. - - ``` - export AMBASSADOR_LB_ENDPOINT=$(kubectl -n ambassador get svc ambassador -o "go-template={{range .status.loadBalancer.ingress}}{{or .ip .hostname}}{{end}}") - ``` - -1. Test the configuration by accessing the service through the $productName$ load -balancer. - - ``` - $ curl -Lk "https://$AMBASSADOR_LB_ENDPOINT/backend/" - { - "server": "idle-cranberry-8tbb6iks", - "quote": "Non-locality is the driver of truth. By summoning, we vibrate.", - "time": "2019-12-11T20:10:16.525471212Z" - } - ``` - -Success, you have created your first $productName$ `Mapping`, routing a -request from your cluster's edge to a service! - -Since the `Mapping` you just created controls how requests are routed, -changing the `Mapping` will immediately change the routing. To see this -in action, use `kubectl` to edit the `Mapping`: - -1. Run `kubectl edit Mapping quote-backend`. - -1. Change `prefix: /backend/` to `prefix: /quoteme/`. - -1. Save the file and let `kubectl` update your `Mapping`. - -1. Run `kubectl get Mappings --namespace ambassador`. You will see the -`quote-backend` `Mapping` has the updated prefix listed. Try to access the -endpoint again via `curl` with the updated prefix. - - ``` - $ kubectl get Mappings --namespace ambassador - NAME PREFIX SERVICE STATE REASON - quote-backend /quoteme/ quote - - $ curl -Lk "https://${AMBASSADOR_LB_ENDPOINT}/quoteme/" - { - "server": "snippy-apple-ci10n7qe", - "quote": "A principal idea is omnipresent, much like candy.", - "time": "2020-11-18T17:15:42.095153306Z" - } - ``` - -1. Change the prefix back to `/backend/` so that you can later use the `Mapping` -with other tutorials. - -## 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. In the Edge Policy Console, navigate to the **APIs** tab. You'll see the -OpenAPI documentation there for the "Quote Service API." Click **GET** to -expand out the documentation. - -1. Navigate to `https:///docs/` to see the -publicly visible Developer Portal. Make sure you include the trailing `/`. -This is a fully customizable portal that you can share with third parties who -need information about your APIs. - -## Next Steps - -Further explore some of the concepts you learned about in this article: -* [`Mapping` resource](../../topics/using/intro-mappings/): routes traffic from -the edge of your cluster to a Kubernetes service -* [`Host` resource](../../topics/running/host-crd/): sets the hostname by which -$productName$ will be accessed and secured with TLS certificates -* [Developer Portal](../../tutorials/dev-portal-tutorial/): -publishes an API catalog and OpenAPI documentation - -$productName$ has a comprehensive range of [features](/features/) to -support the requirements of any edge microservice. - -Learn more about [how developers use $productName$](../../topics/using/) to manage -edge policies. - -Learn more about [how site reliability engineers and operators run $productName$](../../topics/running/) -in production environments. - -To learn how $productName$ works, use cases, best practices, and more, check out -the [Quick Start](../getting-started) or read the [$productName$ Story](../../about/why-ambassador). - -For a custom configuration, you can install $productName$ -[manually](../../topics/install/yaml-install). diff --git a/content/en/docs/pre-release/versions.yml b/content/en/docs/pre-release/versions.yml deleted file mode 100644 index ba9c0f48..00000000 --- a/content/en/docs/pre-release/versions.yml +++ /dev/null @@ -1,35 +0,0 @@ -# branch info -branch: release/v3.8 - -# self -version: 3.8.2 -productName: "Emissary-ingress" -productNamePlural: "Emissary-ingresses" -productNamespace: emissary -productDeploymentName: emissary-ingress -productHelmName: emissary-ingress - -# OSS (self) -ossVersion: 3.8.2 -ossDocsVersion: "pre-release" -ossChartVersion: 8.8.2 -OSSproductName: "Emissary-ingress" -OSSproductNamePlural: "Emissary-ingresses" - -# AES (not self) -aesVersion: 3.8.2 -aesDocsVersion: "pre-release" -aesChartVersion: 8.8.2 -AESproductName: "Ambassador Edge Stack" -AESproductNamePlural: "Ambassador Edge Stacks" - -# other products -qotmVersion: 1.7 -quoteVersion: 0.5.0 - -# Most recent version from previous major versions -# This is mostly to ensure that the migration matrix stays up-to-date -versionTwoX: 2.5.1 -chartVersionTwoX: 7.6.1 -versionOneX: 1.14.4 -chartVersionOneX: 6.9.5