Synthetic Testing Tunnel

Synthetic Testing Tunnel

This feature is in public beta.

The Synthetic testing tunnel creates short lived secure connections between your internal environments and the Datadog infrastructure, allowing you to swiftly trigger Synthetic tests on your private applications.

Datadog recommends using the testing tunnel if you are willing to launch Synthetics tests from your CI/CD pipeline or against local versions of your application without deploying a dedicated and long lasting probing system (such as private locations). The testing tunnel can also prove helpful if you are looking at triggering tests on ephemeral cloud environments.

What is the testing tunnel?

The testing tunnel is a functionality that comes with the @datadog/datadog-ci NPM package which is one of the methods Datadog provides to include your Synthetic tests as part of your CI/CD pipelines. The testing tunnel creates an end-to-end encrypted HTTP proxy between your infrastructure and Datadog, meaning that any test requests sent through the CLI are automatically routed through the datadog-ci client. This allows Datadog to access and test your internal applications.

datadog-ci first gets a presigned URL from Datadog for authentication. It then opens a WebSocket Secure connection (wss) to Datadog’s managed locations using the presigned URL. Using SSH connections through the websocket connection, tests are triggered by datadog-ci and executed through Datadog’s managed locations.

Because DNS resolution is performed through the tunnel, you can test applications with internal domains or even on the localhost of the machine running datadog-ci.

Note: When using the testing tunnel, your tests' locations are overriden by a location that depends on your Datadog account region.

How to use the testing tunnel

As mentioned above, the testing tunnel comes with the @datadog/datadog-ci NPM package and is available from version v0.11.0 of the package. To learn how to get started using the Datadog CI/CD testing integration, see the Synthetics CI documentation.

Once you’ve set up your client on your local machine or your CI server, you can decide to have your tests launched with the tunnel by appending the command used to launch tests with --tunnel. For instance, if you are using a global configuration file, you can use:

datadog-ci synthetics run-tests --config <GLOBAL_CONFIG_FILE>.json --tunnel

Firewall requirements

Allow Outbound connections for the following Datadog endpoints:

PortEndpointDescription
443 tunnel-us1.synthetics.datadoghq.comRequired to open the wss connection from the datadog-ci client to the tunnel service.
443 intake.synthetics.datadoghq.comRequired to get the presigned URL and to trigger the Synthetic tests.
443 api.datadoghq.comRequired to search for Synthetic tests, get them, and poll their results.

PortEndpointDescription
443 tunnel-eu1.synthetics.datadoghq.comRequired to open the wss connection from the datadog-ci client to the tunnel service.
443 api.datadoghq.euRequired to get the presigned URL, search for Synthetic tests, get them, trigger them, and poll their results.

Note: Although the tunnel service top level domain is .com (and not .eu), the endpoint is located in EU (Frankfurt AWS).

PortEndpointDescription
443 tunnel-us3.synthetics.datadoghq.comRequired to open the wss connection from the datadog-ci client to the tunnel service.
443 api.us3.datadoghq.comRequired to get the presigned URL, search for Synthetic tests, get them, trigger them, and poll their results.

Further Reading