Edge deployment

The Edge deployment method allows you to add the Next-Gen WAF as an edge security service onto Fastly's Edge Cloud platform without needing to make any modifications to your own hosting environment.

Limitations and caveats

Keep in mind the following limitations when working with the edge deployment method:

  • Adding the Next-Gen WAF via the edge deployment method to an existing Fastly service counts against the service chain limit.
  • This feature works with backends defined in VCL services using the API, CLI, or web interface. Backend definitions defined manually in VCL or snippets can be supported by redefining them using the API, CLI, or web interface. This will offer validation and enable a number of features not available to VCL-defined backends, including shielding. Learn more about defining backends in our integration documentation.
  • We automatically support VCL directors as long as they are defined using the Fastly API.

Deploying at the edge

To deploy at the edge, you will need a corp and at least one site to protect. Setup involves making calls to the Signal Sciences API. These API calls will add privileged dynamic VCL snippets to your service that enable inspection.

Creating the edge security service

Create a new edge security service by calling the edge deployment API endpoint. This API call creates a new edge security service associated with your corp and site. You will need to replace ${corpName} and ${siteName} with those of the corp and site you are adding the edge security service to. Your ${corpname} and ${siteName} are both present in the address of your Next-Gen WAF console, such as https://dashboard.signalsciences.net/corps/${corpName}/sites/${siteName}.

$ curl -H "x-api-user:${SIGSCI_EMAIL}" -H "x-api-token:${SIGSCI_TOKEN}" \
-H "Content-Type: application/json" -X PUT \
"https://dashboard.signalsciences.net/api/v0/corps/${corpName}/sites/${siteName}/edgeDeployment"

Run this API call again for each site you want to deploy on.

If successful, you will receive an HTTP 200 response with a blank response body ({}). Once this is returned, wait 1-2 minutes to allow the edge resources to be created.

To confirm the Compute instance resources associated with the site have been created, query the edgeDeployment endpoint again using the following request:

$ curl -H "x-api-user:${SIGSCI_EMAIL}" -H "x-api-token:${SIGSCI_TOKEN}" \
-H "Content-Type: application/json" \
"https://dashboard.signalsciences.net/api/v0/corps/${corpName}/sites/${siteName}/edgeDeployment"

The query should now return the appropriate Compute instance associated with the Next-Gen WAF site in the URL path with no services attached. To attach the appropriate service, refer to Mapping to the Fastly service.

{"AgentHostName":"se--${corpName}--{SiteUID}.edgecompute.app","ServicesAttached":[]}

Mapping to the Fastly service

To map your corp and site to an existing Fastly service and synchronize the origins, follow these steps:

  1. Using the curl command line tool, call the PUT edgeDeployment/${fastlySID} API endpoint in a terminal application:

    $ curl -H "x-api-user:${SIGSCI_EMAIL}" -H "x-api-token:${SIGSCI_TOKEN}" \
    -H "Fastly-Key: ${FASTLY_KEY}" -H 'Content-Type: application/json' -X PUT \
    "https://dashboard.signalsciences.net/api/v0/corps/${corpName}/sites/${siteName}/edgeDeployment/${fastlySID}"

    This API call will create and activate a new service version with dynamic VCL snippets automatically added to the service. By default, the service will be activated and set to 0% traffic ramping. You can override those defaults by providing parameters in the JSON body:

    • activateVersion - activate Fastly service version after clone. Possible values are true or false (unquoted). If not specified, defaults to true.
    • percentEnabled - percentage of traffic to send to the Next-Gen WAF. Possible values are integers values 0 to 100 (unquoted). If not specified, defaults to 0. This can be adjusted later. Check out Traffic ramping for details.

    For example, to disable initial activation and set initial traffic ramping to 10%, add the curl parameter -d '{"activateVersion": false, "percentEnabled": 10}' to the usual call:

    $ curl -H "x-api-user:${SIGSCI_EMAIL}" -H "x-api-token:${SIGSCI_TOKEN}" \
    -H "Fastly-Key: ${FASTLY_KEY}" -H 'Content-Type: application/json' -X PUT \
    -d '{"activateVersion": false, "percentEnabled": 10}' \
    "https://dashboard.signalsciences.net/api/v0/corps/${corpName}/sites/${siteName}/edgeDeployment/${fastlySID}"

    This API call requires the Fastly-Key header for authentication. The Fastly API key must have write access to the Fastly service ID. This API call will create and activate a new service version with dynamic VCL snippets automatically added to the service.

  2. Optionally, follow these steps again for each additional Fastly service that you want to deploy on.

    If your origins change, you will need to call the PUT edgeDeployment/${fastlySID}/backends API endpoint again to resynchronize the backends.

Re-mapping a Fastly service to a new site

