Ambassador 0.50 GA Release Notes: SNI, New AuthService and Envoy v2 Support

We are pleased to announce the GA release of Ambassador 0.50, with the headline features of Server Name Indication (SNI) support, more powerful rate limiting semantics, and a new AuthService. This release includes a major re-architecture under the hood that adds support for the Envoy Proxy v2 API and also uses the Aggregate Discovery Service (ADS) functionality, which removes the need for hot restarts.

We are extremely grateful for everyone who contributed to this release, and also those who offered feedback via GitHub and our Slack. We are constantly impressed by the community emerging around Ambassador and Envoy, and we have enjoyed talking to you many of you at KubeCon and other community events.

Let’s explore the latest release of Ambassador 0.50 in more detail.

Headline Features

Ambassador 0.50 includes several headline new features that are now ready for production use:

• Support for Server Name Indication (SNI) (issue #153), which allows the configuration of multiple TLS certificates where different domain names are used within the same Ambassador instance. Similar to other Ambassador functionality, we are enabling SNI to be configured on a per-mapping basis, with a separate global configuration that loads the necessary TLS certificates.
• Ambassador now supports “request labels” that adds metadata to requests that can be used for advanced rate limiting use case. This deprecates the existing rate_limits functionality. Request labels are currently being used as a highly flexible mechanism for annotating requests for a third party rate limiting service, but in the future they can also be used to allow grouping and selection of requests within other functionality. The integrated Ambassador Pro rate limiting service takes advantage of request labels to provide flexible rate limiting.
• Improved support for statsd for statistics gathering. The new statsd approach eliminates the use of socat as a sidecar process, and should be much more friendly do your Kubernetes DNS setup.
• Zero downtime configuration changes. Previously, Ambassador relied on Envoy’s hot restart to drain connections and restart, creating a narrow window of suboptimal performance during configuration changes. Ambassador 0.50 uses Envoy’s Aggregated Discovery Service API, eliminating any need for connection draining on configuration changes.
• Support for certificate reload. Previously, Ambassador required you to manually restart when certificates change. Now, Ambassador will detect when a certificate has changed and automatically reload the new certificate.

There have been several major architectural enhancements with this version of Ambassador, which are detailed later in this blog post, but the end-user results include:

• Officially introducing the new ambassador/v1 YAML configuration, and deprecating the ambassador/v0 configuration (Note that the v0 configuration will be fully deprecated in 0.50 GA.) Ambassador now uses Envoy’s v2 configuration, which allows us to support many commonly requested features such as SNI and gzip compression, but this also means a limited number of Ambassador configurations had to change in way that wasn’t backwards compatible.
• Ambassador has vastly improved connection draining semantics under load e.g. > 1000 requests per second. This is because this version of Ambassador uses Envoy’s Aggregated Discovery Service (ADS) API for configuration changes, instead of the previous hot restart mechanism. ADS not only allows configuration to be updated dynamically, but also the appropriate sequencing of the underlying Envoy CDS/EDS/RDS API configurations to be specified to prevent errors and prevent traffic dropping.

Minor Features

In addition to the headline upgrades, several other highly requested features have been added:

• Response headers can now be added to any response served by using the add_response_headers property (with thanks to Niko Kurtti)
• Support for both gRPC & REST authentication services has been added, and the message body can now be passed to this service, for example, to implement for Hash-based Message Authentication Code (HMAC) checking.
• Support for bypassing authentication has been added, letting you bypass the AuthService when the bypass_auth flag is set on a Mapping.
• We strongly recommend using API version ambassador/v1 for all AuthService resources, so that you can fully configure whether the request body and which headers are allowed from the client to the AuthService, and also which headers are sent from the upstream upon successful authentication.
• Using API version ambassador/v0, Ambassador will attempt to preserve old behavior as documented in docs/reference/services/auth-service.md, but you may very well find that you need to shift to API version ambassador/v1 to fully support your authentication system.
• External authentication now uses the core Envoy envoy.ext_authz filter, rather than the custom Datawire auth filter. Ext_authz is based on the original Datawire ext_auth protocol (we’ve just upstreamed our development work). Your existing external auth services should work, however there are a few caveats (see breaking changes below).
• Zipkin TracingService configuration now supports 128-bit trace IDs and shared span contexts, and Zipkin should correctly trace calls to external auth services (thanks to Alexandre Gervais)
• The diagnostics service JSON has been improved to support filtering, e.g., requests to /ambassador/v0/diag/?json=true&filter=errors will only return the errors element from the diagnostic output.
• Ambassador sends additional anonymized usage data to help Datawire prioritize bug fixes, etc. See Running Ambassador for more information, including how to disable this function.

Architecture Changes: Firm Foundations for the Future

The addition of all these new features and functionality required the switch to using the Envoy v2 configuration and ADS APIs under the hood of Ambassador. This has resulted in the following architecture changes:

• Ambassador now uses Envoy’s v2 configuration, instead of the v1 configuration. This enables Ambassador to take full advantage of Envoy’s latest features and configuration.
• Redesigned the Intermediate Representation (IR) used in Ambassador. The new IR is designed to be much more flexible in generating configuration, and it currently supports generating both v1 and v2 Envoy configuration. Should Envoy change its configuration format in the future, we’ll be in a much better place to support it. Moreover, the new IR also makes configuration validation and error reporting much easier.
• Switched to passing the configuration information through the ADS, instead of hot restart. This means that configuration changes happen without a proxy restart, reducing the impact on existing connections. Hot restart is typically very reliable, but introduced a narrow window where existing clients get suboptimal performance when the proxy restarts.
• We’ve also introduced a new test suite, the Kubernetes Acceptance Testing (KAT) tool. The new test suite automatically generates multiple configuration permutations with a single test. Moreover, it runs much faster and more reliably than the old test suite, improving our “inner loop” development.
• Ambassador now uses mypy static type checking extensively, improving debuggability and code maintenance.
• Ambassador now uses the Kubernetes Golang client libraries, instead of the Python libraries. The Golang libraries are better maintained, with better support for Kubernetes features and bug fixes. This particular change was driven by issues with Ambassador on Azure Kubernetes Service (#1039).

There are several more minor updates, and a full list of changes can be found in the CHANGELOG.md within the Ambassador GitHub repository.

Breaking Changes and Issues

All of these enhancements and architectural changes have resulted in some difficult decisions in relation to our goal of supporting backwards compatibility. After community discussion and feedback we have settled on the following breaking changes:

• You can no longer configure Ambassador with a ConfigMap
• API version ambassador/v0 is officially deprecated. Some ambassador/v1 resources change semantics from their ambassador/v0 versions:
• The Mapping resource no longer supports rate_limits as that functionality has been subsumed by labels.
• The AuthService resource supports more extensive configuration options. An ambassador/v0 AuthService preserves the older, less flexible semantics: see below for more.
• The RateLimitService permits configuring its domain in ambassador/v1.
• The little used authentication Module is no longer supported, and instead the AuthService resource must be used
• External authentication with AuthService now uses the Envoy core ext_authz filter. If you are using a custom external authentication service, ext_authz speaks the same HTTP protocol, and your service will continue to work. If your custom filter sent all HTTP headers to the external authentication service, ext_authz does not. You will need to configure the AuthService with the set of headers you wish to send to your external authentication service. In addition, ext_authz does authenticate OPTIONS requests
• Ambassador explicitly requires a TLS Module to enable TLS termination. Previous versions of Ambassador would automatically enable TLS termination if a Kubernetes secret named ambassador-certs was present. 0.50.0 will not. The following configuration will give you the same behavior:

---
kind: Module
name: tls
config:
 server:
   secret: ambassador-certs

By default, use_remote_address is now True (issue #933). If you need the old behavior, you will need to manually set use_remote_address to false in the ambassador Module. This means that Ambassador will append to the X-Forwarded-For header by default.

Deploying Ambassador 0.50 GA

The documented installation methods will now install and run Ambassador 0.50 GA by default. You can find more information about Ambassador installation options in the documentation, and you can ask any questions you may have on our Slack or raise issues via GitHub.