Table of Contents
*The author selected the Free and Open Source Fund to receive a donation as part of the Write for DOnations program.*
Introduction
Ambassador is an API Gateway for cloud-native applications that routes traffic between heterogeneous services and maintains decentralized workflows. It acts as a single entry point and supports tasks like service discovery, configuration management, routing rules, and rate limiting. It provides great flexibility and ease of configuration for your services.
Envoy is an open source service proxy designed for cloud-native applications. In Kubernetes, Ambassador can be used to install and manage Envoy configuration. Ambassador supports zero downtime configuration changes and integration with other features like authentication, service discovery, and services meshes.
In this tutorial, you'll set up an Ambassador API Gateway on a Kubernetes cluster using Helm and configure it for routing incoming traffic to various services based on routing rules. You'll configure these rules to route the traffic based on hostname or path to the relevant services.
If you’re looking for a managed Kubernetes hosting service, check out our simple, managed Kubernetes service built for growth.
Prerequisites
Before you begin this guide you'll need the following:
- A Kubernetes cluster with kubectl configured. To create a Kubernetes cluster on the cloud provider, see our Kubernetes Quickstart.
- The Helm package manager installed on your local machine, and Tiller installed on your cluster. Complete Steps 1 and 2 of How To Install Software on Kubernetes Clusters with the Helm Package Manager
- A fully registered domain name with at least two A records configured. This tutorial will use
svc1.<^>your-domain<^>,svc2.<^>your-domain<^>, andsvc3.<^>your-domain<^>throughout. You can follow the DNS Quickstart to set your records up on the cloud provider.
Step 1 — Installing Ambassador
In this section, you will install Ambassador on your Kubernetes cluster. Ambassador can be installed using a Helm chart or by passing a YAML configuration file to the kubectl command.
Note: Kubernetes has RBAC enabled by default, so when using a YAML configuration file for installation you need to ensure that you use the RBAC enabled one. You can find further details about deploying Amabassador to Kubernetes via YAML in Ambassador's documentation.
For the purposes of this tutorial, you'll use a Helm chart to install Ambassador to your cluster. Having followed the prerequisites, you'll have Helm installed to your cluster.
To begin, run the following command to install Ambassador via Helm:
helm upgrade --install --wait ambassador stable/ambassador
You'll see output similar to the following:
[secondary_label Output]
Release "ambassador" does not exist. Installing it now.
NAME: ambassador
LAST DEPLOYED: Tue Jun 18 02:15:00 2019
NAMESPACE: default
STATUS: DEPLOYED
RESOURCES:
==> v1/Deployment
NAME READY UP-TO-DATE AVAILABLE AGE
ambassador 3/3 3 3 2m39s
==> v1/Pod(related)
NAME READY STATUS RESTARTS AGE
ambassador-7d55c468cb-4gpq9 1/1 Running 0 2m38s
ambassador-7d55c468cb-jr9zr 1/1 Running 0 2m38s
ambassador-7d55c468cb-zhm7l 1/1 Running 0 2m38s
==> v1/Service
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
ambassador LoadBalancer 10.245.183.114 139.59.52.164 80:30001/TCP,443:31557/TCP 2m40s
ambassador-admins ClusterIP 10.245.46.43 <none> 8877/TCP 2m41s
==> v1/ServiceAccount
NAME SECRETS AGE
ambassador 1 2m43s
==> v1beta1/ClusterRole
NAME AGE
ambassador 2m41s
==> v1beta1/ClusterRoleBinding
NAME AGE
ambassador 2m41s
==> v1beta1/CustomResourceDefinition
NAME AGE
authservices.getambassador.io 2m42s
consulresolvers.getambassador.io 2m41s
kubernetesendpointresolvers.getambassador.io 2m42s
kubernetesserviceresolvers.getambassador.io 2m43s
mappings.getambassador.io 2m41s
modules.getambassador.io 2m41s
ratelimitservices.getambassador.io 2m42s
tcpmappings.getambassador.io 2m41s
tlscontexts.getambassador.io 2m42s
tracingservices.getambassador.io 2m43s
. . .
This will create an Ambassador deployment, service, and a Load Balancer with your Kubernetes cluster nodes attached. You'll need the Load Balancer's IP to map it to your domain's A records.
To get the IP address of your Ambassador Load Balancer, run the following:
kubectl get svc --namespace default ambassador
You'll see output similar to:
[secondary_label Output]
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
ambassador LoadBalancer <^>your_cluster_IP<^> <^>your-IP-address<^> 80:30001/TCP,443:31557/TCP 8m4s
Note the external IP your-IP-address in this step and map the domains (via your domain provider) svc1.<^>your-domain<^>, svc2.<^>your-domain<^>, and svc3.<^>your-domain<^> to point to this IP address.
You can enable HTTPS with your load balancers using the steps given at How to Configure SSL Termination. It is recommended to configure TLS termination via the Load Balancer. Another way of configuring TLS termination is using Ambassador's TLS Support
You've installed Ambassador on your Kubernetes cluster using Helm which created an Ambassador deployment with three replicas in the default namespace. This also created a Load Balancer with a public IP to route all traffic toward the API Gateway. Next you'll create Kubernetes deployments for three different services that you'll be using to test this API Gateway.
Step 2 — Setting Up Web Server Deployments
In this section, you'll create three deployments to run three different web server containers. You'll create YAML files with definitions of Kubernetes deployments for the three different web server containers and deploy them using kubectl.
Open your preferred text editor to create your first deployment for an Nginx web server:
nano svc1-deploy.yaml
Enter the following yaml configuration in your file:
[label svc1-deploy.yaml]
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
name: <^>svc1<^>
spec:
replicas: 1
selector:
matchLabels:
app: nginx
name: svc1
strategy:
type: RollingUpdate
template:
metadata:
labels:
app: nginx
name: svc1
spec:
containers:
- name: nginx
image: <^>nginx:latest<^>
ports:
- name: http
containerPort: 80
Here you have defined a Kubernetes Deployment with the nginx:latest container image to be deployed with 1 replica, called <^>svc1<^>. The Deployment is defined to expose in-cluster at port 80.
Save and close the file.
Then run the following command to apply this configuration:
kubectl apply -f svc1-deploy.yaml
You'll see output confirming creation:
[secondary_label Output]
deployment.extensions/svc1 created
Now, create a second web server deployment. Open a file called svc2-deploy.yaml with:
nano svc2-deploy.yaml
Enter the following YAML configuration in the file:
[label svc2-deploy.yaml]
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
name: <^>svc2<^>
spec:
replicas: 1
selector:
matchLabels:
app: httpd
name: svc2
strategy:
type: RollingUpdate
template:
metadata:
labels:
app: httpd
name: svc2
spec:
containers:
- name: httpd
image: <^>httpd:latest<^>
ports:
- name: http
containerPort: 80
Here you have defined a Kubernetes Deployment with the httpd container image to be deployed with 1 replica, called <^>svc2<^>.
Save and close the file.
Run the following command to apply this configuration:
kubectl apply -f svc2-deploy.yaml
You'll see this output:
[secondary_label Output]
deployment.extensions/svc2 created
Finally for the third deployment, open and create the svc3-deploy.yaml file:
nano svc3-deploy.yaml
Add the following lines to the file:
[label svc3-deploy.yaml]
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
name: <^>svc3<^>
spec:
replicas: 1
selector:
matchLabels:
app: httpbin
name: svc3
strategy:
type: RollingUpdate
template:
metadata:
labels:
app: httpbin
name: svc3
spec:
containers:
- name: httpbin
image: <^>kennethreitz/httpbin:latest<^>
ports:
- name: http
containerPort: 80
Here you have defined a Kubernetes Deployment with the httpbin container image to be deployed with 1 replica, called <^>svc3<^>.
Save and close the file.
Finally, run the following command to apply:
kubectl apply -f svc3-deploy.yaml
And you'll see the following output:
[secondary_label Output]
deployment.extensions/svc3 created
You've deployed three web server containers using Kubernetes deployments. In the next step, you will be exposing these deployments to internet traffic.
Step 3 — Exposing Apps Using Services with Ambassador Annotations
In this section, you will expose your web apps to the internet creating Kubernetes Services with Ambassador annotations to configure rules to route traffic to them. Annotations in Kubernetes are a way to add metadata to objects. Ambassador uses these annotation values from services to configure its routing rules.
As a reminder you need to have your domains (for example: <^>svc1<^>.your-domain, <^>svc2<^>.your-domain, and <^>svc3<^>.your-domain) mapped to the Load Balancer's public IP in your DNS records.
Define a Kubernetes service for the svc1 deployment with Ambassador annotations by creating and opening this file:
nano svc1-service.yaml
Note: The mapping name should be unique for every Ambassador annotation block. The mapping acts as an identifier for every annotation block and if repeated it will overlap the older annotation block.
[label svc1-service.yaml]
apiVersion: v1
kind: Service
metadata:
name: svc1
annotations:
getambassador.io/config: |
---
apiVersion: ambassador/v1
kind: Mapping
name: svc1-service_mapping
host: <^>svc1.your-domain<^>
prefix: /
service: svc1:80
spec:
selector:
app: nginx
name: svc1
ports:
- name: http
protocol: TCP
port: 80
In this YAML code, you have defined a Kubernetes service <^>svc1<^> with Ambassador annotations to map hostname <^>svc1.your-domain<^> to this service.
Save and exit svc1-service.yaml, and then execute the following to apply this configuration:
kubectl apply -f svc1-service.yaml
You'll see this output:
[secondary_label Output]
service/svc1 created
Create your second Kubernetes service for svc2 deployment with Ambassador annotations. This is another example of host-based routing with Ambassador:
svc2-service.yaml
Add the following configuration to the file:
[label svc2-service.yaml]
apiVersion: v1
kind: Service
metadata:
name: svc2
annotations:
getambassador.io/config: |
---
apiVersion: ambassador/v1
kind: Mapping
name: svc2-service_mapping
host: <^>svc2.your-domain<^>
prefix: /
service: svc2:80
spec:
selector:
app: httpd
name: svc2
ports:
- name: http
protocol: TCP
port: 80
Save this as svc2-service.yaml. Here, you've defined another Kubernetes service with Ambassador annotations to route traffic to svc2 when any request is received by Ambassador with the host header value as svc2.your-domain. Therefore this host-based routing will allow you to send a request to the subdomain svc2.your-domain, which will route the traffic to the service svc2 and serve your request from httpd web server.
To create this service, execute the following:
kubectl apply -f svc2-service.yaml
You'll see the following output:
[secondary_label Output]
service/svc2 created
Create a third Kubernetes service for your svc3 deployment and serve it via the path svc2.your-domain/bin. This will configure path-based routing for Ambassador:
[label svc3-service.yaml]
apiVersion: v1
kind: Service
metadata:
name: svc3
spec:
selector:
app: httpbin
name: svc3
ports:
- name: http
protocol: TCP
port: 80
Save this as svc3-service.yaml and run the following to apply the configuration:
kubectl apply -f svc3-service.yaml
Your output will be:
[secondary_label Output]
service/svc3 created
Edit svc2-service.yaml to append the second Ambassador annotation block to route /bin to svc3 service:
nano svc2-service.yaml
[label svc2-service.yaml]
apiVersion: v1
kind: Service
metadata:
name: svc2
annotations:
getambassador.io/config: |
---
apiVersion: ambassador/v1
kind: Mapping
name: svc2-service_mapping
host: svc2.your-domain
prefix: /
service: svc2:80
<^>---<^>
<^>apiVersion: ambassador/v1<^>
<^>kind: Mapping<^>
<^>name: svc3-service_mapping<^>
<^>host: svc2.your-domain<^>
<^>prefix: /bin<^>
<^>service: svc3:80<^>
spec:
selector:
app: httpd
name: svc2
ports:
- name: http
protocol: TCP
port: 80
You've added the second Ambassador annotation block to configure paths beginning with /bin to map to your svc3 Kubernetes service. In order to route requests for svc2.your-domain/bin to svc3, you have added the second annotation block here as the host value svc2.your-domain, which is the same for both of the blocks. Therefore path-based routing will allow you to send a request to svc2.your-domain/bin, which will be received by service svc3 and served by the httpbin application in this tutorial
Now run the following to apply the changes:
kubectl apply -f svc2-service.yaml
You'll see this output:
[secondary_label Output]
service/svc2 configured
You have created Kubernetes Services for the three deployments and added host-based and path-based routing rules with Ambassador annotations. Next, you'll add advanced configuration to these services to configure routing, redirection, and custom headers.
Step 4 — Advanced Ambassador Configurations for Routing
In this section, you will configure the services with further Ambassador annotations to modify headers and configure redirection.
curl the domain svc1.<^>your-domain<^> and check the response headers:
curl -I svc1.<^>your-domain<^>
Your output will be similar to the following:
[secondary_label Output]
HTTP/1.1 200 OK
server: envoy
date: Mon, 17 Jun 2019 21:41:00 GMT
content-type: text/html
content-length: 612
last-modified: Tue, 21 May 2019 14:23:57 GMT
etag: "5ce409fd-264"
accept-ranges: bytes
x-envoy-upstream-service-time: 0
This output shows the headers received from the service routed using Ambassador. You'll add custom headers to your service response using Ambassador annotations and validate the output for new added headers.
To add custom headers to your service response, remove the header x-envoy-upstream-service-time from the response and add a new response header x-geo-location: India for svc1. (You may change this header as per your requirements.)
Edit the file svc1-service.yaml:
nano svc1-service.yaml
Update the annotation with the following highlighted lines:
[label svc1-service.yaml]
apiVersion: v1
kind: Service
metadata:
name: svc1
annotations:
getambassador.io/config: |
---
apiVersion: ambassador/v1
kind: Mapping
name: svc1-service_mapping
host: svc1.example.com
prefix: /
<^>remove_response_headers:<^>
<^>- x-envoy-upstream-service-time<^>
<^>add_response_headers:<^>
<^>x-geo-location: India<^>
service: svc1:80
spec:
selector:
app: nginx
name: svc1
ports:
- name: http
protocol: TCP
port: 80
Here you have modified the svc1 service to remove x-envoy-upstream-service-time and added the <^>x-geo-location: India<^> header in the HTTP response.
Apply the changes you have made:
kubectl apply -f svc1-service.yaml
You will see the following output:
[secondary_label Output]
service/svc1 configured
Now run curl to validate the updated headers in the service response:
curl -I svc1.<^>your-domain<^>
The output will be similar to this:
[secondary_label Output]
HTTP/1.1 200 OK
server: envoy
date: Mon, 17 Jun 2019 21:45:26 GMT
content-type: text/html
content-length: 612
last-modified: Tue, 21 May 2019 14:23:57 GMT
etag: "5ce409fd-264"
accept-ranges: bytes
x-geo-location: India
Now edit svc3-service.yaml to redirect requests for your hostname svc3.<^>your-domain<^> to path svc2.<^>your-domain/bin<^>:
nano svc3-service.yaml
Append the Ambassador annotation block as shown in the following YAML and save it:
[label svc3-service.yaml]
apiVersion: v1
kind: Service
metadata:
name: svc3
<^>annotations:<^>
<^>getambassador.io/config: |<^>
<^>---<^>
<^>apiVersion: ambassador/v1<^>
<^>kind: Mapping<^>
<^>name: redirect_mapping<^>
<^>host: svc3.your-domain<^>
<^>prefix: /<^>
<^>service: svc2.your-domain<^>
<^>host_redirect: true<^>
<^>path_redirect: /bin<^>
spec:
selector:
app: httpbin
name: svc3
ports:
- name: http
protocol: TCP
port: 80
You've added host_redirect: true to configure a 301 redirection response for svc3 to svc2.<^>your-domain/bin<^> for hostname svc3.<^>your-domain<^>. The host_redirect parameter sends a 301 redirection response to the client. If not set, the requests will receive 200 HTTP responses rather than 301 HTTP responses.
Now run the following command to apply these changes:
kubectl apply -f svc3-service.yaml
You will see similar output to:
[secondary_label Output]
service/svc3 configured
You can now check the response for svc3.your-domain using curl:
curl -I svc3.<^>your-domain<^>
Your output will be similar to the following:
[secondary_label Output]
HTTP/1.1 301 Moved Permanently
location: http://svc2.your-domain/bin
date: Mon, 17 Jun 2019 21:52:05 GMT
server: envoy
transfer-encoding: chunked
The output is a HTTP header for the request's response to the service svc3.<^>your-domain<^>showing that the configuration of host_redirect: true in your service annotation has correctly provided the HTTP status code: 301 Moved Permanently.
You've configured the service with Ambassador annotations to modify HTTP headers and configure redirections. Next you will be adding global configuration to the Ambassador API Gateway service.
Step 5 — Setting Up Ambassador Global Configurations
In this section, you will edit the Ambassador service to add global GZIP compression configuration. GZIP compression will compress the HTTP assets size and reduce network bandwidth requirements leading to faster response times for the web clients. This configuration affects all the traffic being routed out through the Ambassador API Gateway. Similarly, you can configure other global modules with Ambassador, which let you enable special behaviors for Ambassador at a global level. These global configurations can be applied using annotations to the Ambassador service. You can refer to Ambassador's Global Configuration documentation for further information.
The following kubectl edit command will open the default editor, which is vim. To use nano, for example, you can set the environment variable KUBE_EDITOR to nano:
export KUBE_EDITOR="nano"
Edit the Ambassador service:
kubectl edit service ambassador
Now add the highlighted lines to a new annotation block for GZIP compression:
[label Editing Ambassador Service]
apiVersion: v1
kind: Service
metadata:
<^>annotations:<^>
<^>getambassador.io/config: |<^>
<^>---<^>
<^>apiVersion: ambassador/v1<^>
<^>kind: Module<^>
<^>name: ambassador<^>
<^>config:<^>
<^>service_port: 8080<^>
<^>---<^>
<^>apiVersion: ambassador/v0<^>
<^>kind: Module<^>
<^>name: ambassador<^>
<^>config:<^>
<^>gzip:<^>
<^>memory_level: 5<^>
<^>min_content_length: 256<^>
<^>compression_level: BEST<^>
<^>compression_strategy: DEFAULT<^>
<^>content_type:<^>
<^>- application/javascript<^>
<^>- application/json<^>
<^>- text/html<^>
<^>- text/plain<^>
<^>disable_on_etag_header: false<^>
<^>remove_accept_encoding_header: false<^>
creationTimestamp: "2019-06-17T20:45:04Z"
labels:
app.kubernetes.io/instance: ambassador
app.kubernetes.io/managed-by: Tiller
app.kubernetes.io/name: ambassador
helm.sh/chart: ambassador-2.8.2
name: ambassador
namespace: default
resourceVersion: "2153"
. . .
You've added the Ambassador annotation block to your Ambassador service and configured GZIP globally for the API Gateway. Here you have included configuration to control the amount of internal memory used with memory_level, which can be a value from 1 to 9. The compression_level set at BEST ensures a higher compression rate at the cost of higher latency. With min_content_length you have configured the minimum response length to 256 bytes. For content_type you've specifically included a set of media types (formerly MIME-types) that yield compression. Finally you added the final two configurations as false to allow for compression.
You can read more about GZIP compression on Envoy's GZIP page.
Any changes in this service apply as global configurations for the API Gateway.
Once you have exited the editor you'll see output similar to the following:
[secondary_label Output]
service/ambassador edited
Check svc1.<^>your-domain<^> using curl for the content-encoding header having value gzip:
curl --compressed -i http://svc1.example.com
The output will be similar to this:
[secondary_label Output]
HTTP/1.1 200 OK
server: envoy
date: Mon, 17 Jun 2019 22:25:35 GMT
content-type: text/html
last-modified: Tue, 21 May 2019 14:23:57 GMT
accept-ranges: bytes
x-geo-location: India
vary: Accept-Encoding
<^>content-encoding: gzip<^>
transfer-encoding: chunked
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
<style>
body {
width: 35em;
margin: 0 auto;
font-family: Tahoma, Verdana, Arial, sans-serif;
}
</style>
</head>
<body>
<h1>Welcome to nginx!</h1>
<p>If you see this page, the nginx web server is successfully installed and
working. Further configuration is required.</p>
<p>For online documentation and support please refer to
<a href="https://nginx.org/">nginx.org</a>.<br/>
Commercial support is available at
<a href="https://nginx.com/">nginx.com</a>.</p>
<p><em>Thank you for using nginx.</em></p>
</body>
</html>
Here you can see the default HTML page of Nginx with its response header showing that content-encoding of the received response is gzip compressed.
You've added global configuration to Ambassador to enable GZIP configuration for selected content type responses across the API Gateway.
Conclusion
You have successfully set up an API Gateway for your Kubernetes cluster using Ambassador. You are now able to expose your apps using host- and path-based routing, custom headers, and global GZIP compression.
For further information about the Ambassador annotations and configuration parameters, read Ambassador's official documentation.