To re-assign the Fastly service to a new site, follow these steps:

  1. Using the curl command line tool, call the DELETE edgeDeployment/${fastlySID} API endpoint in a terminal application:

    $ curl -v -H "x-api-user: ${SIGSCI_EMAIL}" -H "x-api-token: ${SIGSCI_TOKEN}" \
    -H "Fastly-Key: ${FASTLY_KEY}" -H 'Content-Type: application/json' -X DELETE \
    "https://dashboard.signalsciences.net/api/v0/corps/${corpName}/sites/${siteName}/edgeDeployment/${fastlySID}"

    This API call requires the Fastly-Key header for authentication. The Fastly API key must have write access to the Fastly service ID. This API call removes all backends from the edge deployment connected to the Fastly service and detaches the Fastly service from the edge deployment.

  2. Using the curl command line tool, call the PUT edgeDeployment API endpoint in a terminal application with the new ${siteName} to create a new edge security service. For example:

    $ curl -H "x-api-user:${SIGSCI_EMAIL}" -H "x-api-token:${SIGSCI_TOKEN}" \
    -H 'Content-Type: application/json' -X PUT \
    "https://dashboard.signalsciences.net/api/v0/corps/${corpName}/sites/${siteName}/edgeDeployment"

    You can verify if a compute instance resource was successfully created by the above step by referring to Create the edge security service.

  3. Using the curl command line tool, call the PUT edgeDeployment/{fastlySID} API endpoint in a terminal application to map the existing Fastly service to the new ${siteName}. For example:

    $ curl -H "x-api-user:${SIGSCI_EMAIL}" -H "x-api-token:${SIGSCI_TOKEN}" \
    -H "Fastly-Key: ${FASTLY_KEY}" -H 'Content-Type: application/json' -X PUT \
    "https://dashboard.signalsciences.net/api/v0/corps/${corpName}/sites/${siteName}/edgeDeployment/${fastlySID}"

    This API call will activate a new service version by updating the existing Next-Gen WAF VCL dynamic snippet with the new edge security service ID.

Synchronizing origins

IMPORTANT

Failure to synchronize origins may result in your traffic not being inspected properly. Requests sent to a backend that does not exist in the edge security service will be served a 503 Unknown wasm backend error. You can correct this issue by running an API call to properly sync origins after any changes.

Some conditions cause origin syncing to occur automatically:

  • Site configuration changes
  • Agent mode changes (e.g., blocking, not blocking)
  • Enabling or disabling IP Anonymization
  • Rule changes (e.g., request rules, signal exclusion rules, CVE rules)
  • Rule list changes (only if the list is being used by a rule)
  • IP addresses flagged

If you change your origins in the Fastly Console, you will need to take additional action to synchronize your changes using an API call. The API call makes sure origin changes applied in the Fastly Console are reflected in the edge security service. For example:

$ curl -v -H "x-api-user:${SIGSCI_EMAIL}" -H "x-api-token:${SIGSCI_TOKEN}" \
-H "Fastly-Key: $FASTLY_KEY" -H "Content-Type:application/json" -X PUT \
"https://dashboard.signalsciences.net/api/v0/corps/${corpName}/sites/${siteName}/edgeDeployment/${fastlySID}/backends"

WAF execution

Once both API calls are completed, your service will automatically be set up with dynamic VCL snippets that control the execution of the Next-Gen WAF. A new service version will be created and activated containing the additional VCL snippets.

The edge security service runs in the vcl_miss and vcl_pass subroutines. Execution priority is set to a high value to enable compatibility with any other VCL snippets that may be in use.

Traffic ramping

You can control the amount of traffic inspected by the edge security service using the Enabled dictionary key. This value is available in the Edge_Security dictionary and is automatically created when you attach a delivery service.

The default value is 0, with numbers greater than zero representing a percentage of the traffic being inspected. This means that unless you change the value of the Edge_Security Edge dictionary, your WAF will be enabled but won't inspect any traffic. If the value is set to 100, all traffic (100%) will be passed through the edge security service. If the value is less than 100, a random sample of the specified percentage will be sent through the edge security service.

NOTE

The Edge_Security Edge dictionary no longer uses The DISABLED field. To control blocking and logging behavior of an edge security service or turn off agent configurations entirely, use the web interface instead.

Health checks

The edge security service includes a health check inside the edge_security function. Using the backend.health property, this health check will skip security processing entirely if the edge security service is unhealthy for any reason. The edge security service is modeled as an origin using the backend type and uses the same health check feature.

The health check works by sending a periodic probe every 15 seconds and checks for an HTTP status code 200 as an expected response. Should a check indicate an unhealthy service, all security processing will be skipped until the service becomes healthy again. It may take up to 60 seconds for all security processing to be skipped.

Determining if you already use health check logic

You can check if your service already uses health check logic by inspecting the value of the x-sigsci-edgemodule HTTP header, which is added to the request prior to being sent to the edge security service. If the value is greater than or equal to 1.6.0, then your VCL includes the health check logic.

Enabling and testing health check logic

To enable the health check for an existing service, make sure your VCL is updated to the latest version by re-running the steps in our instructions for mapping to the Fastly service. Then, test the health check logic by toggling the Agent mode to Off. This will simulate an unhealthy state for the edge security service and processing will be skipped.

Was this guide helpful?

Do not use this form to send sensitive information. If you need assistance, contact support. This form is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.