1. Introduction
Ambassador Edge Stack (AES) is an advanced API gateway and Kubernetes ingress controller built on Envoy Proxy. It is designed to handle north-south traffic in cloud-native applications, making it a crucial component for microservices and service mesh architectures.
This guide provides a detailed, step-by-step approach to installing, configuring, and troubleshooting AES in a Kubernetes cluster. Whether you are deploying in Minikube, K3s, EKS, GKE, or AKS, this guide ensures a smooth setup.
2. Prerequisites
Before you proceed, ensure you have the following:
A running Kubernetes cluster (Minikube, K3s, EKS, GKE, AKS, etc.).
kubectl installed and configured.
Helm 3+ installed.
Internet access for pulling Docker images and configurations.
An Ambassador Cloud account (for Enterprise features).
3. Installing Ambassador Edge Stack
Step 1: Add the Helm Repository
First, add the official Ambassador Helm repository:
helm repo add datawire https://app.getambassador.io
helm repo update
Step 2: Install Ambassador Edge Stack
Deploy AES using Helm:
kubectl create namespace ambassador
helm install ambassador-edge-stack datawire/ambassador --namespace ambassador
Step 3: Verify Installation
Check if Ambassador pods are running:
kubectl get pods -n ambassador
Expected output:
NAME READY STATUS RESTARTS AGE
ambassador-xxxxxxxx-xxxxx 1/1 Running 0 2m
Step 4: Check Service Availability
kubectl get svc -n ambassador
If EXTERNAL-IP is <pending>, use port-forwarding:
kubectl port-forward svc/ambassador 8080:80 -n ambassador
Access AES at http://localhost:8080
4. Common Errors and Fixes
4.1 CloudConnectToken Required (License Issue)
Error Message:
ERROR cloud-license-provider licensemgt/cloud.go:258 unable to fetch license from ambassador cloud
ERROR cloud-license-provider licensemgt/cloud.go:415 ambassador edge stack requires a valid license to run.
Solution:
Sign up for a free license: Ambassador Cloud.
Install the license:
edgectl license install <LICENSE-KEY>Restart Ambassador pods:
kubectl rollout restart deployment ambassador -n ambassador
4.2 Missing Gateway API CRDs
Error Message:
Warning, unable to watch gatewayclasses.v1alpha1.networking.x-k8s.io, unknown kind.
Solution:
Install Gateway API CRDs:
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v0.6.2/standard-install.yaml
Verify installation:
kubectl get crds | grep gateway
4.3 Client-Side Throttling
Error Message:
request.go:697] Waited for 1.092621791s due to client-side throttling
Solution:
Reduce excessive API calls.
Optimize controller reconciliation.
5. Configuring Ambassador Edge Stack
5.1 Creating a Basic Mapping
Mappings define how requests are routed. Example:
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
name: example-mapping
namespace: ambassador
spec:
prefix: /example/
service: example-service
Apply it:
kubectl apply -f mapping.yaml
5.2 Configuring an Ingress Resource
Example Ingress resource for Ambassador:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: example-ingress
namespace: ambassador
spec:
rules:
- host: example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: example-service
port:
number: 80
Apply it:
kubectl apply -f ingress.yaml
6. Debugging Issues
6.1 Checking Ambassador Logs
kubectl logs -l service=ambassador -n ambassador
6.2 Checking Ambassador Status
kubectl exec -it deploy/ambassador -n ambassador -- ambassador status
6.3 Checking Mappings
kubectl get mappings -n ambassador
7. Conclusion
In this guide, we covered:
Installing Ambassador Edge Stack using Helm.
Troubleshooting common errors like license issues and missing CRDs.
Configuring Ambassador with mappings and ingress resources.
Debugging issues using logs and commands.
Ambassador Edge Stack is a powerful tool for API management, traffic routing, and security. For advanced configurations, visit:
8. Additional Resources
Need help? Drop a comment below or join the Ambassador Community Forum! 🚀