Skip to content

An Intro to Ambassador

In the Cloud Native world, the use of proxies is growing in popularity. One such use-case for a proxy is to support API gateway functionality. Ambassador is one of these API gateways. Read on to learn more!

What is Ambassador?

Ambassador is an open-source API gateway based on the Envoy proxy and meant for k8s environments. It was created by the Datawire team to support primarily North/South traffic within a distributed architecture running on k8s. Ambassador is a configuration wrapper for Envoy. It was created because native Envoy configuration is hard to understand and configure properly.


Different Ambassador instances can run within an environment by specifying different IDs. For example, from a deployment.yaml:

Configuration is done via annotations in k8s. Here is an example of a mapping:

Note, prior to version 0.50.0, configuration could also be done via configmaps, but this is no longer supported.

Ambassador can be configured to route authentication traffic to a dedicated authentication service. If this is configured then EVERY call goes to the authentication service first and must return a status code of 200 before being routed downstream:

Given Ambassador is based on Envoy, it supports the majority of features that Envoy does. This includes things like tracing:

From a monitoring perspective, statsd is supported and can be converted to Prometheus format (from a deployment.yaml):

A Grafana dashboard exists specifically for Ambassador:


After using Ambassador for a while I figured I would share some gotchas I have experienced along the way:

  • If configuration is not working ensure the proper ambassador_id is specified and any configuration names are unique (e.g. if you have multiple mappings)
  • If you are using configmaps you should be moving off. In any case, any changes to a configmap requires a restart of all impacted Ambassador pods to take effect.
  • If things are not working and you cannot track it down use the diagnostics page — the UI will highlight issues and in worst case debug logging will usually help pinpoint the issue.
  • If it is not in the documentation do not expect it to work — while Ambassador is based on Envoy and certain Envoy overrides can be applied, they are limited at best. If what you are trying to do is not in the documentation then it is unlikely to be available or supported.
  • I have run into issues where upgrading a deployment (not service) results in gateway timeouts — the workaround is to kick the impacted Ambassador pods (issue appears to be routing to non-existing pods).


If you are look for an API gateway optimized for north/south traffic on k8s then Ambassador is a solid choice. Ambassador is based on the production ready Envoy proxy and offers many of the same features. The latest information about Ambassador, check the documentation.

© 2019 – 2018, Steve Flanders. All rights reserved.

Published inCloud NativeSystem Administration

Be First to Comment

    Leave a Reply

    Your email address will not be published. Required fields are marked *