- Features and Benefits
- Using Ambassador Edge Stack in Your Organization
- Ambassador Edge Stack vs. Other Software
- Certified Builds
- Ambassador Edge Stack Architecture
- Ambassador Edge Stack Deployment Architecture
- Continuous Delivery, Declarative Config, and GitOps
- Microservices API Gateways
- Rate Limiting Concepts
- Self-Service Routing and Deployment Control
- Safely Testing in Production
- OAuth & OIDC Overview
- Why Ambassador Edge Stack Uses Envoy Proxy (External Link)
- Configuring Ambassador Edge Stack
- Mapping Services
- Canary Releases
- Circuit Breakers
- Cross Origin Resource Sharing
- Header-based routing
- Host Header
- Host CRD
- Prefix Regex
- Rate Limits
- Remove Request Headers
- Remove Response Headers
- Add Request Headers
- Add Response Headers
- Automatic Retries
- Routing TCP Connections
- Traffic Shadowing
- Developer Portal
- Filter Reference
- Statistics and Monitoring
This page is deprecated. For the latest version, check out Edge Control.
How do you verify that the code you've written actually works? Ambassador's Service Preview lets developers see exactly how their service works in a realistic environment -- without impacting other developers or end-users. Service Preview integrates Telepresence, the popular CNCF project for local development and debugging on Kubernetes.
apictl is the command client for Ambassador.
Download the latest version of the client:Mac 64-bit |Linux 64-bit
Make sure the client is somewhere on your PATH. In addition, place your license key in
Information about open-source code used in
apictl can be found by running
In this quick start, we're going to preview a change we make to the backend service of the quote application, without impacting normal users of the application. Before getting started, make sure the quote application is installed on your cluster and you've installed the
apictl command-line tool, as explained above.
We're first going to get the quote backend service running locally. Clone the quote repository and build a local image.git clone https://github.com/datawire/quotecd quotemake docker.run
Note that Preview doesn't depend on a locally running container; you can just run a service locally on your laptop. We're using a container in this tutorial to minimize environmental issues with different Golang environments.
makecommand above, we build the backend application in a docker container named
localhost:31000/quote:backend-latestand run it on port 8080.
Now, in another terminal window, redeploy the quote application with the Preview sidecar. The sidecar is a special process that will route requests to your local machine or the production cluster. The
apictl traffic injectcommand will automatically create the appropriate YAML to inject the sidecar. In the
quotedirectory, pass the file name of the QOTM deployment:apictl traffic inject k8s/tour.yaml -d tour -s tour -p 8080 > k8s/tour-traffic-sidecar.yaml
This will create a YAML file called
qotm-sidecar.yaml. The file will look like the following:---apiVersion: getambassador.io/v1kind: Mappingmetadata:name: quote-backendspec:prefix: /backend/service: quote:8080labels:ambassador:- request_label:- backend---apiVersion: v1kind: Servicemetadata:name: quotespec:ports:- name: backendport: 8080targetPort: 9900selector:app: quote---apiVersion: apps/v1kind: Deploymentmetadata:name: quotespec:replicas: 1selector:matchLabels:app: quotestrategy:type: RollingUpdatetemplate:metadata:labels:app: quotespec:containers:- image: quay.io/datawire/quote:0.2.7name: quoteports:- containerPort: 8080name: httpresources:limits:cpu: "0.1"memory: 100Mi- env:- name: APPNAMEvalue: quote- name: APPPORTvalue: "8080"- name: AMBASSADOR_LICENSE_KEYvalue: eJcbGciOiaIUzI1NiIsInR5cCkpXVCJ9.eCI6Im5rcmF1c2UiLCJleHAiOjE1Nzg0MTg4ODZ9.S_6-zdPyy4z1N4Jmo5e4A7fME4CbQVL_13ikwimage: quay.io/datawire/ambassador_pro:app-sidecar-0.11.0name: traffic-sidecarports:- containerPort: 9900
If you examine this file, you will notice a couple of important difference:
traffic-sidecarcontainer has been added to the deployment
- In the service,
backendport mapping has been changed to point to port 9900 which is the port the
traffic-sidecarcontainer is listening on
Redeploy quote with the sidecar:kubectl apply -f k8s/quote-traffic-sidecar.yaml
Test to make sure that both your production and development instances of QOTM work:curl $AMBASSADOR_IP/backend/ # test productioncurl localhost:8080/ # test development
Initialize the traffic manager for the cluster.apictl traffic initialize
We need to create an
interceptrule that tells Ambassador where to route specific requests. The following command will tell Ambassador to route any traffic for the
quotedeployment where the header
devto go to port 8080 on localhost:apictl traffic intercept quote -n x-service-preview -m dev -t 8080
Requests with the header
x-service-preview: devwill now get routed locally:curl -H "x-service-preview: dev" $AMBASSADOR_IP/backend/` # will go to local Docker instancecurl $AMBASSADOR_IP/backend/ # will go to production instance
Make a change to the backend source code. In
backend/main.go, uncomment out line 85, and comment out line 84, so it reads like so:...//quote := s.random.RandomSelectionFromStringSlice(s.quotes)quote := "Service Preview Rocks!"...
This will ensure that the backend service will return a quote of "Service Preview rocks" every time.
Rebuild the docker container and rerun the
curlabove, which will now route to your (modified) local copy of the QOTM service:make docker.run -C backend/curl -H "x-service-preview: dev" $AMBASSADOR_IP/qotm/` # will go to local Docker instance
To recap: With Preview, we can now see test and visualize changes to our service that we've made locally, without impacting other users of the stable version of that service.
Service Preview will match HTTP headers based on the headers that are seen by the sidecar and not the edge gateway. Matches are made on the whole header, e.g., a match rule of
dev will not match in the example above, while
/backend/dev will match.
While any HTTP header will match, in practice, using host-based routing (i.e., the
:authority header), a custom HTTP header (e.g., the
x-service-preview header used above), or an authentication header is recommended.