Working with staging

Fastly's Staging feature allows you to test changes to your service configuration on a staging network before deploying them to production. To minimize differences between staging and production, staging deploys run on the same type of points of presence (POPs) as production deploys.

You don't need to make changes to your service configuration to use the Staging feature. Staging metrics are kept separate from production metrics, and you can stage a service as many times as you want.

Before you begin

You must enable the Staging feature for your account. If the feature isn't already enabled for your account, contact your account manager or sales@fastly.com for more information.

Staging a CDN service version

You can stage a CDN service version by using the Fastly control panel, API, CLI, or Terraform.

You can make as many changes to your development version as you'd like and push them to staging without increasing the version number. When you're ready to deploy the changes to production, activate your service version.

Staging a Compute service version

You can stage a Compute service version by using the Fastly API, CLI, or Terraform.

PUT /service/<service_id>/version/<version_number>/activate/staging
PUT /service/<service_id>/version/<version_number>/deactivate/staging

$ curl -X PUT -H "Fastly-Key: $fastly_key" https://api.fastly.com/service/$service_id/version/$version/activate/staging

As with CDN service versions, you can make as many changes to your development version as you'd like and push them to staging without increasing the version number. When you're ready to deploy the changes to production, activate your service version.

Accessing staging

You can access your service's staging environment in one of two ways. Using the provided Anycast IP address, you can temporarily modify the hosts file on your personal computer to test locally, or you can create a DNS A record to create a publicly-accessible domain.

Obtaining your service's staging IP address

Before you can modify the hosts file or create a DNS A record, you'll need to obtain the Anycast IP address for your service's staging environment. In most cases, you can find this in the Fastly control panel.

1. Log in to the Fastly control panel.
2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.

3. In the Staging area, click Guide to testing. The IP address for your service's staging environment is displayed.

   

4. Copy the IP address and use it to update your hosts file or DNS A record.

Updating your Hosts file

To access the staging version from your personal computer, open your local hosts file in a text editor. The exact location of the hosts file depends on the operating system you're using:

• Linux: /etc/hosts
• macOS: /private/etc/hosts
• Windows: C:\Windows\System32\drivers\etc\hosts

At the end of the file, add an entry for your staging version that includes the staging IP address and the domain name of your production service (for example, 192.0.2.0 www.example.com). Save the changes to the file.

$ sudo killall -HUP mDNSResponder

Now, when you visit the domain name of your production service on your personal computer (in this example, www.example.com), you should see your staging version.

When you've finished testing your staging version, remove the entry from your hosts file.

Creating a DNS A record

To access the staging version from a publicly-accessible domain, create a new DNS A record using the IP address provided as the value. Refer to your DNS provider's documentation for exact instructions on how to create or update a DNS A record.

Using variables

You can use variables to tell whether or not your code is running in a staging environment.

VCL

The following VCL variable is available.

Compute

The follow Compute variable is available.

Purging all cache

You can purge all cache associated with a staging environment by using the Fastly API purge all endpoint. For example, you can purge all cache for a staging environment using curl in a terminal application.

$ curl -X POST -H "Fastly-Key: $fastly_key" https://api.fastly.com/service/$service_id/purge_all?environment=staging

Purging by URL

You can purge cache associated with a staging URL by using a URL purge. For example, you can purge a staging URL using curl in a terminal application.

$ curl -X PURGE "$url_to_purge" --connect-to "::$staging_ip"

Limitations and considerations

A list of limitations and considerations is available here.

Deactivating staging

To deactivate staging for a service version, follow the steps below:

1. Log in to the Fastly control panel.
2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.
3. Select the version of the service you want to deactivate from staging.
4. From the Options menu, select Deactivate on Staging.