diff --git a/content/en/docs/3.6/about/_index.md b/content/en/docs/3.6/about/_index.md new file mode 100644 index 00000000..0ba607e7 --- /dev/null +++ b/content/en/docs/3.6/about/_index.md @@ -0,0 +1,4 @@ +--- +title: "About" +weight: 10 +--- diff --git a/content/en/docs/3.6/about/alternatives.md b/content/en/docs/3.6/about/alternatives.md index bafec087..b3bc2e7d 100644 --- a/content/en/docs/3.6/about/alternatives.md +++ b/content/en/docs/3.6/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/3.6/about/changes-2.x.md b/content/en/docs/3.6/about/changes-2.x.md index 4c412486..84c7e5b8 100644 --- a/content/en/docs/3.6/about/changes-2.x.md +++ b/content/en/docs/3.6/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 $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 +environment variable to "V2"; in Emissary 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. +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.6/about/changes-3.y.md b/content/en/docs/3.6/about/changes-3.y.md index 91105d28..3d4205e2 100644 --- a/content/en/docs/3.6/about/changes-3.y.md +++ b/content/en/docs/3.6/about/changes-3.y.md @@ -1,24 +1,23 @@ -import Alert from '@material-ui/lab/Alert'; +--- +title: Major Changes in Emissary 3.X +--- -Major Changes in $productName$ 3.X -================================== - -The 3.X family introduces a number of changes to ensure $productName$ +The 3.X family introduces a number of changes to ensure Emissary 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. +Emissary 3 is functionally compatible with Emissary 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 +Emissary 3.X has been upgraded from Envoy 1.17.X to Envoy **1.22** which keeps Emissary 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 +# Emissary 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, @@ -40,7 +39,7 @@ This also means some of the v2 runtime bootstrap flags have been removed as well ## 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). +Emissary 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 @@ -48,5 +47,5 @@ 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. +The setting of transport_protocol to v2 is no longer supported within CRDS (AuthService, etc...). An error will now be logged and Emissary 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.6/about/aes-emissary-eol.md b/content/en/docs/3.6/about/emissary-eol.md similarity index 98% rename from content/en/docs/3.6/about/aes-emissary-eol.md rename to content/en/docs/3.6/about/emissary-eol.md index 6afc3142..8a40b4e1 100644 --- a/content/en/docs/3.6/about/aes-emissary-eol.md +++ b/content/en/docs/3.6/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/3.6/about/faq.md b/content/en/docs/3.6/about/faq.md index 513c75c5..67796d55 100644 --- a/content/en/docs/3.6/about/faq.md +++ b/content/en/docs/3.6/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/3.6/about/features-and-benefits.md b/content/en/docs/3.6/about/features-and-benefits.md index a25d7752..c418cd36 100644 --- a/content/en/docs/3.6/about/features-and-benefits.md +++ b/content/en/docs/3.6/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/3.6/about/known-issues.md b/content/en/docs/3.6/about/known-issues.md index 6b89c65a..74cbc459 100644 --- a/content/en/docs/3.6/about/known-issues.md +++ b/content/en/docs/3.6/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/3.6/about/support.md b/content/en/docs/3.6/about/support.md index 11927f95..85d9df15 100644 --- a/content/en/docs/3.6/about/support.md +++ b/content/en/docs/3.6/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/3.6/about/why-ambassador.md b/content/en/docs/3.6/about/why-ambassador.md index 0d343983..d1b0d929 100644 --- a/content/en/docs/3.6/about/why-ambassador.md +++ b/content/en/docs/3.6/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/3.6/community.md b/content/en/docs/3.6/community.md index 2b578891..76373c4d 100644 --- a/content/en/docs/3.6/community.md +++ b/content/en/docs/3.6/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/DevDocumentation/DEVELOPING.md) diff --git a/content/en/docs/3.6/doc-links.yml b/content/en/docs/3.6/doc-links.yml deleted file mode 100644 index 58b81ad9..00000000 --- a/content/en/docs/3.6/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.6/howtos/_index.md b/content/en/docs/3.6/howtos/_index.md new file mode 100644 index 00000000..b4fc2da6 --- /dev/null +++ b/content/en/docs/3.6/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/3.6/howtos/active-health-checking.md b/content/en/docs/3.6/howtos/active-health-checking.md index fb5decdd..62e7bccf 100644 --- a/content/en/docs/3.6/howtos/active-health-checking.md +++ b/content/en/docs/3.6/howtos/active-health-checking.md @@ -1,8 +1,8 @@ -import Alert from '@material-ui/lab/Alert'; - -# Active Health Checking +--- +title: 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. +Emissary 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. diff --git a/content/en/docs/3.6/howtos/basic-auth.md b/content/en/docs/3.6/howtos/basic-auth.md index 70ce27ce..c59cad2f 100644 --- a/content/en/docs/3.6/howtos/basic-auth.md +++ b/content/en/docs/3.6/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/3.6/howtos/cert-manager.md b/content/en/docs/3.6/howtos/cert-manager.md index d742decd..bc9bcbe8 100644 --- a/content/en/docs/3.6/howtos/cert-manager.md +++ b/content/en/docs/3.6/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/3.6/howtos/client-cert-validation.md b/content/en/docs/3.6/howtos/client-cert-validation.md index 10fe639d..7a2ec247 100644 --- a/content/en/docs/3.6/howtos/client-cert-validation.md +++ b/content/en/docs/3.6/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/3.6/howtos/configure-communications.md b/content/en/docs/3.6/howtos/configure-communications.md index 1ac09d2c..eb6462f1 100644 --- a/content/en/docs/3.6/howtos/configure-communications.md +++ b/content/en/docs/3.6/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/3.6/howtos/consul.md b/content/en/docs/3.6/howtos/consul.md index d75e35ce..8da238cc 100644 --- a/content/en/docs/3.6/howtos/consul.md +++ b/content/en/docs/3.6/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. @@ -118,24 +117,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: @@ -169,10 +168,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`. @@ -293,7 +292,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 @@ -319,12 +318,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}}") @@ -349,14 +348,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 @@ -368,7 +367,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 @@ -484,7 +483,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: @@ -512,11 +511,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. @@ -524,7 +523,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 @@ -551,7 +550,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` | @@ -559,6 +558,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/3.6/howtos/dist-tracing.md b/content/en/docs/3.6/howtos/dist-tracing.md index bc40df8f..870214a6 100644 --- a/content/en/docs/3.6/howtos/dist-tracing.md +++ b/content/en/docs/3.6/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/3.6/howtos/external-dns.md b/content/en/docs/3.6/howtos/external-dns.md index f0f51dbb..2a771dd9 100644 --- a/content/en/docs/3.6/howtos/external-dns.md +++ b/content/en/docs/3.6/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/3.6/howtos/filter-dev-guide.md b/content/en/docs/3.6/howtos/filter-dev-guide.md index eefe8b6b..d0413fd6 100644 --- a/content/en/docs/3.6/howtos/filter-dev-guide.md +++ b/content/en/docs/3.6/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/3.6/howtos/grpc.md b/content/en/docs/3.6/howtos/grpc.md index 3967ddf7..ffdc0872 100644 --- a/content/en/docs/3.6/howtos/grpc.md +++ b/content/en/docs/3.6/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/3.6/howtos/http3-aks.md b/content/en/docs/3.6/howtos/http3-aks.md index 2f9be012..63721f77 100644 --- a/content/en/docs/3.6/howtos/http3-aks.md +++ b/content/en/docs/3.6/howtos/http3-aks.md @@ -1,11 +1,9 @@ --- -title: "$productName$ - HTTP/3 support for Azure Kubernetes Service (AKS)" +title: 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. +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 Emissary](../../topics/running/http3) documentation. ## Configuring an external load balancer for AKS diff --git a/content/en/docs/3.6/howtos/http3-eks.md b/content/en/docs/3.6/howtos/http3-eks.md index d09a1af5..e5226ddf 100644 --- a/content/en/docs/3.6/howtos/http3-eks.md +++ b/content/en/docs/3.6/howtos/http3-eks.md @@ -1,11 +1,11 @@ --- -title: "HTTP/3 with Amazon Elastic Kubernetes Service (EKS) | $productName$" +title: "HTTP/3 with Amazon Elastic Kubernetes Service (EKS)" 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. +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 Emissary](../../topics/running/http3) documentation. ## Create a network load balancer (NLB) @@ -20,9 +20,9 @@ This guide shows how to setup HTTP/3 support for Amazon Elastic Kubernetes Servi --subnets ${SUBNET_IDS} ``` -## Create a NodePort service +## 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. +Now create a `NodePort` service for Emissary 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 @@ -73,7 +73,7 @@ Run the following command with the variables for your VPC ID and cluster name: ## Register your instances -Next, register your cluster's instance with the the instance IDs and Amazon Resource Names (ARN). +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 @@ -160,7 +160,7 @@ Enter the following command to get the DNS name for your load balancers and crea ## 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. +Now you need to create the `Listener` resources for Emissary. 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 - < -## 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/3.6/howtos/knative.md b/content/en/docs/3.6/howtos/knative.md index 951aa01f..490a5613 100644 --- a/content/en/docs/3.6/howtos/knative.md +++ b/content/en/docs/3.6/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/3.6/howtos/linkerd2.md b/content/en/docs/3.6/howtos/linkerd2.md index 09352941..aab60d39 100644 --- a/content/en/docs/3.6/howtos/linkerd2.md +++ b/content/en/docs/3.6/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/3.6/howtos/prometheus.md b/content/en/docs/3.6/howtos/prometheus.md index a3faf047..e9c6612a 100644 --- a/content/en/docs/3.6/howtos/prometheus.md +++ b/content/en/docs/3.6/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,23 +9,23 @@ 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. -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 @@ -44,17 +46,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 @@ -130,12 +132,12 @@ 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`. Scrape metrics directly from the `/metrics` endpoint of - $productName$ running in the `ambassador` namespace: + Emissary running in the `ambassador` namespace: ```yaml --- @@ -156,7 +158,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 @@ -170,7 +172,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. @@ -193,7 +195,7 @@ documentation. release=prometheus`. Scrape metrics directly from the `/metrics` endpoint of - $productName$ running in the `ambassador` namespace. You may + Emissary running in the `ambassador` namespace. You may want to adjust namespace and label selectors to match your installation: ```yaml @@ -215,7 +217,7 @@ documentation. - port: ambassador-admin ``` -Prometheus is now configured to gather metrics from $productName$. +Prometheus is now configured to gather metrics from Emissary. #### Prometheus Operator CRDs @@ -247,12 +249,12 @@ for monitoring your ingress traffic and control plane operations. 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 --- @@ -332,7 +334,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, @@ -353,7 +355,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 `Add your first data source`. Now, select 'Prometheus'. In the URL section, type in `http://prometheus.default:9090`, or `http://prometheus-operated.default:9090` if you installed Prometheus with Helm. @@ -368,12 +370,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 with -$productName$ metrics. +Emissary metrics. ## 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. @@ -395,7 +397,7 @@ kubectl port-forward service/prometheus 9090 and going to `http://localhost:9090/` from a web browser In the UI, discover all the stats Prometheus is -able to scrape from $productName$ by searching for expressions +able to scrape from Emissary by searching for expressions starting with `envoy` and `ambassador`. The Prometheus data model is, at its core, time-series diff --git a/content/en/docs/3.6/howtos/protecting-diag-access.md b/content/en/docs/3.6/howtos/protecting-diag-access.md index edbb34ae..ec601db2 100644 --- a/content/en/docs/3.6/howtos/protecting-diag-access.md +++ b/content/en/docs/3.6/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/3.6/howtos/rate-limiting-tutorial.md b/content/en/docs/3.6/howtos/rate-limiting-tutorial.md index a098e758..60215764 100644 --- a/content/en/docs/3.6/howtos/rate-limiting-tutorial.md +++ b/content/en/docs/3.6/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/ratelimit-example) 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/ratelimit-example) that: - listens for requests on port 5000; - handles gRPC `shouldRateLimit` requests; @@ -76,17 +76,17 @@ spec: 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: +Once this configuration is applied Kubernetes will startup the example ratelimit service and Emissary will be configured to use the rate limit service. The `RateLimitService` configuration tells Emissary 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. +If Emissary 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 +## 2. Configure Emissary 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 +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/). diff --git a/content/en/docs/3.6/howtos/route.md b/content/en/docs/3.6/howtos/route.md index 6a399ec5..705e4242 100644 --- a/content/en/docs/3.6/howtos/route.md +++ b/content/en/docs/3.6/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/3.6/howtos/tls-termination.md b/content/en/docs/3.6/howtos/tls-termination.md index 2bbdf4c4..a1625ece 100644 --- a/content/en/docs/3.6/howtos/tls-termination.md +++ b/content/en/docs/3.6/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 @@ -104,7 +106,7 @@ spec: 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.: +**Note:** If running multiple instances of Emissary in one cluster remember to include the `ambassador_id` property in the `spec`, e.g.: ```yaml --- @@ -123,14 +125,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`: ``` @@ -153,9 +155,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: ``` @@ -173,20 +175,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/3.6/howtos/tracing-datadog.md b/content/en/docs/3.6/howtos/tracing-datadog.md index d627e29f..842bc6a0 100644 --- a/content/en/docs/3.6/howtos/tracing-datadog.md +++ b/content/en/docs/3.6/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/3.6/howtos/tracing-lightstep.md b/content/en/docs/3.6/howtos/tracing-lightstep.md index 30353e71..1e8c7471 100644 --- a/content/en/docs/3.6/howtos/tracing-lightstep.md +++ b/content/en/docs/3.6/howtos/tracing-lightstep.md @@ -1,16 +1,18 @@ -# Distributed Tracing with OpenTelemetry and Lightstep +--- +title: 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. +In this tutorial, we'll configure [Emissary](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. + Please note that the TracingService no longer supports the native Envoy Lightstep tracing driver as of Emissary 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. +This tutorial 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. -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. Setup Lightstep @@ -189,19 +191,19 @@ spec: 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): +As a final step we want to restart Emissary as this is necessary to add the distributed tracing headers. This command will restart all the Pods (assuming Emissary 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. + Restarting Emissary 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. +Finally, we are going to test our Distributed Tracing. 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. ```bash curl -Li http://$LB_ENDPOINT/backend/ @@ -212,18 +214,18 @@ At this point, we should be able to view and check our traces on the [Lightstep ## Migrating from the Lightstep Tracing Driver - Please be sure to follow these steps prior to upgrading to $productName$ version 3.4.0. + Please be sure to follow these steps prior to upgrading to Emissary 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. +As of Emissary 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. +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 Emissary 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: +Once our TracingService configuration has been updated, a restart of Emissary 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.6/howtos/tracing-zipkin.md b/content/en/docs/3.6/howtos/tracing-zipkin.md index 37ddc902..874a2fb3 100644 --- a/content/en/docs/3.6/howtos/tracing-zipkin.md +++ b/content/en/docs/3.6/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/3.6/howtos/websockets.md b/content/en/docs/3.6/howtos/websockets.md index 25cac7da..95925b23 100644 --- a/content/en/docs/3.6/howtos/websockets.md +++ b/content/en/docs/3.6/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/3.6/release-notes/edge-stack-1.13.4.png b/content/en/docs/3.6/release-notes/edge-stack-1.13.4.png deleted file mode 100644 index 954ac1a9..00000000 Binary files a/content/en/docs/3.6/release-notes/edge-stack-1.13.4.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/edge-stack-1.13.7-json-logging.png b/content/en/docs/3.6/release-notes/edge-stack-1.13.7-json-logging.png deleted file mode 100644 index 4a47cbdf..00000000 Binary files a/content/en/docs/3.6/release-notes/edge-stack-1.13.7-json-logging.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/edge-stack-1.13.7-memory.png b/content/en/docs/3.6/release-notes/edge-stack-1.13.7-memory.png deleted file mode 100644 index 9c415ba3..00000000 Binary files a/content/en/docs/3.6/release-notes/edge-stack-1.13.7-memory.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/edge-stack-1.13.7-tcpmapping-consul.png b/content/en/docs/3.6/release-notes/edge-stack-1.13.7-tcpmapping-consul.png deleted file mode 100644 index c455a47f..00000000 Binary files a/content/en/docs/3.6/release-notes/edge-stack-1.13.7-tcpmapping-consul.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/edge-stack-1.13.8-cloud-bugfix.png b/content/en/docs/3.6/release-notes/edge-stack-1.13.8-cloud-bugfix.png deleted file mode 100644 index 6beaf653..00000000 Binary files a/content/en/docs/3.6/release-notes/edge-stack-1.13.8-cloud-bugfix.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/edge-stack-2.0.0-host_crd.png b/content/en/docs/3.6/release-notes/edge-stack-2.0.0-host_crd.png deleted file mode 100644 index c77ef528..00000000 Binary files a/content/en/docs/3.6/release-notes/edge-stack-2.0.0-host_crd.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/edge-stack-2.0.0-ingressstatus.png b/content/en/docs/3.6/release-notes/edge-stack-2.0.0-ingressstatus.png deleted file mode 100644 index 6856d308..00000000 Binary files a/content/en/docs/3.6/release-notes/edge-stack-2.0.0-ingressstatus.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/edge-stack-2.0.0-insecure_action_hosts.png b/content/en/docs/3.6/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.6/release-notes/edge-stack-2.0.0-insecure_action_hosts.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/edge-stack-2.0.0-listener.png b/content/en/docs/3.6/release-notes/edge-stack-2.0.0-listener.png deleted file mode 100644 index ea45a02b..00000000 Binary files a/content/en/docs/3.6/release-notes/edge-stack-2.0.0-listener.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/edge-stack-2.0.0-prune_routes.png b/content/en/docs/3.6/release-notes/edge-stack-2.0.0-prune_routes.png deleted file mode 100644 index bc43229f..00000000 Binary files a/content/en/docs/3.6/release-notes/edge-stack-2.0.0-prune_routes.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/edge-stack-2.0.0-tlscontext.png b/content/en/docs/3.6/release-notes/edge-stack-2.0.0-tlscontext.png deleted file mode 100644 index 68dbad80..00000000 Binary files a/content/en/docs/3.6/release-notes/edge-stack-2.0.0-tlscontext.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/edge-stack-2.0.0-v3alpha1.png b/content/en/docs/3.6/release-notes/edge-stack-2.0.0-v3alpha1.png deleted file mode 100644 index c0ac3596..00000000 Binary files a/content/en/docs/3.6/release-notes/edge-stack-2.0.0-v3alpha1.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/emissary-1.13.10-cors-origin.png b/content/en/docs/3.6/release-notes/emissary-1.13.10-cors-origin.png deleted file mode 100644 index b7538e5f..00000000 Binary files a/content/en/docs/3.6/release-notes/emissary-1.13.10-cors-origin.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/emissary-ga.png b/content/en/docs/3.6/release-notes/emissary-ga.png deleted file mode 100644 index 062f043a..00000000 Binary files a/content/en/docs/3.6/release-notes/emissary-ga.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/tada.png b/content/en/docs/3.6/release-notes/tada.png deleted file mode 100644 index c8832e8e..00000000 Binary files a/content/en/docs/3.6/release-notes/tada.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/v2.0.4-k8s-1.22.png b/content/en/docs/3.6/release-notes/v2.0.4-k8s-1.22.png deleted file mode 100644 index ed9b0415..00000000 Binary files a/content/en/docs/3.6/release-notes/v2.0.4-k8s-1.22.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/v2.0.4-l7depth.png b/content/en/docs/3.6/release-notes/v2.0.4-l7depth.png deleted file mode 100644 index 9314324c..00000000 Binary files a/content/en/docs/3.6/release-notes/v2.0.4-l7depth.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/v2.0.4-mapping-dns-type.png b/content/en/docs/3.6/release-notes/v2.0.4-mapping-dns-type.png deleted file mode 100644 index 7770c77d..00000000 Binary files a/content/en/docs/3.6/release-notes/v2.0.4-mapping-dns-type.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/v2.0.4-v3alpha1.png b/content/en/docs/3.6/release-notes/v2.0.4-v3alpha1.png deleted file mode 100644 index 9c50b8fb..00000000 Binary files a/content/en/docs/3.6/release-notes/v2.0.4-v3alpha1.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/v2.0.4-version.png b/content/en/docs/3.6/release-notes/v2.0.4-version.png deleted file mode 100644 index 9481b7db..00000000 Binary files a/content/en/docs/3.6/release-notes/v2.0.4-version.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/v2.0.5-auth-circuit-breaker.png b/content/en/docs/3.6/release-notes/v2.0.5-auth-circuit-breaker.png deleted file mode 100644 index cac8cf7b..00000000 Binary files a/content/en/docs/3.6/release-notes/v2.0.5-auth-circuit-breaker.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/v2.0.5-mappingselector.png b/content/en/docs/3.6/release-notes/v2.0.5-mappingselector.png deleted file mode 100644 index 31942ede..00000000 Binary files a/content/en/docs/3.6/release-notes/v2.0.5-mappingselector.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/v2.1.0-canary.png b/content/en/docs/3.6/release-notes/v2.1.0-canary.png deleted file mode 100644 index 39d3bbbf..00000000 Binary files a/content/en/docs/3.6/release-notes/v2.1.0-canary.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/v2.1.0-gzip-enabled.png b/content/en/docs/3.6/release-notes/v2.1.0-gzip-enabled.png deleted file mode 100644 index 061fcbc9..00000000 Binary files a/content/en/docs/3.6/release-notes/v2.1.0-gzip-enabled.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/v2.1.0-smoother-migration.png b/content/en/docs/3.6/release-notes/v2.1.0-smoother-migration.png deleted file mode 100644 index ebd77497..00000000 Binary files a/content/en/docs/3.6/release-notes/v2.1.0-smoother-migration.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/v2.1.2-annotations.png b/content/en/docs/3.6/release-notes/v2.1.2-annotations.png deleted file mode 100644 index b5498c3c..00000000 Binary files a/content/en/docs/3.6/release-notes/v2.1.2-annotations.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/v2.1.2-host-mapping-matching.png b/content/en/docs/3.6/release-notes/v2.1.2-host-mapping-matching.png deleted file mode 100644 index 1cfba5ed..00000000 Binary files a/content/en/docs/3.6/release-notes/v2.1.2-host-mapping-matching.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/v2.1.2-mapping-cors.png b/content/en/docs/3.6/release-notes/v2.1.2-mapping-cors.png deleted file mode 100644 index f76ea01c..00000000 Binary files a/content/en/docs/3.6/release-notes/v2.1.2-mapping-cors.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/v2.1.2-mapping-less-weighted.png b/content/en/docs/3.6/release-notes/v2.1.2-mapping-less-weighted.png deleted file mode 100644 index 7e299062..00000000 Binary files a/content/en/docs/3.6/release-notes/v2.1.2-mapping-less-weighted.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/v2.1.2-mapping-no-rewrite.png b/content/en/docs/3.6/release-notes/v2.1.2-mapping-no-rewrite.png deleted file mode 100644 index 5d3d5a29..00000000 Binary files a/content/en/docs/3.6/release-notes/v2.1.2-mapping-no-rewrite.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/v2.2.0-cloud.png b/content/en/docs/3.6/release-notes/v2.2.0-cloud.png deleted file mode 100644 index 5923fcb4..00000000 Binary files a/content/en/docs/3.6/release-notes/v2.2.0-cloud.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/v2.2.0-percent-escape.png b/content/en/docs/3.6/release-notes/v2.2.0-percent-escape.png deleted file mode 100644 index df4d81b9..00000000 Binary files a/content/en/docs/3.6/release-notes/v2.2.0-percent-escape.png and /dev/null differ diff --git a/content/en/docs/3.6/release-notes/v2.2.0-tls-cert-validation.png b/content/en/docs/3.6/release-notes/v2.2.0-tls-cert-validation.png deleted file mode 100644 index f8635b5a..00000000 Binary files a/content/en/docs/3.6/release-notes/v2.2.0-tls-cert-validation.png and /dev/null differ diff --git a/content/en/docs/3.6/releaseNotes.yml b/content/en/docs/3.6/releaseNotes.yml deleted file mode 100644 index b86b1ee9..00000000 --- a/content/en/docs/3.6/releaseNotes.yml +++ /dev/null @@ -1,1569 +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.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/3.6/topics/_index.md b/content/en/docs/3.6/topics/_index.md new file mode 100644 index 00000000..4beca302 --- /dev/null +++ b/content/en/docs/3.6/topics/_index.md @@ -0,0 +1,4 @@ +--- +title: "Topics" +weight: 30 +--- diff --git a/content/en/docs/3.6/topics/concepts/index.md b/content/en/docs/3.6/topics/concepts/_index.md similarity index 81% rename from content/en/docs/3.6/topics/concepts/index.md rename to content/en/docs/3.6/topics/concepts/_index.md index 2d02a027..df88d005 100644 --- a/content/en/docs/3.6/topics/concepts/index.md +++ b/content/en/docs/3.6/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/3.6/topics/concepts/architecture.md b/content/en/docs/3.6/topics/concepts/architecture.md index fe9e0bd3..85aa5397 100644 --- a/content/en/docs/3.6/topics/concepts/architecture.md +++ b/content/en/docs/3.6/topics/concepts/architecture.md @@ -1,27 +1,32 @@ -# The $productName$ architecture +--- +title: "Architecture" +description: "This section of the documentation provides an overview of the Emissary architecture" +--- -## $productName$ is a control plane +# The Emissary architecture -$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 control plane + +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/3.6/topics/concepts/gitops-continuous-delivery.md b/content/en/docs/3.6/topics/concepts/gitops-continuous-delivery.md index 336a1c66..c8878695 100644 --- a/content/en/docs/3.6/topics/concepts/gitops-continuous-delivery.md +++ b/content/en/docs/3.6/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/3.6/topics/concepts/kubernetes-network-architecture.md b/content/en/docs/3.6/topics/concepts/kubernetes-network-architecture.md index 2239a24f..ce2ada65 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 @@ -1,3 +1,8 @@ +--- +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 @@ -34,7 +39,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 +49,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/3.6/topics/concepts/microservices-api-gateways.md b/content/en/docs/3.6/topics/concepts/microservices-api-gateways.md index ba95b8fc..46415c42 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 @@ -1,3 +1,8 @@ +--- +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. diff --git a/content/en/docs/3.6/topics/concepts/progressive-delivery.md b/content/en/docs/3.6/topics/concepts/progressive-delivery.md index f2ade27f..b4eba9e4 100644 --- a/content/en/docs/3.6/topics/concepts/progressive-delivery.md +++ b/content/en/docs/3.6/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/3.6/topics/concepts/rate-limiting-at-the-edge.md b/content/en/docs/3.6/topics/concepts/rate-limiting-at-the-edge.md index f471b6d5..b694689a 100644 --- a/content/en/docs/3.6/topics/concepts/rate-limiting-at-the-edge.md +++ b/content/en/docs/3.6/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](../../../../2.0/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](../../../../2.0/howtos/advanced-rate-limiting) documentation for examples. ## Benefits of applying a rate limiter to the edge diff --git a/content/en/docs/3.6/topics/install/index.md b/content/en/docs/3.6/topics/install/_index.md similarity index 52% rename from content/en/docs/3.6/topics/install/index.md rename to content/en/docs/3.6/topics/install/_index.md index 40fa95fd..c0c54068 100644 --- a/content/en/docs/3.6/topics/install/index.md +++ b/content/en/docs/3.6/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/3.6/topics/install/ambassador-oss-community.md b/content/en/docs/3.6/topics/install/ambassador-oss-community.md index b53d1407..e4150e2f 100644 --- a/content/en/docs/3.6/topics/install/ambassador-oss-community.md +++ b/content/en/docs/3.6/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/3.6/topics/install/bare-metal.md b/content/en/docs/3.6/topics/install/bare-metal.md index 84ac1c8d..7a7cbfb5 100644 --- a/content/en/docs/3.6/topics/install/bare-metal.md +++ b/content/en/docs/3.6/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/3.6/topics/install/convert-to-v3alpha1.md b/content/en/docs/3.6/topics/install/convert-to-v3alpha1.md index 2d8dfb79..53e8f932 100644 --- a/content/en/docs/3.6/topics/install/convert-to-v3alpha1.md +++ b/content/en/docs/3.6/topics/install/convert-to-v3alpha1.md @@ -1,18 +1,18 @@ -import Alert from '@material-ui/lab/Alert'; - -# Convert Configuration 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/3.6/topics/install/docker.md b/content/en/docs/3.6/topics/install/docker.md index e430a55c..f2ad9db5 100644 --- a/content/en/docs/3.6/topics/install/docker.md +++ b/content/en/docs/3.6/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/3.6/topics/install/helm.md b/content/en/docs/3.6/topics/install/helm.md index a807d335..3b74f533 100644 --- a/content/en/docs/3.6/topics/install/helm.md +++ b/content/en/docs/3.6/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,6 +99,6 @@ 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/3.6/topics/install/index.less b/content/en/docs/3.6/topics/install/index.less deleted file mode 100644 index bc649e7c..00000000 --- a/content/en/docs/3.6/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.6/topics/install/migrate-to-2-alternate.md b/content/en/docs/3.6/topics/install/migrate-to-2-alternate.md index edc42916..7d45c17a 100644 --- a/content/en/docs/3.6/topics/install/migrate-to-2-alternate.md +++ b/content/en/docs/3.6/topics/install/migrate-to-2-alternate.md @@ -1,40 +1,37 @@ --- - Title: Migrate to $productName$ $versionTwoX$ - description: "Instructions for how to upgrade $productName$ to $versionTwoX$. Transfer your current configuration of $AESproductName$ or $OSSproductName$ to $versionTwoX$." +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" --- -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 +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$ $versionTwoX$: +For example, to upgrade from some other version of Ambassador Edge Stack or +Emissary to Emissary $versionTwoX$: -1. Install $productName$ $versionTwoX$ in a completely new cluster. +1. Install Emissary $versionTwoX$ in a completely new cluster. -2. **Create `Listener`s for $productName$ $versionTwoX$.** +2. **Create `Listener`s for Emissary $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$ + When Emissary $versionTwoX$ starts, it will not have any `Listener`s, and it will not + create any. You must create `Listener` resources by hand, or Emissary $versionTwoX$ 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 $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` + This will create `getambassador.io/v2` resources in the Emissary $versionTwoX$ cluster. + Emissary $versionTwoX$ 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 $versionTwoX$ cluster. diff --git a/content/en/docs/3.6/topics/install/migrate-to-3-alternate.md b/content/en/docs/3.6/topics/install/migrate-to-3-alternate.md index 3b9df0c1..711bc618 100644 --- a/content/en/docs/3.6/topics/install/migrate-to-3-alternate.md +++ b/content/en/docs/3.6/topics/install/migrate-to-3-alternate.md @@ -1,36 +1,37 @@ -import Alert from '@material-ui/lab/Alert'; +--- +title: Migrate to Emissary 3.x +description: "Instructions for how to upgrade Emissary to 3.x. Transfer your current configuration of Emissary to 3.x." +--- -# Upgrading $productName$ $version$ 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/3.6/topics/install/migration-matrix.md b/content/en/docs/3.6/topics/install/migration-matrix.md index b980ca1d..1ab1ce75 100644 --- a/content/en/docs/3.6/topics/install/migration-matrix.md +++ b/content/en/docs/3.6/topics/install/migration-matrix.md @@ -1,46 +1,46 @@ -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$](/docs/edge-stack/$aesDocsVersion$/topics/install/migration-matrix/). +See the [instructions on updating Ambassador Edge Stack](/docs/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-3.6/edge-stack-3.X/) | -| $OSSproductName$ 3.5.X | [$OSSproductName$ $version$](../upgrade/helm/emissary-3.5/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) | +| Emissary $version$ | [Ambassador Edge Stack $aesVersion$](/docs/edge-stack/$aesDocsVersion$/topics/install/upgrade/helm/emissary-3.6/edge-stack-3.X/) | +| Emissary 3.5.X | [Emissary $version$](../upgrade/helm/emissary-3.5/emissary-3.X) | +| Emissary $versionTwoX$ | [Emissary $version$](../upgrade/helm/emissary-2.5/emissary-3.X) | +| Emissary 2.4.X | [Emissary $versionTwoX$](../upgrade/helm/emissary-2.4/emissary-2.X) | +| Emissary 2.0.5 | [Emissary $versionTwoX$](../upgrade/helm/emissary-2.0/emissary-2.X) | +| Emissary $versionOneX$ | [Emissary $versionTwoX$](../upgrade/helm/emissary-1.14/emissary-2.X) | +| Emissary prior to $versionOneX$ | [Emissary $versionOneX$](../../../../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-3.6/edge-stack-3.X/) | -| $OSSproductName$ 3.5.X | [$OSSproductName$ $version$](../upgrade/yaml/emissary-3.5/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) | +| Emissary $version$ | [Ambassador Edge Stack $aesVersion$](/docs/edge-stack/$aesDocsVersion$/topics/install/upgrade/yaml/emissary-3.6/edge-stack-3.X/) | +| Emissary 3.5.X | [Emissary $version$](../upgrade/yaml/emissary-3.5/emissary-3.X) | +| Emissary $versionTwoX$ | [Emissary $version$](../upgrade/yaml/emissary-2.5/emissary-3.X) | +| Emissary 2.4.X | [Emissary $versionTwoX$](../upgrade/yaml/emissary-2.4/emissary-2.X) | +| Emissary 2.0.5 | [Emissary $versionTwoX$](../upgrade/yaml/emissary-2.0/emissary-2.X) | +| Emissary $versionOneX$ | [Emissary $versionTwoX$](../upgrade/yaml/emissary-1.14/emissary-2.X) | +| Emissary prior to $versionOneX$ | [Emissary $versionOneX$](../../../../1.14/topics/install/upgrading) | diff --git a/content/en/docs/3.6/topics/install/upgrade/_index.md b/content/en/docs/3.6/topics/install/upgrade/_index.md new file mode 100644 index 00000000..65f73d96 --- /dev/null +++ b/content/en/docs/3.6/topics/install/upgrade/_index.md @@ -0,0 +1,4 @@ +--- +title: Upgrade +weight: -10 +--- diff --git a/content/en/docs/3.6/topics/install/upgrade/helm/_index.md b/content/en/docs/3.6/topics/install/upgrade/helm/_index.md new file mode 100644 index 00000000..a7e3d4b1 --- /dev/null +++ b/content/en/docs/3.6/topics/install/upgrade/helm/_index.md @@ -0,0 +1,3 @@ +--- +title: Helm +--- diff --git a/content/en/docs/3.6/topics/install/upgrade/helm/emissary-1.14/_index.md b/content/en/docs/3.6/topics/install/upgrade/helm/emissary-1.14/_index.md new file mode 100644 index 00000000..a1248d01 --- /dev/null +++ b/content/en/docs/3.6/topics/install/upgrade/helm/emissary-1.14/_index.md @@ -0,0 +1,3 @@ +--- +title: 1.14 +--- diff --git a/content/en/docs/3.6/topics/install/upgrade/helm/emissary-1.14/emissary-2.X.md b/content/en/docs/3.6/topics/install/upgrade/helm/emissary-1.14/emissary-2.X.md index bd61fafc..51d4db35 100644 --- a/content/en/docs/3.6/topics/install/upgrade/helm/emissary-1.14/emissary-2.X.md +++ b/content/en/docs/3.6/topics/install/upgrade/helm/emissary-1.14/emissary-2.X.md @@ -1,9 +1,9 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 1.14.X (Helm) +--- +title: 1.14.x to 2.x +--- - This guide covers migrating from $productName$ 1.14.X to $productName$ $versionTwoX$. If + This guide covers migrating from Emissary 1.14.X to Emissary $versionTwoX$. 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$ $versionTwoX$! 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 $versionTwoX$! 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$ -$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 +The recommended strategy for migration is to run Emissary 1.14 and Emissary +$versionTwoX$ side-by-side in the same cluster. This gives Emissary $versionTwoX$ +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$ $versionTwoX$, while not interfering with the operation of your - $productName$ 1.14 installation. + Emissary $versionTwoX$, 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$ $versionTwoX$ installation from - seeing a particular bit of $productName$ 1.14 configuration, you can apply + If you need to prevent your Emissary $versionTwoX$ 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$ $versionTwoX$ installation, then set its + your Emissary $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 + that should be visible to Emissary $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$ + If you have services in Emissary 1.14 that use selectors that will match + Pods from Emissary $versionTwoX$, traffic will be erroneously split between + Emissary 1.14 and Emissary $versionTwoX$. The labels used by Emissary $versionTwoX$ 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$ $versionTwoX$. Once testing is done, you can switch Agents safely. + Emissary $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 +You can also migrate by [installing Emissary $versionTwoX$ 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 $versionTwoX$, 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$ $versionTwoX$ itself, you must configure your + Before installing Emissary $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$, + must install support for `getambassador.io/v3alpha1`** to run Emissary $versionTwoX$, 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$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace + Emissary $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 + 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$ $versionTwoX$.** +3. **Install Emissary $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 + After installing the new CRDs, you need to install Emissary $versionTwoX$ 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$ $versionTwoX$ includes a Deployment in the $productNamespace$ namespace + Emissary $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 + 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$ $versionTwoX$ is the + An important difference between Emissary 1.14 and Emissary $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$ + you will need to make sure that a `Host` is present for the new Emissary $versionTwoX$ 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$ $versionTwoX$ installation can support the `getambassador.io/v2` - configuration resources used by $productName$ 1.14, but you may need to make some + Your Emissary $versionTwoX$ 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$ $versionTwoX$ installation and your $productName$ 1.14 + If you find that your Emissary $versionTwoX$ 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$ $versionTwoX$. + installation of Emissary $versionTwoX$. -6. **When ready, switch over to $productName$ $versionTwoX$.** +6. **When ready, switch over to Emissary $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** + You can run Emissary 1.14 and Emissary $versionTwoX$ 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$ $versionTwoX$ are only available using + since some useful features in Emissary $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 + When you're ready to have Emissary $versionTwoX$ handle traffic on its own, switch + your original Emissary 1.14 Service to point to Emissary $versionTwoX$. 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$ $versionTwoX$ Ambassador Agent.** +7. **Finally, install the Emissary $versionTwoX$ 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$ $versionTwoX$ is fully running and it's safe to remove the `ambassador` and `ambassador-agent` Deployments: +Congratulations! At this point, Emissary $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) +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/3.6/topics/install/upgrade/helm/emissary-2.0/_index.md b/content/en/docs/3.6/topics/install/upgrade/helm/emissary-2.0/_index.md new file mode 100644 index 00000000..a17e8935 --- /dev/null +++ b/content/en/docs/3.6/topics/install/upgrade/helm/emissary-2.0/_index.md @@ -0,0 +1,3 @@ +--- +title: 2.0 +--- diff --git a/content/en/docs/3.6/topics/install/upgrade/helm/emissary-2.0/emissary-2.X.md b/content/en/docs/3.6/topics/install/upgrade/helm/emissary-2.0/emissary-2.X.md index c0a392f1..2113afff 100644 --- a/content/en/docs/3.6/topics/install/upgrade/helm/emissary-2.0/emissary-2.X.md +++ b/content/en/docs/3.6/topics/install/upgrade/helm/emissary-2.0/emissary-2.X.md @@ -1,9 +1,9 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.0.5 (Helm) +--- +title: 2.0.x to latest 2.x +--- - This guide covers migrating from $productName$ 2.0.5 to $productName$ $versionTwoX$. If + This guide covers migrating from Emissary 2.0.5 to Emissary $versionTwoX$. 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$ $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$. + Before installing Emissary $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 Emissary. ``` kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml @@ -30,9 +30,9 @@ Migration is a two-step process: ``` - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace + Emissary $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 + 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$ $versionTwoX$.** +2. **Install Emissary $versionTwoX$.** - After installing the new CRDs, use Helm to install $productName$ $versionTwoX$. Start by + After installing the new CRDs, use Helm to install Emissary $versionTwoX$. 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/3.6/topics/install/upgrade/helm/emissary-2.4/_index.md b/content/en/docs/3.6/topics/install/upgrade/helm/emissary-2.4/_index.md new file mode 100644 index 00000000..39dfcfd6 --- /dev/null +++ b/content/en/docs/3.6/topics/install/upgrade/helm/emissary-2.4/_index.md @@ -0,0 +1,3 @@ +--- +title: 2.4 +--- diff --git a/content/en/docs/3.6/topics/install/upgrade/helm/emissary-2.4/emissary-2.X.md b/content/en/docs/3.6/topics/install/upgrade/helm/emissary-2.4/emissary-2.X.md index 3e44b511..d9a6a6f0 100644 --- a/content/en/docs/3.6/topics/install/upgrade/helm/emissary-2.4/emissary-2.X.md +++ b/content/en/docs/3.6/topics/install/upgrade/helm/emissary-2.4/emissary-2.X.md @@ -1,9 +1,9 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.4.Z (Helm) +--- +title: 2.4.x to latest 2.x +--- - This guide covers migrating from $productName$ 2.4.Z to $productName$ $versionTwoX$. If + This guide covers migrating from Emissary 2.4.Z to Emissary $versionTwoX$. 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$ $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$. + Before installing Emissary $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 Emissary. ``` kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml @@ -30,9 +30,9 @@ Migration is a two-step process: ``` - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace + Emissary $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 + 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$ $versionTwoX$.** +2. **Install Emissary $versionTwoX$.** - After installing the new CRDs, use Helm to install $productName$ $versionTwoX$. Start by + After installing the new CRDs, use Helm to install Emissary $versionTwoX$. 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/3.6/topics/install/upgrade/helm/emissary-2.5/_index.md b/content/en/docs/3.6/topics/install/upgrade/helm/emissary-2.5/_index.md new file mode 100644 index 00000000..7e9b9b4d --- /dev/null +++ b/content/en/docs/3.6/topics/install/upgrade/helm/emissary-2.5/_index.md @@ -0,0 +1,3 @@ +--- +title: 2.5 +--- diff --git a/content/en/docs/3.6/topics/install/upgrade/helm/emissary-2.5/emissary-3.X.md b/content/en/docs/3.6/topics/install/upgrade/helm/emissary-2.5/emissary-3.X.md index d8439c5a..484b719f 100644 --- a/content/en/docs/3.6/topics/install/upgrade/helm/emissary-2.5/emissary-3.X.md +++ b/content/en/docs/3.6/topics/install/upgrade/helm/emissary-2.5/emissary-3.X.md @@ -1,9 +1,9 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.5.Z (Helm) +--- +title: 2.5.x to latest 3.x +--- - This guide covers migrating from $productName$ 2.5.Z to $productName$ $version$. If + This guide covers migrating from Emissary 2.5.Z to Emissary $version$. If this is not your exact situation, see the migration matrix. @@ -19,23 +19,23 @@ import Alert from '@material-ui/lab/Alert'; 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 +Since Emissary'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. +Emissary 3 is functionally compatible with Emissary 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. +Emissary 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. +You can refer to the [Major changes in Emissary 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. +1. Emissary 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 + The environment variable `DISABLE_STRICT_LABEL_SELECTORS` can be set to `"true"` on the Emissary 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). @@ -44,7 +44,7 @@ You can refer to the [Major changes in $productName$ 3.x](../../../../../../abou 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. + `protocol_version` should be updated to `v3` for all of the above resources while still running Emissary $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 Emissary $version$ where support for `v2` is removed. Upgrading any application code for your own implementations of these services is very straightforward. @@ -68,7 +68,7 @@ You can refer to the [Major changes in $productName$ 3.x](../../../../../../abou ```yaml # No longer necessary because this was removed from Envoy - # $productName$ already was converted to use the compressor API + # Emissary 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, @@ -86,10 +86,10 @@ You can refer to the [Major changes in $productName$ 3.x](../../../../../../abou 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. + As of Emissary 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.** +Emissary 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 @@ -98,10 +98,10 @@ 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. + in previous version of Emissary 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$. + Before installing Emissary $version$ itself, you need to update the CRDs in + your cluster. This is mandatory during any upgrade of Emissary. ```bash kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml @@ -109,9 +109,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. @@ -123,13 +123,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 @@ -138,7 +138,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. @@ -149,5 +149,5 @@ Migration is a two-step process: ``` - You must use the $productHelmName$ Helm chart for $productName$ 3.Y. + You must use the $productHelmName$ Helm chart for Emissary 3.Y. diff --git a/content/en/docs/3.6/topics/install/upgrade/helm/emissary-3.4/_index.md b/content/en/docs/3.6/topics/install/upgrade/helm/emissary-3.4/_index.md new file mode 100644 index 00000000..25fc70fb --- /dev/null +++ b/content/en/docs/3.6/topics/install/upgrade/helm/emissary-3.4/_index.md @@ -0,0 +1,3 @@ +--- +title: 3.4 +--- diff --git a/content/en/docs/3.6/topics/install/upgrade/helm/emissary-3.4/emissary-3.X.md b/content/en/docs/3.6/topics/install/upgrade/helm/emissary-3.4/emissary-3.X.md index f5b4e26d..e377b944 100644 --- a/content/en/docs/3.6/topics/install/upgrade/helm/emissary-3.4/emissary-3.X.md +++ b/content/en/docs/3.6/topics/install/upgrade/helm/emissary-3.4/emissary-3.X.md @@ -1,9 +1,9 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 3.4.Z (Helm) +--- +title: 3.4 to latest 3.x +--- - This guide covers migrating from $productName$ 3.4.Z to $productName$ $version$. If + This guide covers migrating from Emissary 3.4.Z to Emissary $version$. If this is not your exact situation, see the migration matrix. @@ -14,16 +14,16 @@ 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. ### 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. + As of Emissary 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.** +Emissary 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 @@ -32,10 +32,10 @@ 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. + in previous version of Emissary 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$. + Before installing Emissary $version$ itself, you need to update the CRDs in + your cluster. This is mandatory during any upgrade of Emissary. ```bash kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml @@ -43,9 +43,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. @@ -57,13 +57,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 @@ -72,7 +72,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. @@ -83,5 +83,5 @@ Migration is a two-step process: ``` - You must use the $productHelmName$ Helm chart for $productName$ 3.Y. + You must use the $productHelmName$ Helm chart for Emissary 3.Y. diff --git a/content/en/docs/3.6/topics/install/upgrade/helm/emissary-3.5/_index.md b/content/en/docs/3.6/topics/install/upgrade/helm/emissary-3.5/_index.md new file mode 100644 index 00000000..fc28770e --- /dev/null +++ b/content/en/docs/3.6/topics/install/upgrade/helm/emissary-3.5/_index.md @@ -0,0 +1,3 @@ +--- +title: 3.5 +--- diff --git a/content/en/docs/3.6/topics/install/upgrade/helm/emissary-3.5/emissary-3.X.md b/content/en/docs/3.6/topics/install/upgrade/helm/emissary-3.5/emissary-3.X.md index 2344faea..d7e6f987 100644 --- a/content/en/docs/3.6/topics/install/upgrade/helm/emissary-3.5/emissary-3.X.md +++ b/content/en/docs/3.6/topics/install/upgrade/helm/emissary-3.5/emissary-3.X.md @@ -1,9 +1,9 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 3.5.Z (Helm) +--- +title: 3.5.x to latest 3.x +--- - This guide covers migrating from $productName$ 3.5.Z to $productName$ $version$. If + This guide covers migrating from Emissary 3.5.Z to Emissary $version$. If this is not your exact situation, see the migration matrix. @@ -14,7 +14,7 @@ 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. ### Resources to check before migrating to $version$. @@ -26,10 +26,10 @@ 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. + in the previous version of Emissary 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$. + Before installing Emissary $version$ itself, you need to update the CRDs in + your cluster. This is mandatory during any upgrade of Emissary. ```bash kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml @@ -37,9 +37,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. @@ -51,13 +51,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 @@ -66,7 +66,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. @@ -77,5 +77,5 @@ Migration is a two-step process: ``` - You must use the $productHelmName$ Helm chart for $productName$ 3.Y. + You must use the $productHelmName$ Helm chart for Emissary 3.Y. diff --git a/content/en/docs/3.6/topics/install/upgrade/yaml/_index.md b/content/en/docs/3.6/topics/install/upgrade/yaml/_index.md new file mode 100644 index 00000000..07ce4fef --- /dev/null +++ b/content/en/docs/3.6/topics/install/upgrade/yaml/_index.md @@ -0,0 +1,3 @@ +--- +title: YAML +--- diff --git a/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-1.14/_index.md b/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-1.14/_index.md new file mode 100644 index 00000000..a1248d01 --- /dev/null +++ b/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-1.14/_index.md @@ -0,0 +1,3 @@ +--- +title: 1.14 +--- diff --git a/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-1.14/emissary-2.X.md b/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-1.14/emissary-2.X.md index eb1dcf6c..9e69c1d8 100644 --- a/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-1.14/emissary-2.X.md +++ b/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-1.14/emissary-2.X.md @@ -1,9 +1,9 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 1.14.X (YAML) +--- +title: 1.14 to latest 2.x +--- - This guide covers migrating from $productName$ 1.14.X to $productName$ $versionTwoX$. If + This guide covers migrating from Emissary 1.14.X to Emissary $versionTwoX$. 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$ $versionTwoX$! 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 $versionTwoX$! 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$ -$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 +The recommended strategy for migration is to run Emissary 1.14 and Emissary +$versionTwoX$ side-by-side in the same cluster. This gives Emissary $versionTwoX$ +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$ $versionTwoX$, while not interfering with the operation of your - $productName$ 1.14 installation. + Emissary $versionTwoX$, 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$ $versionTwoX$ installation from - seeing a particular bit of $productName$ 1.14 configuration, you can apply + If you need to prevent your Emissary $versionTwoX$ 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$ $versionTwoX$ installation, then set its + your Emissary $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 + that should be visible to Emissary $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$ + If you have services in Emissary 1.14 that use selectors that will match + Pods from Emissary $versionTwoX$, traffic will be erroneously split between + Emissary 1.14 and Emissary $versionTwoX$. The labels used by Emissary $versionTwoX$ 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$ $versionTwoX$ will not + The migration YAML used below to install Emissary $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 +You can also migrate by [installing Emissary $versionTwoX$ 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 $versionTwoX$, 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$ $versionTwoX$ itself, you must configure your + Before installing Emissary $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$, + must install support for `getambassador.io/v3alpha1`** to run Emissary $versionTwoX$, 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$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace + Emissary $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 + 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$ $versionTwoX$.** +3. **Install Emissary $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 + After installing the new CRDs, you need to install Emissary $versionTwoX$ 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/$versionTwoX$/emissary-emissaryns.yaml @@ -166,9 +166,9 @@ Migration is a seven-step process: ``` - $productName$ $versionTwoX$ includes a Deployment in the $productNamespace$ namespace + Emissary $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 + 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$ $versionTwoX$ is the + An important difference between Emissary 1.14 and Emissary $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$ + you will need to make sure that a `Host` is present for the new Emissary $versionTwoX$ 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$ $versionTwoX$ installation can support the `getambassador.io/v2` - configuration resources used by $productName$ 1.14, but you may need to make some + Your Emissary $versionTwoX$ 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$ $versionTwoX$ installation and your $productName$ 1.14 + If you find that your Emissary $versionTwoX$ 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$ $versionTwoX$. + installation of Emissary $versionTwoX$. -6. **When ready, switch over to $productName$ $versionTwoX$.** +6. **When ready, switch over to Emissary $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** + You can run Emissary 1.14 and Emissary $versionTwoX$ 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$ $versionTwoX$ are only available using + since some useful features in Emissary $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 + When you're ready to have Emissary $versionTwoX$ handle traffic on its own, switch + your original Emissary 1.14 Service to point to Emissary $versionTwoX$. Use `kubectl edit service ambassador` and change the `selectors` to: ``` @@ -270,13 +270,13 @@ Migration is a seven-step process: Service. -Congratulations! At this point, $productName$ $versionTwoX$ is fully running and it's safe to remove the `ambassador` and `ambassador-agent` Deployments: +Congratulations! At this point, Emissary $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) +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/3.6/topics/install/upgrade/yaml/emissary-2.0/_index.md b/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-2.0/_index.md new file mode 100644 index 00000000..a17e8935 --- /dev/null +++ b/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-2.0/_index.md @@ -0,0 +1,3 @@ +--- +title: 2.0 +--- diff --git a/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-2.0/emissary-2.X.md b/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-2.0/emissary-2.X.md index b16d046f..e933b214 100644 --- a/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-2.0/emissary-2.X.md +++ b/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-2.0/emissary-2.X.md @@ -1,9 +1,9 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.0.5 (YAML) +--- +title: 2.0 to latest 2.x +--- - This guide covers migrating from $productName$ 2.0.5 to $productName$ $versionTwoX$. If + This guide covers migrating from Emissary 2.0.5 to Emissary $versionTwoX$. 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$ $versionTwoX$ itself, you need to update the CRDs in - your cluster. This is mandatory during any upgrade of $productName$. + Before installing Emissary $versionTwoX$ 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/$versionTwoX$/emissary-crds.yaml @@ -30,9 +30,9 @@ Migration is a two-step process: ``` - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace + Emissary $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 + 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$ $versionTwoX$.** +2. **Install Emissary $versionTwoX$.** - After installing the new CRDs, upgrade $productName$ $versionTwoX$. + After installing the new CRDs, upgrade Emissary $versionTwoX$. 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/3.6/topics/install/upgrade/yaml/emissary-2.4/_index.md b/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-2.4/_index.md new file mode 100644 index 00000000..39dfcfd6 --- /dev/null +++ b/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-2.4/_index.md @@ -0,0 +1,3 @@ +--- +title: 2.4 +--- diff --git a/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-2.4/emissary-2.X.md b/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-2.4/emissary-2.X.md index ec8b6a70..2e673b18 100644 --- a/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-2.4/emissary-2.X.md +++ b/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-2.4/emissary-2.X.md @@ -1,9 +1,9 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.4.Z (YAML) +--- +title: 2.4 to latest 2.x +--- - This guide covers migrating from $productName$ 2.4.Z to $productName$ $versionTwoX$. If + This guide covers migrating from Emissary 2.4.Z to Emissary $versionTwoX$. If this is not your exact situation, see the migration matrix. @@ -14,7 +14,7 @@ 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 Steps @@ -23,8 +23,8 @@ 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$. + Before installing Emissary $versionTwoX$ itself, you need to update the CRDs in + your cluster. This is mandatory during any upgrade of Emissary. ```bash kubectl apply -f https://app.getambassador.io/yaml/emissary/$versionTwoX$/emissary-crds.yaml @@ -32,9 +32,9 @@ Migration is a two-step process: ``` - $productName$ $versionTwoX$ includes a Deployment in the `emissary-system` namespace + Emissary $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 + that supports converting Emissary CRDs between getambassador.io/v2 and getambassador.io/v3alpha1. This Deployment needs to be running at all times. @@ -46,17 +46,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$ $versionTwoX$.** +2. **Install Emissary $versionTwoX$.** - After installing the new CRDs, upgrade $productName$ $versionTwoX$. + After installing the new CRDs, upgrade Emissary $versionTwoX$. 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/3.6/topics/install/upgrade/yaml/emissary-2.5/_index.md b/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-2.5/_index.md new file mode 100644 index 00000000..7e9b9b4d --- /dev/null +++ b/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-2.5/_index.md @@ -0,0 +1,3 @@ +--- +title: 2.5 +--- diff --git a/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-2.5/emissary-3.X.md b/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-2.5/emissary-3.X.md index ea3b7bc9..63a6d286 100644 --- a/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-2.5/emissary-3.X.md +++ b/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-2.5/emissary-3.X.md @@ -1,9 +1,9 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 2.5.Z (YAML) +--- +title: 2.5 to latest 3.x +--- - This guide covers migrating from $productName$ 2.5.Z to $productName$ $version$. If + This guide covers migrating from Emissary 2.5.Z to Emissary $version$. If this is not your exact situation, see the migration matrix. @@ -19,23 +19,23 @@ import Alert from '@material-ui/lab/Alert'; 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 +Since Emissary'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. +Emissary 3 is functionally compatible with Emissary 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. +Emissary 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. +You can refer to the [Major changes in Emissary 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. +1. Emissary 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 + The environment variable `DISABLE_STRICT_LABEL_SELECTORS` can be set to `"true"` on the Emissary 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). @@ -44,7 +44,7 @@ You can refer to the [Major changes in $productName$ 3.x](../../../../../../abou 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. + `protocol_version` should be updated to `v3` for all of the above resources while still running Emissary $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 Emissary $version$ where support for `v2` is removed. Upgrading any application code for your own implementations of these services is very straightforward. @@ -68,7 +68,7 @@ You can refer to the [Major changes in $productName$ 3.x](../../../../../../abou ```yaml # No longer necessary because this was removed from Envoy - # $productName$ already was converted to use the compressor API + # Emissary 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, @@ -86,10 +86,10 @@ You can refer to the [Major changes in $productName$ 3.x](../../../../../../abou 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. + As of Emissary 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.** +Emissary 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 @@ -98,10 +98,10 @@ 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. + in previous version of Emissary 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$. + Before installing Emissary $version$ itself, you need to update the CRDs in + your cluster. This is mandatory during any upgrade of Emissary. ```bash kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml @@ -109,9 +109,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. @@ -123,17 +123,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/3.6/topics/install/upgrade/yaml/emissary-3.4/_index.md b/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-3.4/_index.md new file mode 100644 index 00000000..25fc70fb --- /dev/null +++ b/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-3.4/_index.md @@ -0,0 +1,3 @@ +--- +title: 3.4 +--- diff --git a/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-3.4/emissary-3.X.md b/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-3.4/emissary-3.X.md index 723ac6a1..246a7c78 100644 --- a/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-3.4/emissary-3.X.md +++ b/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-3.4/emissary-3.X.md @@ -1,9 +1,9 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 3.4.Z (YAML) +--- +title: 3.4.x to latest 3.x +--- - This guide covers migrating from $productName$ 3.4.Z to $productName$ $version$. If + This guide covers migrating from Emissary 3.4.Z to Emissary $version$. If this is not your exact situation, see the migration matrix. @@ -14,16 +14,16 @@ import Alert from '@material-ui/lab/Alert'; upgrade instructions. -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading +Since Emissary'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. + As of Emissary 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.** +Emissary 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 @@ -31,8 +31,8 @@ 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. ```bash kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml @@ -40,9 +40,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. @@ -54,17 +54,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/3.6/topics/install/upgrade/yaml/emissary-3.5/_index.md b/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-3.5/_index.md new file mode 100644 index 00000000..ff66a134 --- /dev/null +++ b/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-3.5/_index.md @@ -0,0 +1,3 @@ +--- +title: 3.7 +--- diff --git a/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-3.5/emissary-3.X.md b/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-3.5/emissary-3.X.md index 5558728f..262c7cd3 100644 --- a/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-3.5/emissary-3.X.md +++ b/content/en/docs/3.6/topics/install/upgrade/yaml/emissary-3.5/emissary-3.X.md @@ -1,9 +1,9 @@ -import Alert from '@material-ui/lab/Alert'; - -# Upgrade $productName$ 3.5.Z (YAML) +--- +title: 3.7 to latest 3.x +--- - This guide covers migrating from $productName$ 3.5.Z to $productName$ $version$. If + This guide covers migrating from Emissary 3.5.Z to Emissary $version$. If this is not your exact situation, see the migration matrix. @@ -14,7 +14,7 @@ import Alert from '@material-ui/lab/Alert'; upgrade instructions. -Since $productName$'s configuration is entirely stored in Kubernetes resources, upgrading +Since Emissary's configuration is entirely stored in Kubernetes resources, upgrading between versions is straightforward. ### Resources to check before migrating to $version$. @@ -25,8 +25,8 @@ 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. ```bash kubectl apply -f https://app.getambassador.io/yaml/emissary/$version$/emissary-crds.yaml @@ -34,9 +34,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. @@ -48,17 +48,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/3.6/topics/install/yaml-install.md b/content/en/docs/3.6/topics/install/yaml-install.md index bb628f5b..0e1e151b 100644 --- a/content/en/docs/3.6/topics/install/yaml-install.md +++ b/content/en/docs/3.6/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,20 +67,20 @@ $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/3.6/topics/running/_index.md b/content/en/docs/3.6/topics/running/_index.md new file mode 100644 index 00000000..5a140ccb --- /dev/null +++ b/content/en/docs/3.6/topics/running/_index.md @@ -0,0 +1,21 @@ +--- +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. +* *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/3.6/topics/running/ambassador-deployment.md b/content/en/docs/3.6/topics/running/ambassador-deployment.md index d870f32c..4b4c6591 100644 --- a/content/en/docs/3.6/topics/running/ambassador-deployment.md +++ b/content/en/docs/3.6/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/3.6/topics/running/ambassador-with-aws.md b/content/en/docs/3.6/topics/running/ambassador-with-aws.md index b321543a..cf058510 100644 --- a/content/en/docs/3.6/topics/running/ambassador-with-aws.md +++ b/content/en/docs/3.6/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/3.6/topics/running/ambassador-with-gke.md b/content/en/docs/3.6/topics/running/ambassador-with-gke.md index 2b90581d..d13d7e8e 100644 --- a/content/en/docs/3.6/topics/running/ambassador-with-gke.md +++ b/content/en/docs/3.6/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/3.6/topics/running/ambassador.md b/content/en/docs/3.6/topics/running/ambassador.md index 3af41d93..d12a84e1 100644 --- a/content/en/docs/3.6/topics/running/ambassador.md +++ b/content/en/docs/3.6/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/3.6/topics/running/custom-error-responses.md b/content/en/docs/3.6/topics/running/custom-error-responses.md index b0ad9877..690c4482 100644 --- a/content/en/docs/3.6/topics/running/custom-error-responses.md +++ b/content/en/docs/3.6/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/3.6/topics/running/debugging.md b/content/en/docs/3.6/topics/running/debugging.md index bd376483..ab832de9 100644 --- a/content/en/docs/3.6/topics/running/debugging.md +++ b/content/en/docs/3.6/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/3.6/topics/running/diagnostics.md b/content/en/docs/3.6/topics/running/diagnostics.md index 20506304..857a3b3f 100644 --- a/content/en/docs/3.6/topics/running/diagnostics.md +++ b/content/en/docs/3.6/topics/running/diagnostics.md @@ -1,11 +1,13 @@ -# Diagnostics +--- +title: 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 +With Emissary 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? +### Can't access Emissary Diagnostics Overview? Create an Ambassador `Module` if one does not already exist, and add the following config to enable diagnostics data. @@ -37,9 +39,9 @@ Finally, set the `AES_DIAGNOSTICS_URL` environment variable to `"http://emissary After setting up `AES_DIAGNOSTICS_URL`, you can access diagnostics information by using the same URL value. -### Still can't see $productName$ Diagnostics? +### Still can't see Emissary Diagnostics? -Do a port forward on your $productName$ pod +Do a port forward on your Emissary pod ```shell # Namespace, deployment name, and pod url/port depend on your current install @@ -49,6 +51,6 @@ Do a port forward on your $productName$ pod 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? +### Emissary not routing your services as expected? -You will need to examine the logs and $productName$ pod status. See [Debugging](../debugging) for more information. +You will need to examine the logs and Emissary pod status. See [Debugging](../debugging) for more information. diff --git a/content/en/docs/3.6/topics/running/environment.md b/content/en/docs/3.6/topics/running/environment.md index 265fcedd..a7054c95 100644 --- a/content/en/docs/3.6/topics/running/environment.md +++ b/content/en/docs/3.6/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 | |----------------------------------------------------------------------------------------------------------- |-----------------------------------------------------|-------------------------------------------------------------------------------| @@ -57,7 +59,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) @@ -91,16 +93,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) @@ -112,19 +114,19 @@ 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 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. +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 were able switch back to Envoy V2 by setting the `AMBASSADOR_ENVOY_API_VERSION` environment variable to "V2". +Emissary 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 Emissary such as V4. ### `AMBASSADOR_GRPC_METRICS_SINK` @@ -132,11 +134,11 @@ Configures Edgissary (envoy) to send metrics to the Agent which are then relayed ### `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`). +Configures Emissary to bind its health check server to the provided address. If not set Emissary 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`). +Configures Emissary to bind its health check server to the provided port. If not set Emissary will listen on the admin port(`8877`). ### `AMBASSADOR_HEALTHCHECK_IP_FAMILY` @@ -144,7 +146,7 @@ Allows the IP Family used by health check server to be overriden. By default, th ### `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) @@ -159,7 +161,7 @@ Some (but few) logs from `gunicorn` and the Kubernetes `client-go` package will ### `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 +and port `8006`. `8006` is part of the reserved ports dedicated to Emissary. 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` @@ -169,8 +171,8 @@ 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. +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` @@ -186,58 +188,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) @@ -256,7 +258,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) @@ -310,8 +312,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. @@ -325,7 +327,7 @@ This controls the number of worker threads used to serve requests and can be use ### `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 +In Emissary 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`. @@ -334,7 +336,7 @@ In version `3.2` this bug was fixed and resources that configure a selector will 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. +Emissary 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`. @@ -343,7 +345,7 @@ See The [Host documentation](../../running/host-crd#controlling-association-with ## 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 | |------|----------|---------------------------------------------------------| @@ -351,7 +353,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/3.6/topics/running/gzip.md b/content/en/docs/3.6/topics/running/gzip.md index e3005c83..11f2968c 100644 --- a/content/en/docs/3.6/topics/running/gzip.md +++ b/content/en/docs/3.6/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/3.6/topics/running/host-crd.md b/content/en/docs/3.6/topics/running/host-crd.md index cd187ebe..d8f36182 100644 --- a/content/en/docs/3.6/topics/running/host-crd.md +++ b/content/en/docs/3.6/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` @@ -174,9 +174,9 @@ 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. -> **Note:** In $productName$ version `3.2`, a bug with how `Hosts` are associated with `Mappings` was fixed. The `mappingSelector` field in `Hosts` was not +> **Note:** In Emissary 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`. @@ -184,7 +184,7 @@ In version `3.2` this bug was fixed and a `Host` will only be associated with a 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. +Emissary may remove the ability to opt-out of this bugfix. ## Secure and insecure requests @@ -214,11 +214,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 @@ -226,7 +226,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 @@ -258,21 +258,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/3.6/topics/running/http3.md b/content/en/docs/3.6/topics/running/http3.md index 9aeb6cac..304bf75a 100644 --- a/content/en/docs/3.6/topics/running/http3.md +++ b/content/en/docs/3.6/topics/running/http3.md @@ -1,23 +1,23 @@ --- -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." +title: "HTTP/3 configuration" +description: "Configure HTTP/3 support with Emissary. Create services to handle UDP and TCP traffic and setup HTTP/3 with your cloud service provider." --- -# HTTP/3 in $productName$ +# HTTP/3 in Emissary 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. +Since the QUIC network protocol is built on UDP, most clients will require Emissary 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 Emissary 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. +QUIC requires Transport Layer Security (TLS) version 1.3 to communicate. Otherwise, Emissary 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. +Because HTTP/3 adoption is still growing and and changing, the Emissary team will continue update this documentation as features change and mature. -## Setting up HTTP/3 with $productName$ +## Setting up HTTP/3 with Emissary -To configure $productName$ for HTTP/3 you need to do the following: +To configure Emissary for HTTP/3 you need to do the following: 1. Configure `Listener` resources. 2. Configure a `Host`. @@ -26,13 +26,13 @@ To configure $productName$ for HTTP/3 you need to do the following: ### 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`. +To make Emissary 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 `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 Emissary 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. diff --git a/content/en/docs/3.6/topics/running/index.md b/content/en/docs/3.6/topics/running/index.md deleted file mode 100644 index 6eb7af94..00000000 --- a/content/en/docs/3.6/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.6/topics/running/ingress-controller.md b/content/en/docs/3.6/topics/running/ingress-controller.md index 9b7afb82..82e17a0b 100644 --- a/content/en/docs/3.6/topics/running/ingress-controller.md +++ b/content/en/docs/3.6/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/3.6/topics/running/listener.md b/content/en/docs/3.6/topics/running/listener.md index 152e1b74..b79a4a7a 100644 --- a/content/en/docs/3.6/topics/running/listener.md +++ b/content/en/docs/3.6/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/3.6/topics/running/load-balancer.md b/content/en/docs/3.6/topics/running/load-balancer.md index 987a910b..07b45d01 100644 --- a/content/en/docs/3.6/topics/running/load-balancer.md +++ b/content/en/docs/3.6/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/3.6/topics/running/resolvers.md b/content/en/docs/3.6/topics/running/resolvers.md index 1ace9a86..1d725b29 100644 --- a/content/en/docs/3.6/topics/running/resolvers.md +++ b/content/en/docs/3.6/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/3.6/topics/running/running.md b/content/en/docs/3.6/topics/running/running.md index a28b0cb5..5b8d2a57 100644 --- a/content/en/docs/3.6/topics/running/running.md +++ b/content/en/docs/3.6/topics/running/running.md @@ -1,20 +1,22 @@ -# Running and deployment +--- +title: 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 +43,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 +59,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 +81,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 +95,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 +114,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 +128,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 +136,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 +178,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,48 +198,48 @@ 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.** ## 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: @@ -247,17 +249,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 | | :------------------------ | :---- | :------------------------ | @@ -273,17 +275,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 | @@ -306,7 +308,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'? | @@ -329,10 +331,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/3.6/topics/running/scaling.md b/content/en/docs/3.6/topics/running/scaling.md index 22fa743e..1364e14b 100644 --- a/content/en/docs/3.6/topics/running/scaling.md +++ b/content/en/docs/3.6/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/3.6/topics/running/services/_index.md b/content/en/docs/3.6/topics/running/services/_index.md new file mode 100644 index 00000000..e2f6d1b7 --- /dev/null +++ b/content/en/docs/3.6/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/3.6/topics/running/services/auth-service.md b/content/en/docs/3.6/topics/running/services/auth-service.md index adfb77e4..ec913b9f 100644 --- a/content/en/docs/3.6/topics/running/services/auth-service.md +++ b/content/en/docs/3.6/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`. @@ -95,7 +95,7 @@ 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. | +| `protocol_version` | `v3` | Allowed values are `v3` and `v2`(defualt). `protocol_version` was used in previous versions of Emissary to control the protocol used by the gRPC service. Emissary 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`. @@ -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/3.6/topics/running/services/ext-authz.md b/content/en/docs/3.6/topics/running/services/ext-authz.md index d850ba4b..6649d940 100644 --- a/content/en/docs/3.6/topics/running/services/ext-authz.md +++ b/content/en/docs/3.6/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/3.6/topics/running/services/index.md b/content/en/docs/3.6/topics/running/services/index.md deleted file mode 100644 index 1646aa5a..00000000 --- a/content/en/docs/3.6/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.6/topics/running/services/log-service.md b/content/en/docs/3.6/topics/running/services/log-service.md index b3e90c7c..7760e7aa 100644 --- a/content/en/docs/3.6/topics/running/services/log-service.md +++ b/content/en/docs/3.6/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 @@ -75,7 +77,7 @@ spec: [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. + - `protocol_version` was used in previous versions of Emissary to control the gRPC service name used to communicate with the `LogService`. Emissary 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 @@ -96,7 +98,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/3.6/topics/running/services/rate-limit-service.md b/content/en/docs/3.6/topics/running/services/rate-limit-service.md index 39c2b0ce..8e408d18 100644 --- a/content/en/docs/3.6/topics/running/services/rate-limit-service.md +++ b/content/en/docs/3.6/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 `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 +limit service, Ambassador Edge Stack 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 +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 @@ -88,31 +90,31 @@ 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` 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. +- `protocol_version` Allowed values are `v3` and `v2`(default). `protocol_version` was used in previous versions of Emissary to control the protocol used by the gRPC service to communicate with the `RateLimitService`. Emissary 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 +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/3.6/topics/running/services/tracing-service.md b/content/en/docs/3.6/topics/running/services/tracing-service.md index b46e6870..a3716dcc 100644 --- a/content/en/docs/3.6/topics/running/services/tracing-service.md +++ b/content/en/docs/3.6/topics/running/services/tracing-service.md @@ -1,12 +1,12 @@ -import Alert from '@material-ui/lab/Alert'; - -# 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 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). +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 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: +A `TracingService` manifest configures Emissary to use an external trace visualization service: ```yaml --- @@ -20,11 +20,11 @@ spec: config: {} custom_tags: # optional - tag: host - request_header: + request_header: name: ":authority" default_value: "unknown" - tag: path - request_header: + request_header: name: ":path" default_value: "unknown" sampling: @@ -47,8 +47,8 @@ Please note that you must use the HTTP/2 pseudo-header names. For example: - 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) +Emissary supports a single Global TracingService which is configured during Envoy bootstrap. Emissary must be restarted for changes to the +TracingService manifest to take affect. If you have multiple instances of Emissary in your cluster, ensure [ambassador_id](../../running#ambassador_id) is set correctly in the TracingService manifest. @@ -61,11 +61,11 @@ The `TracingService` currently supports the following drivers: - `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 Envoy 1.24, support for the LightStep driver was removed. As of Emissary 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. +In Emissary 3.5.0, support for Envoy's native OpenTelemetry driver was added to the TracingService. Envoy still considers this driver experimental. ## Sampling @@ -81,9 +81,9 @@ 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. +When collecting traces, Emissary 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. +Previous versions of Emissary 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. diff --git a/content/en/docs/3.6/topics/running/statistics/8877-metrics.md b/content/en/docs/3.6/topics/running/statistics/8877-metrics.md index 94bd2043..bed60743 100644 --- a/content/en/docs/3.6/topics/running/statistics/8877-metrics.md +++ b/content/en/docs/3.6/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_*`: - - `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`][]. diff --git a/content/en/docs/3.6/topics/running/statistics/index.md b/content/en/docs/3.6/topics/running/statistics/_index.md similarity index 84% rename from content/en/docs/3.6/topics/running/statistics/index.md rename to content/en/docs/3.6/topics/running/statistics/_index.md index ab44009f..e27e7fd2 100644 --- a/content/en/docs/3.6/topics/running/statistics/index.md +++ b/content/en/docs/3.6/topics/running/statistics/_index.md @@ -1,13 +1,16 @@ -# 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, 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 + number of requests that a particular service has received via Emissary. 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. @@ -16,7 +19,7 @@ As an example, here are some interesting statistics to investigate: 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. + that tracks the latency in milliseconds of a given service from Emissary's perspective. ## 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,13 +50,13 @@ 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 as both Envoy metrics and $productName$ control plane + our recommended method as both Envoy metrics and Emissary control plane metrics are collected. -- $productName$ can push [Envoy statistics](./envoy-statsd) over the +- Emissary can push [Envoy statistics](./envoy-statsd) over the StatsD or DogStatsD protocol. ## The Four Golden Signals diff --git a/content/en/docs/3.6/topics/running/statistics/envoy-statsd.md b/content/en/docs/3.6/topics/running/statistics/envoy-statsd.md index 7cbcc208..aa64fec4 100644 --- a/content/en/docs/3.6/topics/running/statistics/envoy-statsd.md +++ b/content/en/docs/3.6/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 [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,12 +66,12 @@ 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. +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: @@ -100,10 +100,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/3.6/topics/running/tls/index.md b/content/en/docs/3.6/topics/running/tls/_index.md similarity index 87% rename from content/en/docs/3.6/topics/running/tls/index.md rename to content/en/docs/3.6/topics/running/tls/_index.md index 850fb5c0..6874d3a7 100644 --- a/content/en/docs/3.6/topics/running/tls/index.md +++ b/content/en/docs/3.6/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/3.6/topics/running/tls/cleartext-redirection.md b/content/en/docs/3.6/topics/running/tls/cleartext-redirection.md index 7144b1a3..d3fd6e38 100644 --- a/content/en/docs/3.6/topics/running/tls/cleartext-redirection.md +++ b/content/en/docs/3.6/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/3.6/topics/running/tls/mtls.md b/content/en/docs/3.6/topics/running/tls/mtls.md index 1b039cf8..f79769c8 100644 --- a/content/en/docs/3.6/topics/running/tls/mtls.md +++ b/content/en/docs/3.6/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/3.6/topics/running/tls/origination.md b/content/en/docs/3.6/topics/running/tls/origination.md index b15dd5f8..1cfa4849 100644 --- a/content/en/docs/3.6/topics/running/tls/origination.md +++ b/content/en/docs/3.6/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/3.6/topics/running/tls/sni.md b/content/en/docs/3.6/topics/running/tls/sni.md index 92e4992f..f32a0c6d 100644 --- a/content/en/docs/3.6/topics/running/tls/sni.md +++ b/content/en/docs/3.6/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.6/topics/using/index.md b/content/en/docs/3.6/topics/using/_index.md similarity index 76% rename from content/en/docs/3.6/topics/using/index.md rename to content/en/docs/3.6/topics/using/_index.md index d4f09a83..a547e1ce 100644 --- a/content/en/docs/3.6/topics/using/index.md +++ b/content/en/docs/3.6/topics/using/_index.md @@ -1,6 +1,11 @@ -# 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. +# Using Emissary + +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/3.6/topics/using/authservice.md b/content/en/docs/3.6/topics/using/authservice.md index cfe3598b..b0a733f0 100644 --- a/content/en/docs/3.6/topics/using/authservice.md +++ b/content/en/docs/3.6/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/3.6/topics/using/rate-limits/index.md b/content/en/docs/3.6/topics/using/basic-rate-limiting.md similarity index 83% rename from content/en/docs/3.6/topics/using/rate-limits/index.md rename to content/en/docs/3.6/topics/using/basic-rate-limiting.md index b65f8c5d..5e512edf 100644 --- a/content/en/docs/3.6/topics/using/rate-limits/index.md +++ b/content/en/docs/3.6/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: {}`. @@ -190,10 +190,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/3.6/topics/using/canary.md b/content/en/docs/3.6/topics/using/canary.md index f99de1a3..b8b44d7f 100644 --- a/content/en/docs/3.6/topics/using/canary.md +++ b/content/en/docs/3.6/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/3.6/topics/using/circuit-breakers.md b/content/en/docs/3.6/topics/using/circuit-breakers.md index 97b40f57..275e00a2 100644 --- a/content/en/docs/3.6/topics/using/circuit-breakers.md +++ b/content/en/docs/3.6/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/3.6/topics/using/cors.md b/content/en/docs/3.6/topics/using/cors.md index 315e4694..1e4c0743 100644 --- a/content/en/docs/3.6/topics/using/cors.md +++ b/content/en/docs/3.6/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/3.6/topics/using/defaults.md b/content/en/docs/3.6/topics/using/defaults.md index d08a84d8..7601bb40 100644 --- a/content/en/docs/3.6/topics/using/defaults.md +++ b/content/en/docs/3.6/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/3.6/topics/using/gateway-api.md b/content/en/docs/3.6/topics/using/gateway-api.md index 5e92cd0d..2ee72327 100644 --- a/content/en/docs/3.6/topics/using/gateway-api.md +++ b/content/en/docs/3.6/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/3.6/topics/using/headers/_index.md b/content/en/docs/3.6/topics/using/headers/_index.md new file mode 100644 index 00000000..57127082 --- /dev/null +++ b/content/en/docs/3.6/topics/using/headers/_index.md @@ -0,0 +1,4 @@ +--- +title: Headers +weight: -10 +--- diff --git a/content/en/docs/3.6/topics/using/headers/add-request-headers.md b/content/en/docs/3.6/topics/using/headers/add-request-headers.md index c6ad4956..a9911079 100644 --- a/content/en/docs/3.6/topics/using/headers/add-request-headers.md +++ b/content/en/docs/3.6/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/3.6/topics/using/headers/add-response-headers.md b/content/en/docs/3.6/topics/using/headers/add-response-headers.md index 236ace61..9bf02050 100644 --- a/content/en/docs/3.6/topics/using/headers/add-response-headers.md +++ b/content/en/docs/3.6/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/3.6/topics/using/headers/headers.md b/content/en/docs/3.6/topics/using/headers/headers.md index 126653b0..1c0a5489 100644 --- a/content/en/docs/3.6/topics/using/headers/headers.md +++ b/content/en/docs/3.6/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/3.6/topics/using/headers/host.md b/content/en/docs/3.6/topics/using/headers/host.md index 5a8dd02c..ba07fea7 100644 --- a/content/en/docs/3.6/topics/using/headers/host.md +++ b/content/en/docs/3.6/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/3.6/topics/using/headers/remove-request-headers.md b/content/en/docs/3.6/topics/using/headers/remove-request-headers.md index 62603756..b5fae6fa 100644 --- a/content/en/docs/3.6/topics/using/headers/remove-request-headers.md +++ b/content/en/docs/3.6/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/3.6/topics/using/headers/remove-response-headers.md b/content/en/docs/3.6/topics/using/headers/remove-response-headers.md index 16b18569..abe9e45a 100644 --- a/content/en/docs/3.6/topics/using/headers/remove-response-headers.md +++ b/content/en/docs/3.6/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/3.6/topics/using/intro-mappings.md b/content/en/docs/3.6/topics/using/intro-mappings.md index 51656052..38dff272 100644 --- a/content/en/docs/3.6/topics/using/intro-mappings.md +++ b/content/en/docs/3.6/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/3.6/topics/using/keepalive.md b/content/en/docs/3.6/topics/using/keepalive.md index d75e96ba..015d7258 100644 --- a/content/en/docs/3.6/topics/using/keepalive.md +++ b/content/en/docs/3.6/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/3.6/topics/using/mappings.md b/content/en/docs/3.6/topics/using/mappings.md index f930fc62..17d34abc 100644 --- a/content/en/docs/3.6/topics/using/mappings.md +++ b/content/en/docs/3.6/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/3.6/topics/using/method.md b/content/en/docs/3.6/topics/using/method.md index 94185dcd..43b36e68 100644 --- a/content/en/docs/3.6/topics/using/method.md +++ b/content/en/docs/3.6/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/3.6/topics/using/prefix-regex.md b/content/en/docs/3.6/topics/using/prefix-regex.md index 04a6e4b8..e7b29c55 100644 --- a/content/en/docs/3.6/topics/using/prefix-regex.md +++ b/content/en/docs/3.6/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/3.6/topics/using/query-parameters.md b/content/en/docs/3.6/topics/using/query-parameters.md index 0bd5eb13..9628c209 100644 --- a/content/en/docs/3.6/topics/using/query-parameters.md +++ b/content/en/docs/3.6/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/3.6/topics/using/redirects.md b/content/en/docs/3.6/topics/using/redirects.md index f55c467d..dadc41b9 100644 --- a/content/en/docs/3.6/topics/using/redirects.md +++ b/content/en/docs/3.6/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/3.6/topics/using/retries.md b/content/en/docs/3.6/topics/using/retries.md index d018ab59..5a417d99 100644 --- a/content/en/docs/3.6/topics/using/retries.md +++ b/content/en/docs/3.6/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/3.6/topics/using/rewrites.md b/content/en/docs/3.6/topics/using/rewrites.md index 44d0a961..0c7060cd 100644 --- a/content/en/docs/3.6/topics/using/rewrites.md +++ b/content/en/docs/3.6/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/3.6/topics/using/shadowing.md b/content/en/docs/3.6/topics/using/shadowing.md index dd95fbba..1a102238 100644 --- a/content/en/docs/3.6/topics/using/shadowing.md +++ b/content/en/docs/3.6/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/3.6/topics/using/tcpmappings.md b/content/en/docs/3.6/topics/using/tcpmappings.md index f246e799..deb98dbc 100644 --- a/content/en/docs/3.6/topics/using/tcpmappings.md +++ b/content/en/docs/3.6/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/3.6/topics/using/timeouts.md b/content/en/docs/3.6/topics/using/timeouts.md index ae004102..0e184811 100644 --- a/content/en/docs/3.6/topics/using/timeouts.md +++ b/content/en/docs/3.6/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/3.6/tutorials/_index.md b/content/en/docs/3.6/tutorials/_index.md new file mode 100644 index 00000000..bc896d9b --- /dev/null +++ b/content/en/docs/3.6/tutorials/_index.md @@ -0,0 +1,4 @@ +--- +title: Tutorials +weight: 40 +--- diff --git a/content/en/docs/3.6/tutorials/dev-portal-tutorial.md b/content/en/docs/3.6/tutorials/dev-portal-tutorial.md deleted file mode 100644 index d3c0d0a8..00000000 --- a/content/en/docs/3.6/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.6/tutorials/getting-started.md b/content/en/docs/3.6/tutorials/getting-started.md index 1fb11cec..6971739e 100644 --- a/content/en/docs/3.6/tutorials/getting-started.md +++ b/content/en/docs/3.6/tutorials/getting-started.md @@ -1,12 +1,12 @@ --- -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..." +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 +# Emissary quick start

