How-to guides on

Active Health Checking

Mon, 01 Jan 0001 00:00:00 +0000

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. 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 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.

Basic Authentication

Mon, 01 Jan 0001 00:00:00 +0000

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 Emissary tutorial.

Before you get started

This tutorial assumes you have already followed the Emissary Installation guide. If you haven’t done that already, you should do so now.

Once complete, you’ll have a Kubernetes cluster running Emissary. Let’s walk through adding authentication to this setup.

Client certificate validation

Mon, 01 Jan 0001 00:00:00 +0000

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, 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 Emissary and the client provide and validate each other’s certificates.

Prerequisites

openssl For creating client certificates
kubectl
Emissary
cURL

Configuration

Create a certificate and key.

Configuring Emissary Communications

Mon, 01 Jan 0001 00:00:00 +0000

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, 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. Hosts can be associated with one or more Listeners.
TLSContext: defines whether, and how, Emissary will manage TLS certificates and options. TLSContexts can be associated with one or more Hosts.

Once the basic communications setup is in place, Emissary Mappings and TCPMappings can be associated with Hosts to actually do routing.

Consul integration

Mon, 01 Jan 0001 00:00:00 +0000

Consul integration

Consul is a widely used service mesh. Emissary natively supports service discovery and unauthenticated communication to services in Consul. Additionally, the Ambassador Consul Connector enables Emissary to encrypt and authenticate its communication via mTLS with services in Consul that make use of Consul’s Connect feature.

Architecture overview

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 Emissary to securely route over TLS to any application regardless of where it is deployed.

Developing custom filters for routing

Mon, 01 Jan 0001 00:00:00 +0000

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

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.

Distributed Tracing

Mon, 01 Jan 0001 00:00:00 +0000

The Kubernetes monitoring and distributed tracing landscape is hard to grasp. Although this conceptual approach to observability is nothing new — companies like New Relic revolutionized single-application performance monitoring (APM) over a decade ago — it took a few years and the Dapper publication for this idea to migrate to distributed applications. The importance of this technology is only increasing, as more and more of us are building deep systems.

As the industry is slowly but surely maturing, standardization is underway. Standardization means proprietary vendor solutions and open source projects are able to collaborate, making our lives easier. For newcomers, understanding the plethora of options, concepts, specifications, and implementations available is still a daunting task:

Distributed Tracing with Datadog

Mon, 01 Jan 0001 00:00:00 +0000

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 Emissary 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 Emissary and the Quote service. Let’s walk through adding tracing to this setup.

Distributed Tracing with OpenTelemetry and Dash0

Mon, 01 Jan 0001 00:00:00 +0000

In this tutorial, we’ll configure Emissary to initiate a trace on some sample requests, collect them with the OpenTelemetry Collector and use Dash0 to visualize them.

Before you get started

This tutorial will walk you through setting up Emissary with distributed tracing using Dash0. We’ll use a local kind cluster for this guide.

First, create a kind cluster:

kind create cluster --name emissary

Then follow the Quick Start guide to install Emissary and the Faces demo application. After completing those steps, you’ll have a Kubernetes cluster running Emissary and the Faces demo. Now let’s add distributed tracing to this setup.

Distributed Tracing with OpenTelemetry and Lightstep

Mon, 01 Jan 0001 00:00:00 +0000

In this tutorial, we’ll configure Emissary 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 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 Emissary Getting Started guide. If you haven’t done that already, you should do that now.

Distributed tracing with Zipkin

Mon, 01 Jan 0001 00:00:00 +0000

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 Emissary 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 Emissary and the Quote service. Let’s walk through adding tracing to this setup.

ExternalDNS

Mon, 01 Jan 0001 00:00:00 +0000

ExternalDNS configures your existing DNS provider to make Kubernetes resources discoverable via public DNS servers by getting resources from the Kubernetes API to create a list of DNS records.

Getting started

Prerequisites

Start by checking the ExternalDNS repo’s deployment instructions to get information about the supported DNS providers and steps to setup ExternalDNS for your provider. Each DNS provider will have its own required steps as well as annotations, arguments, and permissions needed for the following configuration.

gRPC

Mon, 01 Jan 0001 00:00:00 +0000

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.

HTTP/3 support for Azure Kubernetes Service (AKS)

Mon, 01 Jan 0001 00:00:00 +0000

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 documentation.

Configuring an external load balancer for AKS

To configure an external load balancer for AKS, you need to:

Reserve a public static IP address.
Create two LoadBalancer services, one for TCP and one for UDP.
Assign the public static IP address to the loadBalancerIP field.

An example of the two load balancer services described above looks as follows:

HTTP/3 support for Google Kubernetes Engine (GKE)

Mon, 01 Jan 0001 00:00:00 +0000

This guide shows how to setup HTTP/3 support for Google Kubernetes Engine (GKE). The instructions provided in this page are a continuation of the HTTP/3 in Emissary documentation.

Configuring an external load balancer for GKE

Currently, GKE only supports adding feature flags to alpha clusters, and doesn’t support the creation of mixed protocol services of type LoadBalancer. To configure an external load balancer for GKE, you need to:

