Preview Environments

Flightcontrol’s Preview Environment feature is an alternative to long-lived staging environments.

When configured, Flightcontrol will automatically create an ephemeral environment for each pull request or merge request. Here's an example of how it will look like in the Flightcontrol dashboard once preview environments are configured and there are opened pull requests:

Currently Supported Services

• ✅  Fargate
• ✅  Fargate-worker
• ✅ RDS | Note: There's currently a limitation on changing the config after it has been deployed (see RDS section for more info)

Configuration

With the Dashboard

Click the following button at the bottom of any Project’s page in the Flightcontrol dashboard. Then add the services and environment variables you want for preview environments.

With flightcontrol.json

Add a new environment to your environments array, with the following source object:

• Required:
  • pr: true
• Optional:
  • filter.toBranches: string[]
    • Example: "toBranches": ["main"]
    • Supports globs. We use micromatch (opens in a new tab)
    • If set, only pull or merge requests to the specified branch(es) will be deployed as preview environments. If omitted, all to branches will pass the filter.
  • filter.fromBranches: string[]
    • Example: "fromBranches": ["feature/**"]
    • Supports globs. We use micromatch (opens in a new tab)
    • If set, only pull or merge requests from the specified branch(es) will be deployed as preview environments. If omitted, all from branches will pass the filter.
  • filter.labels: string[]
    • Example: "labels": ["deploy-preview"]
    • If set, only pull or merge requests with at least one of the specified labels will be deployed. It will be deployed when the label is added, whether that’s during PR creation or some time after the PR is opened.

The service configuration schema is the same as the regular environment.

Examples

Preview Environment Example

    {
      "environments": [
        ...existing environments,
        {
          "source": {
    				// With this configuration, ready-for-review PRs
            // targetting `main` and with the `deploy` label will
            // trigger a deploy in Flightcontrol
            "pr": true,
            "filter": {
              // optional
              "toBranches": ["main"],
              // optional
              "fromBranches": ["feature/**"],
              // optional label filter:
    					"labels": ["deploy"]
            }
          },
          "services": [
            ...your supported service config
            // ⚠️ Do not include **static** service type as it is not supported yet
          ]
          ...rest of env config
        }
      ]
    }

Preview RDS With Fargate Example

In this example, we're retrieving the database URL from the preview environment URL.

{
  "environments": [
    ...otherEnvironments,
    {
      // Preview environment (`pr: true`)
      "source": {
        "pr": true,
        "filter": {
          "toBranches": ["main"]
        }
      },
      "services": [
        {
          "id": "preview-db",
          "type": "rds",
          "engine": "postgres"
          ...restOfConfig
        },
        {
          "id": "backend-api",
          "envVariables": {
            "DATABASE_URL": {
              "fromService": {
                "id": "preview-db",
                "value": "dbConnectionString"
              }
            }
          }
          ...restOfConfig
        }
      ]
    }
  ]
}

Using Database From Another Non-preview Environment Example

{
  "environments": [
    ...existing environments,
		{ // This environment will have the database
      "id": "staging",
      "name": "Staging",
      "region": "us-west-2",
      "source": {
        "branch": "main"
      },
      "services": [
        ...other services,
        {
          "id": "database-xuorBu",
          "name": "Database",
          "port": 5432,
          "type": "rds",
          "engine": "postgres",
          "private": false,
          "storage": 20,
          "maxStorage": 100,
          "instanceSize": "db..micro",
          "engineVersion": "12",
          "deletionProtection": false,
          "applyChangesImmediately": false,
          "autoUpgradeMinorVersions": true,
        }
      ]
    },
    { // This is the environment for enabling preview environment
      "source": {
        "pr": true,
        "filter": {
          "toBranches": ["main"],
        }
      },
      "services": [
         {
          ...your fargate config
          "envVariables": {
            "DATABASE_URL": {
              "fromParameterStore": "parameter.store.name.for.your.RDS"
            }
          },
         }
        // ⚠️ The **static** service type is not yet supported
      ]
      ...rest of env config
    }
  ]
}

Lifecycle

Creation

A preview environment will be created when:

• a pull request matches your configuration (the target branch and labels filters if any)
• and when it is not in draft mode.

New Deployment

Each new push to a branch that is currently opened in a Pull Request will trigger a new deployment.

Destroy

Your preview environment will be destroyed when:

• the pull request is merged — destroyed immediately
• the pull request is closed but not merged — destroyed after 30 mins, in case it was accidentally closed.

Limitations

Preview environments are not intended for production workloads.

To reduce your resource cost and to increase speed of provisioning, they don’t support the following features:

1. No CDN
2. No custom domains (every service and PR will have a Flightcontrol subdomain created automatically for it)
3. No horizontal scaling or load balancing, services with servers will only have a single instance

Good to Know

First Deployment Time

All the preview environments will share AWS resources. What this means in term of deployment time is that the very first time a pull request is created, it will take a bit longer to create the preview environment but subsequent pull requests will skip this step. The time for build and deploy will be the same.

Github Comment

Flightcontrol will keep you updated of the deployment with a Github comment added to the corresponding pull request. This comment will inform you of the progress and once successful, it will display the URL for you preview environment. It should look something like this:

You can also check the Flightcontrol dashboard to see information about the preview environment.

Preview URL

You'll be able to get the preview URL once a preview environment has been fully deployed. This URL can be retrieved in the Flightcontrol dashboard as well as in the Github comment in your PR.

AWS Costs

• Constant
  • When you have preview environments enabled, there are a number of AWS resources that are configured all the time, even if you are not making pull requests. We do this (1) to speed up provisioning of an environment for each PR and (2) reduce incremental costs for each preview environment.
  • The main long-running AWS resource is a single load balancer (per service configured under your environment) that manages traffic for all your preview environments. This AWS cost is around $20/month.
• Variable
  • Each service on each preview environment will have an associated cost, same as normal environments.
  • AWS only charges you based on the time the services are running. So if the preview environment for a specific PR is only running for 2 days, then you’re only charged for 2 days of usage.

How It Works

VPC

By default, a new, single VPC is used for all preview environments.

Alternatively, you can deploy preview environments to an existing VPC by setting the vpc field in flightcontrol.json.

RDS Preview Environment

To keep costs as low as possible and to increase deployment time, the RDS service in Preview Environment will only have a single AWS RDS instance per service configured that will be shared. i.e.: if you have 1 RDS service and 10 PRs open, there will only be 1 instance created in AWS.

Then, for each preview environment, a new database within that instance will be created. The connection string for a specific PR can be accessed from the other services via the configured environment variable.

When the PR is merged and the preview environment is cleaned up, that database will be deleted.

Limitation

We do not currently support changing the RDS config once it has been deployed and as way around that we suggest you change the ID for the RDS service type.

This will create a new RDS instance which can have the changed config.