Contents

@@ -20,7 +20,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. @@ -28,7 +28,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. @@ -40,11 +40,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: @@ -81,7 +81,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**. @@ -112,14 +112,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/ @@ -138,19 +138,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/3.6/tutorials/gs-tabs.js b/content/en/docs/3.6/tutorials/gs-tabs.js deleted file mode 100644 index c9931553..00000000 --- a/content/en/docs/3.6/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' + - '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.6/tutorials/gs-tabs2.js b/content/en/docs/3.6/tutorials/gs-tabs2.js deleted file mode 100644 index bfd95047..00000000 --- a/content/en/docs/3.6/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.6/tutorials/quickstart-demo.md b/content/en/docs/3.6/tutorials/quickstart-demo.md index 70cbce8b..5aab30c7 100644 --- a/content/en/docs/3.6/tutorials/quickstart-demo.md +++ b/content/en/docs/3.6/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/3.6/versions.yml b/content/en/docs/3.6/versions.yml deleted file mode 100644 index 3f57e554..00000000 --- a/content/en/docs/3.6/versions.yml +++ /dev/null @@ -1,35 +0,0 @@ -# branch info -branch: release/v3.6 - -# self -version: 3.6.0 -productName: "Emissary-ingress" -productNamePlural: "Emissary-ingresses" -productNamespace: emissary -productDeploymentName: emissary-ingress -productHelmName: emissary-ingress - -# OSS (self) -ossVersion: 3.6.0 -ossDocsVersion: "3.6" -ossChartVersion: 8.6.0 -OSSproductName: "Emissary-ingress" -OSSproductNamePlural: "Emissary-ingresses" - -# AES (not self) -aesVersion: 3.6.0 -aesDocsVersion: "3.6" -aesChartVersion: 8.6.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.5.1 -chartVersionTwoX: 7.6.1 -versionOneX: 1.14.4 -chartVersionOneX: 6.9.5 diff --git a/content/en/docs/3.7/howtos/http3-eks.md b/content/en/docs/3.7/howtos/http3-eks.md index 2c9f03ad..212f0780 100644 --- a/content/en/docs/3.7/howtos/http3-eks.md +++ b/content/en/docs/3.7/howtos/http3-eks.md @@ -6,8 +6,7 @@ description: "How to configure HTTP/3 support for Amazon Elastic Kubernetes Serv 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 Emissary](../../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. +The virtual private cloud (VPC) for your load balancer needs one public subnet in each availability zone where you have targets. ```shell SUBNET_IDS=( ) @@ -71,7 +70,7 @@ Run the following command with the variables for your VPC ID and cluster name: ## Register your instances -Next, register your cluster's instance with the the instance IDs and Amazon Resource Names (ARN). +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 diff --git a/content/en/docs/3.7/howtos/rate-limiting-tutorial.md b/content/en/docs/3.7/howtos/rate-limiting-tutorial.md index bf718042..60215764 100644 --- a/content/en/docs/3.7/howtos/rate-limiting-tutorial.md +++ b/content/en/docs/3.7/howtos/rate-limiting-tutorial.md @@ -1,6 +1,6 @@ -import Alert from '@material-ui/lab/Alert'; - -# Basic rate limiting +--- +title: Basic Rate Limiting +--- This guide applies to Emissary. It will not work correctly on Ambassador Edge Stack.