VPC Environments

Run E2E tests against internal endpoints inside your AWS VPC.

Overview

VPC environments allow Canary to test internal applications that aren't publicly accessible, such as services behind a private ALB or in a private subnet. Canary provisions a temporary EC2 instance inside your VPC, runs a headless browser on it, and streams browser commands to/from the Canary cloud over WebSocket.

Architecture

  1. You configure an environment with your AWS VPC details (IAM role, subnet, security group).
  2. When a test suite runs, Canary assumes the IAM role and launches an EC2 instance in your subnet.
  3. The instance runs a lightweight CLI that connects back to Canary's API via WebSocket (outbound HTTPS through your NAT gateway).
  4. Canary controls the browser remotely, executing your test workflows against internal URLs.
  5. After the suite completes, the EC2 instance is terminated automatically.

Connection pooling

When a test suite contains multiple workflows targeting the same VPC environment, Canary provisions one EC2 instance per environment (not one per workflow). The browser process is shared, and credential isolation is handled at the browser context level — each workflow gets a fresh context loaded with its own credential's storage state.

Prerequisites

Before configuring a VPC environment, ensure:

  • NAT gateway: The subnet must have a route to the internet (via NAT gateway) so the EC2 instance can connect back to Canary's API.
  • IAM role: Create a role that Canary can assume (cross-account STS) with permissions to launch and terminate EC2 instances in your VPC.
  • Subnet: A private subnet in the VPC where the browser instance will run.
  • Security group: Must allow outbound HTTPS (port 443) to Canary's API, and any ports needed to reach your internal application.

Setup

  1. Navigate to your property's Environments tab.
  2. Click Add Environment and fill in the name and internal URL.
  3. Enable Run tests in customer AWS VPC.
  4. Provide the required fields:
    • IAM Role ARN: The cross-account role Canary will assume (e.g., arn:aws:iam::123456789012:role/CanaryVpcBrowser).
    • Subnet ID: The private subnet for the browser instance.
    • Security Group ID: Controls network access for the browser instance.
    • AWS Region: The region where your VPC resides.
  5. Click Create.

IAM trust policy

Your IAM role needs a trust policy allowing Canary to assume it:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<canary-account-id>:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<your-org-id>"
        }
      }
    }
  ]
}

IAM permissions

The role needs these EC2 permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:RunInstances",
        "ec2:TerminateInstances",
        "ec2:DescribeInstances",
        "ec2:CreateTags"
      ],
      "Resource": "*"
    }
  ]
}

Troubleshooting

Browser doesn't connect (timeout after 120s)

  • Verify the subnet has a NAT gateway with a route to the internet.
  • Check that the security group allows outbound HTTPS on port 443.
  • Ensure the IAM role has ec2:RunInstances permission in the specified region.

Tests fail with "No browser available"

  • The EC2 instance may have been terminated before the test completed. Check if your security group or VPC flow logs show connection drops.

IAM assume role errors

  • Verify the trust policy includes Canary's AWS account ID and your organization ID as the external ID.
  • Ensure the role ARN is correct and the role exists in the specified region.

Subnet or security group not found

  • Confirm the subnet ID and security group ID are in the same region as configured.
  • The security group must belong to the same VPC as the subnet.