The Ambassador API Gateway serves as an open-source, Kubernetes-native API Gateway, Layer 7 load balancer, and Kubernetes Ingress controller, all engineered atop the high-performance Envoy Proxy. By leveraging the underlying capabilities of Envoy, Ambassador provides a robust mechanism to expose, secure, and manage traffic directed toward Kubernetes microservices, regardless of the specific type of service being deployed. The system is fundamentally designed around the core philosophies of self-service—which facilitates GitOps-style management—and comprehensiveness, ensuring it can integrate seamlessly with a wide array of technology solutions and architectural situations.
Architecture and Fundamental Design
Ambassador functions as a critical entry point for north-south traffic, acting as the bridge between external clients and internal Kubernetes microservices. At its core, it deploys the Envoy Proxy to handle Layer 7 (L7) traffic management. This architectural choice allows Ambassador to move beyond the limitations of standard ingress controllers by providing a comprehensive superset of functionality, including traditional routing layered with a vast array of advanced configuration options.
The system relies heavily on the Kubernetes ecosystem for its own scaling and resilience. Rather than implementing a separate management plane for scaling, Ambassador utilizes Kubernetes' inherent orchestration capabilities to ensure high availability and performance. Configuration is primarily handled through Kubernetes annotations, allowing developers to define routing and policy behavior directly within their resource manifests.
Core Capabilities and Functional Layers
Ambassador provides a multifaceted approach to traffic management, security, and observability.
Traffic Management and Routing
Ambassador manages ingress traffic by providing sophisticated load balancing and extensive protocol support.
- Protocol Support: The gateway supports gRPC, HTTP/2, TCP, and web sockets, ensuring that modern microservices using streaming or binary protocols can be exposed without compatibility issues.
- Routing Configuration: Changes to routing are managed via a declarative policy engine. This allows for self-service configuration utilizing either Kubernetes Custom Resource Definitions (CRDs) or annotations.
- Progressive Delivery: The system enables canary releases, allowing operators to shift traffic gradually to new versions of a service to mitigate the risk of deployment failures.
- Service Preview: Ambassador allows for the setup of shared development environments through Service Preview, facilitating faster iteration cycles for developers.
Security and Reliability
Securing the perimeter of a Kubernetes cluster is a primary function of the Ambassador API Gateway.
- Authentication and Authorization: Microservices are secured through integrated authentication mechanisms and custom request filters.
- Traffic Control: The gateway implements rate limiting to prevent service exhaustion and protect against denial-of-service attacks.
- Encryption: Support for TLS and automatic HTTPS ensures that data in transit is encrypted.
- High Availability: To maintain system stability, Ambassador employs sticky sessions, circuit breaking, and rate limiting, which prevents a single failing service from cascading into a total system failure.
Observability and Integration
Ambassador is designed to plug into existing observability stacks to provide deep insights into traffic patterns.
- Metrics Integration: The gateway leverages integrations with Prometheus, Grafana, and Datadog, providing comprehensive metrics support.
- Developer Onboarding: A dedicated Developer Portal is available to streamline the process of onboarding new developers to the API ecosystem.
- Serverless Integration: Ambassador provides integration with Knative, enabling the management of serverless workloads within the cluster.
Deployment Ecosystems and Tools
Ambassador can be deployed across a vast array of Kubernetes distributions and environments using various installation methods.
Distribution Support
The Ambassador API Gateway is compatible with numerous Kubernetes distributions, including:
- Cloud Service Providers: AKS (Azure Kubernetes Service), EKS (Amazon Elastic Kubernetes Service), and GKE (Google Kubernetes Engine).
- Local and Sandbox Environments: Minikube and kind.
Installation Methodologies
Users have multiple paths to install and configure Ambassador depending on their specific needs:
- Helm: Ambassador can be installed via Helm, providing a standardized package management approach for Kubernetes.
- Kubernetes Initializer: This tool, built by Ambassador Labs, allows for the rapid deployment of sandbox environments. It can deploy Ambassador alongside other platforms such as Prometheus, Jaeger, and Consul. For cloud providers, the initializer generates the necessary YAML to create LoadBalancers, supporting both Layer 4 and Layer 7 load balancer types.
- MicroK8s Addon: In specific versions of MicroK8s, Ambassador is available as a built-in add-on.
MicroK8s Integration and Lifecycle
The integration of Ambassador within MicroK8s provides a streamlined experience for local development, although it is subject to specific versioning and hardware constraints.
Version Availability
Ambassador is available as an add-on in the following MicroK8s versions:
- MicroK8s 1.19
- MicroK8s 1.20
- MicroK8s 1.21
- MicroK8s 1.22
- MicroK8s 1.23
It is critical to note that Ambassador was removed from MicroK8s in version 1.24 and all subsequent releases.
Enabling and Configuring the Add-on
To activate the Ambassador API Gateway in a supported MicroK8s environment, the following command is used:
microk8s enable ambassador
Once enabled, the gateway is ready to serve traffic. However, Ambassador employs a specific filtering mechanism for Ingress resources. It will only serve Ingress resources that contain the following annotation:
kubernetes.io/ingress.class: ambassador
If this annotation is missing, the Ingress resource is ignored by the Ambassador controller.
Implementation Example
The following configuration demonstrates the deployment of a simple application, a service to expose it, and an Ambassador Ingress resource to route external traffic to that service.
```yaml
cat<
kind: Pod
apiVersion: v1
metadata:
name: foo-app
labels:
app: foo
spec:
containers:
- name: foo-app
image: hashicorp/http-echo:0.2.3
args:
- "-text=foo"
kind: Service
apiVersion: v1
metadata:
name: foo-service
spec:
selector:
app: foo
ports:
- port: 5678
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: example-ingress
annotations:
kubernetes.io/ingress.class: ambassador
spec:
rules:
- http:
paths:
- path: /foo
backend:
serviceName: foo-service
servicePort: 5678
EOF
```
To verify that the ingress is functioning correctly, a curl request can be sent to the local endpoint:
curl localhost/foo
This request should return the output foo.
Known Constraints and Issues in MicroK8s
The MicroK8s implementation of Ambassador has encountered several technical hurdles related to hardware and API evolution.
- Hardware Limitations: Ambassador is not supported on ARM or Raspberry Pi deployments.
- API Version Conflicts: In MicroK8s version 1.23, users have reported errors when enabling the add-on due to mismatches in CustomResourceDefinition (CRD) versions. Specifically, errors occur when the system tries to recognize
https://github.com/datawire/ambassador-operator/releases/latest/download/ambassador-operator-crds.yaml because no matches are found for kind CustomResourceDefinition in version apiextensions.k8s.io/v1beta1.
- Deprecation Warnings: In MicroK8s 1.21, the system may issue warnings stating that
apiextensions.k8s.io/v1beta1 CustomResourceDefinition is deprecated in v1.16+ and unavailable in v1.22+, recommending the use of apiextensions.k8s.io/v1 CustomResourceDefinition.
Service Mesh and Third-Party Integrations
Ambassador is designed to function as the north-south gateway for various service meshes, providing the necessary bridge between external clients and the internal mesh proxies.
Consul Integration
HashiCorp Consul integrates with Ambassador to ensure secure routing of ingress traffic into the Consul service mesh. This is particularly critical when:
- Onboarding new applications onto a service mesh.
- Integrating existing applications that reside outside of the mesh.
In these scenarios, Ambassador acts as the API Gateway that routes incoming traffic to Consul service mesh proxies. This integration allows the infrastructure to combine the service discovery and mesh capabilities of Consul with the advanced API Gateway features of Ambassador, such as authentication and rate limiting.
Mesh Compatibility
Beyond Consul, Ambassador is capable of connecting to other prominent service meshes, including:
- Linkerd
- Istio
Ambassador API Gateway vs. Ambassador Edge Stack
While the Ambassador API Gateway is an open-source project, there is a commercial superset known as the Ambassador Edge Stack.
Comparative Analysis
The following table outlines the differences between the open-source API Gateway and the Edge Stack.
Feature
Ambassador API Gateway (OSS)
Ambassador Edge Stack
Core Engine
Envoy Proxy
Envoy Proxy
L7 Load Balancing
Included
Included
Kubernetes Ingress
Included
Included
OAuth/OpenID Connect
Not Included
Included
Advanced Rate Limiting
Basic
Advanced
Swagger/OpenAPI Support
Not Included
Included
Automatic TLS (ACME)
Not Included
Integrated Support
User Interface (UI)
Not Included
Included
The Edge Stack is positioned as a comprehensive solution for enterprises requiring advanced security, automated certificate management, and a visual management interface.
Summary of Technical Specifications
The following table summarizes the technical properties and requirements of the Ambassador API Gateway.
Specification
Detail
Base Proxy
Envoy Proxy
Primary Configuration
Kubernetes Annotations / CRDs
Supported Protocols
HTTP/2, gRPC, TCP, Web Sockets
Scaling Mechanism
Kubernetes Native
Mesh Integrations
Consul, Istio, Linkerd
Deployment Tools
Helm, K8s Initializer, MicroK8s Addon
OSS License
Open Source
Analysis of Operational Impact
The deployment of Ambassador within a Kubernetes cluster transforms the way traffic is managed by shifting the complexity from the application code to the infrastructure layer. By implementing a declarative policy engine, organizations can adopt a GitOps workflow where routing changes are version-controlled and audited through Kubernetes manifests.
The impact on developer productivity is significant. Through the use of Service Preview and the Developer Portal, the friction associated with onboarding new services is reduced. Furthermore, the ability to perform canary releases allows for a "fail-safe" deployment strategy, where the blast radius of a buggy release is limited to a small percentage of traffic.
From a security perspective, the ability to centralize authentication and rate limiting at the gateway level prevents the need to implement these features redundantly across every microservice. This not only reduces the amount of boilerplate code in the services but also ensures a consistent security posture across the entire organization.
However, the transition to Ambassador requires a clear understanding of the underlying Envoy Proxy and the specificities of the Kubernetes Ingress API. The challenges observed in MicroK8s deployments highlight the sensitivity of the tool to Kubernetes API versioning, particularly regarding CustomResourceDefinitions. Operators must ensure that their cluster version is aligned with the Ambassador operator's requirements to avoid deployment failures.
Sources
kind: Pod
apiVersion: v1
metadata:
name: foo-app
labels:
app: foo
spec:
containers:
- name: foo-app
image: hashicorp/http-echo:0.2.3
args:
- "-text=foo"
kind: Service
apiVersion: v1
metadata:
name: foo-service
spec:
selector:
app: foo
ports:
- port: 5678
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: example-ingress
annotations:
kubernetes.io/ingress.class: ambassador
spec:
rules:
- http:
paths:
- path: /foo
backend:
serviceName: foo-service
servicePort: 5678
EOF
```
To verify that the ingress is functioning correctly, a curl request can be sent to the local endpoint:
curl localhost/foo
This request should return the output foo.
Known Constraints and Issues in MicroK8s
The MicroK8s implementation of Ambassador has encountered several technical hurdles related to hardware and API evolution.
- Hardware Limitations: Ambassador is not supported on ARM or Raspberry Pi deployments.
- API Version Conflicts: In MicroK8s version 1.23, users have reported errors when enabling the add-on due to mismatches in CustomResourceDefinition (CRD) versions. Specifically, errors occur when the system tries to recognize
https://github.com/datawire/ambassador-operator/releases/latest/download/ambassador-operator-crds.yamlbecause no matches are found for kindCustomResourceDefinitionin versionapiextensions.k8s.io/v1beta1. - Deprecation Warnings: In MicroK8s 1.21, the system may issue warnings stating that
apiextensions.k8s.io/v1beta1 CustomResourceDefinitionis deprecated in v1.16+ and unavailable in v1.22+, recommending the use ofapiextensions.k8s.io/v1 CustomResourceDefinition.
Service Mesh and Third-Party Integrations
Ambassador is designed to function as the north-south gateway for various service meshes, providing the necessary bridge between external clients and the internal mesh proxies.
Consul Integration
HashiCorp Consul integrates with Ambassador to ensure secure routing of ingress traffic into the Consul service mesh. This is particularly critical when:
- Onboarding new applications onto a service mesh.
- Integrating existing applications that reside outside of the mesh.
In these scenarios, Ambassador acts as the API Gateway that routes incoming traffic to Consul service mesh proxies. This integration allows the infrastructure to combine the service discovery and mesh capabilities of Consul with the advanced API Gateway features of Ambassador, such as authentication and rate limiting.
Mesh Compatibility
Beyond Consul, Ambassador is capable of connecting to other prominent service meshes, including:
- Linkerd
- Istio
Ambassador API Gateway vs. Ambassador Edge Stack
While the Ambassador API Gateway is an open-source project, there is a commercial superset known as the Ambassador Edge Stack.
Comparative Analysis
The following table outlines the differences between the open-source API Gateway and the Edge Stack.
| Feature | Ambassador API Gateway (OSS) | Ambassador Edge Stack |
|---|---|---|
| Core Engine | Envoy Proxy | Envoy Proxy |
| L7 Load Balancing | Included | Included |
| Kubernetes Ingress | Included | Included |
| OAuth/OpenID Connect | Not Included | Included |
| Advanced Rate Limiting | Basic | Advanced |
| Swagger/OpenAPI Support | Not Included | Included |
| Automatic TLS (ACME) | Not Included | Integrated Support |
| User Interface (UI) | Not Included | Included |
The Edge Stack is positioned as a comprehensive solution for enterprises requiring advanced security, automated certificate management, and a visual management interface.
Summary of Technical Specifications
The following table summarizes the technical properties and requirements of the Ambassador API Gateway.
| Specification | Detail |
|---|---|
| Base Proxy | Envoy Proxy |
| Primary Configuration | Kubernetes Annotations / CRDs |
| Supported Protocols | HTTP/2, gRPC, TCP, Web Sockets |
| Scaling Mechanism | Kubernetes Native |
| Mesh Integrations | Consul, Istio, Linkerd |
| Deployment Tools | Helm, K8s Initializer, MicroK8s Addon |
| OSS License | Open Source |
Analysis of Operational Impact
The deployment of Ambassador within a Kubernetes cluster transforms the way traffic is managed by shifting the complexity from the application code to the infrastructure layer. By implementing a declarative policy engine, organizations can adopt a GitOps workflow where routing changes are version-controlled and audited through Kubernetes manifests.
The impact on developer productivity is significant. Through the use of Service Preview and the Developer Portal, the friction associated with onboarding new services is reduced. Furthermore, the ability to perform canary releases allows for a "fail-safe" deployment strategy, where the blast radius of a buggy release is limited to a small percentage of traffic.
From a security perspective, the ability to centralize authentication and rate limiting at the gateway level prevents the need to implement these features redundantly across every microservice. This not only reduces the amount of boilerplate code in the services but also ensures a consistent security posture across the entire organization.
However, the transition to Ambassador requires a clear understanding of the underlying Envoy Proxy and the specificities of the Kubernetes Ingress API. The challenges observed in MicroK8s deployments highlight the sensitivity of the tool to Kubernetes API versioning, particularly regarding CustomResourceDefinitions. Operators must ensure that their cluster version is aligned with the Ambassador operator's requirements to avoid deployment failures.