Reserve a public static IP address.
Create two LoadBalancer services, one for TCP and one for UDP.
Assign the public static IP address to the loadBalancerIP field.

An example of the two load balancer services described above looks as follows:

HTTP/3 with Amazon Elastic Kubernetes Service (EKS) | Emissary

Mon, 01 Jan 0001 00:00:00 +0000

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 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.

SUBNET_IDS=(<your-subnet1-id> <your-subnet2-id> <your-subnet3-id>)

aws elbv2 create-load-balancer \
  --name ${CLUSTER_NAME}-nlb \
  --type network \
  --subnets ${SUBNET_IDS}

Create a NodePort service

Now create a NodePort service for Emissary installation with two entries. Use port: 443 to include support for both TCP and UDP traffic.

Istio

Mon, 01 Jan 0001 00:00:00 +0000

Emissary and Istio: Edge Proxy and Service Mesh together in one. Emissary is deployed at the edge of your network and routes incoming traffic to your internal services (aka “north-south” traffic). Istio is a service mesh for microservices, and is designed to add application-level Layer (L7) observability, routing, and resilience to service-to-service traffic (aka “east-west” traffic). Both Istio and Emissary are built using Envoy.

Emissary and Istio can be deployed together on Kubernetes. In this configuration, Emissary manages traditional edge functions such as authentication, TLS termination, and edge routing. Istio mediates communication from Emissary to services, and communication between services.

Knative

Mon, 01 Jan 0001 00:00:00 +0000

Knative is a popular Kubernetes-based platform for managing serverless workloads with two main components:

Eventing: Management and delivery of events
Serving: Request-driven compute that can scale to zero

We will be focusing on Knative Serving, which builds on Kubernetes to support deploying and serving of serverless applications and functions.

Ambassador can watch for changes in Knative configuration in your Kubernetes cluster and set up routing accordingly.

Note: Knative was originally built with Istio handling cluster networking. This integration lets us replace Istio with Ambassador, which will dramatically reduce the operational overhead of running Knative.

Linkerd 2

Mon, 01 Jan 0001 00:00:00 +0000

Linkerd 2 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.

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.

Mapping resource

Mon, 01 Jan 0001 00:00:00 +0000

Get traffic from the edge

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 Emissary installation that can route traffic!
Learn more about Listener.
Learn more about Host.

Examples

This Mapping would route requests to https://<hostname>/webapp/ to the webapp-svc Service. This is not a complete example on its own; see below.

Monitoring with Prometheus and Grafana

Mon, 01 Jan 0001 00:00:00 +0000

Prometheus is an open-source monitoring and alerting system. When used along with Grafana, you can create a dynamic dashboard for monitoring ingress into our Kubernetes cluster.

Deployment

This guide will focus on deploying Prometheus and Grafana alongside Emissary in Kubernetes using the 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.

Protecting Access to the Diagnostics Interface

Mon, 01 Jan 0001 00:00:00 +0000

Out of the box, Emissary enables Mappings 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 Emissary to follow.

Rate Limiting Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

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.)

Before you get started

This tutorial assumes you have already followed the Emissary Installation and Quickstart Tutorial guides. If you haven’t done that already, you should do so now.

TLS Termination and Enabling HTTPS

Mon, 01 Jan 0001 00:00:00 +0000

TLS encryption is one of the basic requirements of having a secure system. Ambassador Edge Stack automatically enables TLS termination/HTTPs , making TLS encryption easy and centralizing TLS termination for all of your services in Kubernetes.

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.

Using cert-manager

Mon, 01 Jan 0001 00:00:00 +0000

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 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.

WebSockets

Mon, 01 Jan 0001 00:00:00 +0000

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 the “websocket” protocol:

allow_upgrade:
- websocket

Example WebSocket service

The example configuration below demonstrates the addition of the allow_upgrade: attribute to support websockets. The use of use_websocket is now deprecated.

How-to guides on

Active Health Checking

Basic Authentication

Before you get started

Client certificate validation

Prerequisites

Configuration

Configuring Emissary Communications

Consul integration

Contents

Architecture overview

Developing custom filters for routing

Distributed Tracing

Distributed Tracing with Datadog

Before you get started

Distributed Tracing with OpenTelemetry and Dash0

Before you get started

Distributed Tracing with OpenTelemetry and Lightstep

Before you get started

Distributed tracing with Zipkin

Before you get started

ExternalDNS

Getting started

Prerequisites

gRPC

HTTP/3 support for Azure Kubernetes Service (AKS)

Configuring an external load balancer for AKS

HTTP/3 support for Google Kubernetes Engine (GKE)

Configuring an external load balancer for GKE

HTTP/3 with Amazon Elastic Kubernetes Service (EKS) | Emissary

Create a network load balancer (NLB)

Create a NodePort service

Istio

Knative

Linkerd 2

Architecture

Mapping resource

Get traffic from the edge

Contents

Examples

Monitoring with Prometheus and Grafana

Deployment

Protecting Access to the Diagnostics Interface

Rate Limiting Tutorial

Before you get started

TLS Termination and Enabling HTTPS

Using cert-manager

WebSockets

Example WebSocket service