Skip to main content

Pull Request Previews

Overview​

In a microservices environment, functionality is often realized across one or more different microservices at different layers of the stack. In this scenario, it proves challenging to preview and test changes to the application end-to-end without either setting up a dedicated environment containing multiple microservices or updating an existing staging environment with the changes.

In both of the above scenarios, there are issues - setting up a fully dedicated environment does not scale and becomes expensive both in terms of and infrastructure & maintenance costs and still may not provide production-like fidelity. Alternatively, using just the shared staging environment often disrupts other teams, not allowing parallelism.

In this guide, we outline how you can preview every feature in isolation using Sandboxes.

High-Level Steps​

1. Create Pull Request Sandboxes​

Follow the steps outlined in the Pull Request Sandboxes guide to create a sandbox for each pull request. In the rest of the guide, we will go over how to enable developers to use previews on top of these sandboxes.

2. Ensure Context Propagation​

To ensure that your requests are isolated and only affect the specific sandbox, you need to ensure context propagation. This is especially important if you're looking to exercise the changes from the frontend or a mobile app. For more details on context propagation, refer to the guide on setting up context propagation.

3. Set Up Access to Previews​

Once the sandbox is set up, you can provide access to developers in several ways:

Using Chrome Extension for Web Frontend Previews​

If you are testing web services, you can use the Signadot Chrome Extension. This extension allows you to easily switch between different sandboxes and preview changes directly in your browser. Refer to the guide on Previews from Web Frontends for details.

Setting the Request Header Manually​

For previewing APIs, you can manually set the request header to point to the sandbox. This can be done using tools like Postman, cURL, gRPCurl etc. When a sandbox is created, it will return a Routing Key, which can then be set using any of the supported header propagation mechanisms which will in turn cause the request to be re-routed accordingly.

You can do this on any existing staging URLs or in-cluster URLs. For example, with cURL, the header may end up looking like:

curl -H 'baggage: sd-routing-key=<my-sandbox-routing-key>' http://my.company.staging/api/...

Ensure that you're setting the appropriate format of headers depending on the library that you're using for context propagation.

Using Hosted Preview URLs​

note

You may run into limitations with using preview URLs such as CORS errors especially when looking to access frontends which you may not encounter when using either of the above methods.

Signadot also can create hosted preview URLs for sandboxes which can automatically inject the required headers automatically. These URLs are of the form *.preview.signadot.com and can point to any service that is addressable within your Kubernetes cluster. To set up preview URLs, you will need to modify the sandbox spec as detailed here.

Advanced: Previews Across Pull Requests​

In some scenarios, you may need to test changes that span across multiple pull requests (cross-PR testing). This can be achieved by combining multiple sandboxes using RouteGroups.

RouteGroups allow you to define routing rules that span multiple sandboxes, effectively combining them into a single environment. Here's a high-level overview:

  1. Create Individual Sandboxes for Each PR: Follow the steps outlined in the Pull Request Sandboxes guide to create a sandbox for each pull request.
  2. Define a RouteGroup: Create a RouteGroup that combines sandboxes using their labels. This RouteGroup will allow you to access services from multiple sandboxes seamlessly.
  3. Access the Combined Environment: Use the routing key provided by the RouteGroup to access the combined environment for testing.

Refer to the RouteGroups documentation for more details on how to set up and configure RouteGroups.

Best Practices​

Surfacing Routing Keys​

  • Web Frontends: Use the Signadot Chrome Extension for a simple DevEx that just involves choosing a Sandbox by name.
  • API Previews and Mobile Frontends: In these cases, there may not be a convenient measure and you may need to surface the routing key itself. In these cases, placing the routing key into a Pull Request comment offers a simple interface for developers to plug it into tools like Postman, or a debug build of a mobile app that takes the appropriate routing header as a parameter.

Mobile App Debug Builds​

For mobile applications, you can set up a debug build with settings to plug in the routing key. This allows you to test the app against different sandboxes and allows backend engineers to see the effect of their change all the way from the mobile app itself.

Sandbox Labels​

It is recommended to set labels that are derived from source control parameters, such as the git-branch, the org and the repo. These parameters can later be used to combine sandboxes into RouteGroups.

Setting up Route Groups automatically in CI/CD​

While Route Groups are specified as an ad hoc construct that is created on the fly by a user, they can also be automated in CI using convention.

For example, branch names or special labels on Pull Requests can be used as convention to give developers an easy interface to automatically create Route Groups and select sandboxes into them. Note that the routing key of a Route Group is separate from each of its constituent Sandboxes and must be surfaced to the user if it's being created as part of CI/CD automation.

Conclusion​

By following these steps, you can easily set up pull request previews and allow developers to test and preview their changes in isolation. This not only improves code quality but also speeds up the development process by catching issues early.

This document covered the basics of setting up a Sandbox and RouteGroups for previews. You can read more in-depth about Sandboxes and RouteGroups in the reference documentation.