---
title: Working with staging
summary: null
url: >-
  https://www.fastly.com/documentation/guides/getting-started/services/working-with-staging
---

Fastly's [Staging feature](https://docs.fastly.com/products/staging) 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 should review this feature's [limitations](https://docs.fastly.com/products/staging#limitations-and-considerations) before using it. By default, the Staging feature is automatically enabled for use in the Fastly API, CLI, and Terraform.

### Enabling staging controls in the Fastly control panel

You must enable the Staging feature for use in the Fastly control panel. If you've been assigned the [role of superuser](https://www.fastly.com/documentation/guides/account-info/user-and-account-management/about-user-roles-and-permissions), do that by following these steps:

1.   Log in to the [Fastly control panel](https://manage.fastly.com).

2. From the [**Home**](https://manage.fastly.com/home) page, select a service.
3. Click the **Opt in to Staging** button.

![the staging feature opt-in banner](/img/staging-opt-in.png)

> **NOTE:** If you previously enabled and then opted out of using the Staging feature for your account, you'll need to [contact support](https://support.fastly.com/) to reenable the feature.

### Preparing services that use Next-Gen WAF

> **IMPORTANT:** This section only applies to Next-Gen WAF customers who **cannot** access the WAF in the Fastly control panel.

If your service is configured to use [Next-Gen WAF](https://www.fastly.com/documentation/guides/next-gen-waf/) and your deployment uses a `edgemodule` version lower than 2.11.0, run the following command for each service to update that service's [delivery integration](https://docs.fastly.com/signalsciences/api/#_corps__corpName__sites__siteName__deliveryIntegration__fastlySID__put) and enable support for the Staging feature:

```term copy nolinenums
$ curl -H "x-api-user:$api_user" \
  -H "x-api-token:$signalsciences_key" \
  -H "Content-Type: application/json" \
  -H "Fastly-Key: $fastly_key" https://dashboard.signalsciences.net/api/v0/corps/$corp/sites/$site_name/deliveryIntegration/$service_id \
  -X PUT -d '{"percentEnabled": 100, "activateVersion": true }'
```

> **TIP:** You only need to run this command if your deployment uses an `edgemodule` version lower than 2.11.0. Find your deployment's current version by viewing the service's VCL and searching for `x-fastly-ngwaf:edgemodule`.

## Staging a CDN service version

You can stage a CDN service version by using the Fastly control panel, API, CLI, or [Terraform](https://registry.terraform.io/providers/fastly/fastly/latest/docs/resources/service_vcl).

### Control panel

1.   Log in to the [Fastly control panel](https://manage.fastly.com).

2.   From the [**Home**](https://manage.fastly.com/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 push to staging.
4. Click the **Activate** button, and select **Staging**.
5. If you make additional changes to your service, click **Push changes to Staging** to push them to staging.

   ![the Deploy to Staging button](/img/deploy-to-staging.png)

### API

You can stage a service version using the same API endpoints used for [activating](https://www.fastly.com/documentation/reference/api/services/version/#activate-service-version) and [deactivating](https://www.fastly.com/documentation/reference/api/services/version/#deactivate-service-version) a version.

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

For example, you can stage a service version using curl in a terminal application.

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

### CLI

You can stage or unstage a VCL service version by using the [Fastly CLI](https://www.fastly.com/documentation/reference/cli/):

```term copy
$ fastly service-version stage --service-id 123 --version 2
$ fastly service-version unstage --service-id 123 --version 2
```

These commands take the same options as the [activate](https://www.fastly.com/documentation/reference/cli/service-version/activate/) command.

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](https://www.fastly.com/documentation/guides/getting-started/services/about-services#understanding-fastly-services-and-versions) your service version.

## Staging a Compute service version

You can stage a Compute service version by using the Fastly API, CLI, or [Terraform](https://registry.terraform.io/providers/fastly/fastly/latest/docs/resources/service_compute).

### API

You can stage a Compute service version using the same API endpoints used for [activating](https://www.fastly.com/documentation/reference/api/services/version/#activate-service-version) and [deactivating](https://www.fastly.com/documentation/reference/api/services/version/#deactivate-service-version) a service version.

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

For example, you can stage a Compute service version using curl in a terminal application.

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

### CLI

You can stage or unstage a Compute service version by using the [Fastly CLI](https://www.fastly.com/documentation/reference/cli/):

1. Build the package:

   ```term copy
   $ fastly compute build
   ```

2. Upload the new Wasm package, which will create a draft Compute service version:

   ```term copy
   $ fastly compute update --autoclone
   ```

   This command will output a version number for the draft Compute service version.

3. Stage the draft Compute service version, replacing `<draft version number>` with the version number from the previous step:

   ```term copy
   $ fastly service-version stage --version=<draft version number>
   ```

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](https://www.fastly.com/documentation/guides/getting-started/services/about-services#understanding-fastly-services-and-versions) 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.

### Control panel

1.   Log in to the [Fastly control panel](https://manage.fastly.com).

2.   From the [**Home**](https://manage.fastly.com/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 **Test on staging**. 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.

> **HINT:** If you don't see the IP address for your staging environment in the Fastly control panel, [contact support](https://support.fastly.com).

### API

You can obtain your service's staging IP address using the Fastly API endpoint used for [listing your service's domains](https://www.fastly.com/documentation/reference/api/services/domain/).

```text
GET /service/<service_id>/version/<version_number>/domain?include=staging_ips
```

For example, you can obtain your service's staging IP address using curl in a terminal application.

```term copy nolinenums
$ curl -i \
  -X GET \
  -H "Fastly-Key: $fastly_key" \
  "https://api.fastly.com/service/$service_id/version/$version/domain?include=staging_ips"
```

### 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.

If you're using macOS, flush your DNS cache by entering the following command:

```term copy
$ 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.

| Variable name       | Description                                                                  | Type   | Access    |
| ------------------- | ---------------------------------------------------------------------------- | ------ | --------- |
| `fastly.is_staging` | Returns `true` if VCL code is running in your service's staging environment. | `BOOL` | Read only |

### Compute

The follow Compute variable is available.

| Variable name       | Description                                                                                                    |
| ------------------- | -------------------------------------------------------------------------------------------------------------- |
| `FASTLY_IS_STAGING` | Returns `1` if Compute code is running in your service's staging environment and `0` if running in production. |

## Purging

You can purge cache associated with a staging environment by using the Fastly API [purging endpoints](https://www.fastly.com/documentation/reference/api/purging/). For example, you can purge cache for a staging environment using curl in a terminal application.

### Purging by URL

```term copy nolinenums
$ curl -i \
  -H "Fastly-key: $fastly_key" \
  -X PURGE \
  --connect-to "::$staging_ip:443" \
  "https://$url_to_purge"
```

> **HINT:** If you don't know your staging IP address, refer to our instructions on [obtaining your service's staging IP address](https://www.fastly.com/documentation/guides/getting-started/services/working-with-staging#obtaining-your-services-staging-ip-address) for more information.

### Purging all cache

```term copy nolinenums
$ curl -i \
  -H "Fastly-Key: $fastly_key" \
  -H "Fastly-Purge-Environment: staging" \
  -X POST \
  "https://api.fastly.com/service/$service_id/purge_all"
```

### Purging by surrogate key tag

```term copy nolinenums
$ curl -i \
  -H "Fastly-key: $fastly_key" \
  -H "Fastly-Purge-Environment: staging" \
  -X POST \
  "https://api.fastly.com/service/$service_id/purge/$surrogate_key"
```

### Purging by multiple surrogate key tags

```term copy nolinenums
$ curl -i \
  -H "Fastly-key: $fastly_key" \
  -H "Fastly-Purge-Environment: staging" \
  -H "Content-type: application/json" \
  -X POST \
  -d '{"surrogate_keys":["key"]}' \
  "https://api.fastly.com/service/$service_id/purge"
```

## Deactivating staging for a service version

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

1.   Log in to the [Fastly control panel](https://manage.fastly.com).

2.   From the [**Home**](https://manage.fastly.com/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**.

## Opting out of staging controls in the Fastly control panel

If you've been assigned the [role of superuser](https://www.fastly.com/documentation/guides/account-info/user-and-account-management/about-user-roles-and-permissions), follow the steps below to hide the staging controls in the Fastly control panel:

1.   Log in to the [Fastly control panel](https://manage.fastly.com).

2. From the [**Home**](https://manage.fastly.com/home) page, select a service that you've staged.
3. In the Staging section of the page, click **Opt out**.

   ![the Staging feature opt-out link](/img/staging-opt-out.png)

You'll still be able to stage service versions using the Fastly API, CLI, and Terraform after you hide the staging controls in the Fastly control panel.

## Related content

- [Terraform Fastly VCL service resource](https://registry.terraform.io/providers/fastly/fastly/latest/docs/resources/service_vcl)
- [Terraform Fastly Compute service resource](https://registry.terraform.io/providers/fastly/fastly/latest/docs/resources/service_compute)