Service Preview has been replaced by Telepresence, these docs will remain as a historical reference. Learn more about Telepresence or go to the quick start guide.

Service Preview tutorial

When Service Preview is used, incoming requests get routed by Ambassador to a Traffic Agent, which then routes traffic to the microservice. When a request meets a specific criteria (e.g., it has a specific HTTP header value), the Traffic Agent will route that request to the microservice running locally. The following video shows Service Preview in more detail:

Quick start

Service Preview creates a connection between your local environment and the cluster. These connections are managed through the Traffic Manager, which is deployed in your cluster, and the edgectl daemon, which runs in your local environment.

To get started with Service Preview, you'll need to download and install the edgectl client.

Service Preview should already by installed in your cluster before starting this quick start. See the installation instructions for information on how to install Service Preview.

Intercepting traffic

One of the main use cases of Service Preview is to intercept certain requests to services in your Kubernetes cluster and route them to your laptop instead.

Intercept with an HTTP header

1. Make sure sure that the Hello is installed. See the installation instructions.

2. Launch a local service on your laptop. If you were debugging the Hello service, you might run a local copy in your debugger. In this example, we will start an arbitrary service on port 9000.

3. Make sure you are connected to the cluster to set up outbound connectivity and check that you can access the Hello service in the cluster with curl.

4. Set up an intercept. In this example, we’ll capture requests that have the x-dev header set to $USER.

   As you can see, the second request, which includes the specified x-dev header, is served by the local server.

5. Next, remove the intercept to restore normal operation.

   Requests are no longer intercepted.

Intercept with a preview URL

Now let's set up an intercept with a preview URL.

1. Create or edit an existing Host resource to enable Preview URLs

   Replace {{AMBASSADOR_IP_OR_DOMAIN_NAME}} with the IP address or domain name of your Ambassador service and apply it with kubectl

2. Refresh the edgectl connection for it to detect the new Host

3. Now add an intercept and give it a try.

   As you can see, the second request, which uses the preview URL, is served by the local server.

4. Remove the intercept to restore normal operation.

   Requests are no longer intercepted.

Outbound services

Service Preview bridges your local and cluster DNS. This allows for the use case of using Service Preview as a debug tool for interacting with services in your cluster.

1. Make sure sure that the Hello service is installed. See the installation instructions.

2. Make sure you are still connected to the cluster.

You are now able to connect to services directly from your laptop, as demonstrated by the curl command above.

3. When you’re done working with this cluster, disconnect.

What's next?

Multiple intercepts of the same deployment can run at the same time too. You can direct them to the same machine, allowing you to “or” together intercept conditions. Also, multiple developers can intercept the same deployment simultaneously. As long as their match patterns don’t collide, they don’t need to worry about disrupting one another.