Deprecation notice for Edge Side Code
Edge Side Code (ESC) is a customization option used by several Enterprise customers that allows for more configurability of Cloudflare’s global network features. This code can alter the behavior of Cloudflare’s CDN, enabling logic for specific customer use cases. Currently, a few customers have ESC in place to perform special operations such as advanced header manipulation, host header switching.
Edge Side Code is now deprecated. All configurations currently done via ESC will be removed on 2024-01-01. If you are using ESC, you will need to configure other Cloudflare products to replace your current ESC configuration before this date.
Will this deprecation affect my account?
If your account is currently using ESC, your account team will contact you so that you can discuss the migration from ESC to other existing Cloudflare products.
Which Cloudflare products should I use instead?
The following table contains recommendations for different use cases of ESC:
| Use case | Description | Alternative |
|---|---|---|
| Redirect to URL | Navigate visitors to a different URL without sending the request to the origin server. | Use Single Redirects or Bulk Redirects. |
| Rewrite SNI | Override the hostname used for TLS SNI when connecting to the origin server. | Use Origin Rules to override the Server Name Indication (SNI) value of a request. Cloudflare for SaaS customers can perform SNI rewrites via custom hostnames. |
| Resolve override | Override the resolved hostname used to reach the origin server. | Use Origin Rules to override the resolved hostname of incoming requests. |
| Rewrite URI | Request a different URL from the origin server while displaying the original request URL in the visitor’s browser. | Use Transform Rules to rewrite URLs. |
| Set/clear request headers | Set (or clear) HTTP headers sent to the origin server. | Use Transform Rules to modify request headers. |
| Feature exceptions | Exclude specific requests from one or more Cloudflare security products. | Use Configuration Rules. |
| Send custom error response | Abort the current request, returning a specific response body and/or HTTP status code to the client. | Use custom error responses to define custom responses for errors returned by an origin server or by a Cloudflare product (including Workers). |
| Set/add/remove response headers | Update, add, or remove headers from the response returned by the origin server. | Use Transform Rules to modify response headers. |
| Status redirect | After receiving a response from the origin, conditionally send a redirect back to the client if the origin response code matches a key in the supplied table. | Use Cloudflare Workers. Refer to the Modify response example for a similar use case. |
| Add cookies to response | Set cookies in the response sent to the client. | Use Transform Rules to modify response headers (which includes setting cookies). |
For more complex use cases, consider using Cloudflare Workers.
Can I disable ESC right now to understand the deprecation impact?
Yes, you can disable ESC via API. The API allows you to:
- Understand the impact of disabling ESC on your account or zone.
- Test your alternative configuration with other Cloudflare products (and with ESC disabled) before the sunset date.
What kind of tests can I run?
The available API operations allow you to do the following:
- Disable ESC for individual requests: Any test requests containing a cookie with a specific secret will be processed with ESC disabled.
- Disable/enable ESC for a specific zone: After disabling ESC for a zone, all incoming requests for the zone will have all ESC configurations disabled.
- Disable/enable ESC for an entire account: After disabling ESC for an account, all incoming requests for any zone in the account will have all ESC configurations disabled.
What is the recommended testing strategy?
Cloudflare recommends that you start doing tests using individual HTTP requests, to make sure the triggered rules and the response you get match your expectations.
Start by configuring a secret and including it in a request cookie to disable ESC for specific requests.
If these tests are successful, disable ESC for the entire zone. Perform some additional tests to make sure that your configuration with ESC disabled performs as intended. If you detect any issues, re-enable ESC for the zone.
If you wish, you can also disable ESC for an entire account. This will affect all incoming requests for all zones in your account.
Disabling ESC via API
The available API operations allow you to disable ESC for an account/zone and re-enable ESC in a few seconds and in self-service mode.
You can also configure a secret to perform per-request tests without changing the ESC status (disabled or enabled) for account or zone. Use this feature to check if the appropriate rules are being triggered and if the request/response matches your expectations.
To disable/enable ESC for individual requests, do the following:
Create a secret (up to 100 characters) using the Create ESC secret for a zone or Create ESC secret for an account operation.
Include the secret in your test requests using a cookie named
disable_esc. This will only disable ESC for these test requests addressed at your zone or account, according to the endpoint scope you used in the previous step (zone or account). The following example HTTP request header defines a cookie for disabling ESC for the current request:Cookie: disable_esc=<SECRET>
To change the ESC status for a zone, use the following operations:
To change the ESC status for an account, use the following operations:
API operations
| Name | HTTP verb | Endpoint |
|---|---|---|
| Get ESC secret or status for a zone | GET | /zones/{zone_id}/disable_esc |
| Create ESC secret for a zone | POST | /zones/{zone_id}/disable_esc |
| Disable ESC for a zone | POST | /zones/{zone_id}/disable_esc |
| Re-enable ESC for a zone | DELETE | /zones/{zone_id}/disable_esc |
| Get ESC secret or status for an account | GET | /accounts/{account_id}/disable_esc |
| Create ESC secret for an account | POST | /accounts/{account_id}/disable_esc |
| Disable ESC for an account | POST | /accounts/{account_id}/disable_esc |
| Re-enable ESC for an account | DELETE | /accounts/{account_id}/disable_esc |
To invoke an API operation, append the operation endpoint to the Cloudflare API base URL:
https://api.cloudflare.com/client/v4 API examples
Get ESC status for a zone
This example obtains the current status of the Disable ESC setting for the specified zone. The same endpoint will return the currently configured ESC secret for the zone, if configured.
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/disable_esc" \
--header "X-Auth-Key: <API_KEY>" \
--header "X-Auth-Email: <EMAIL>"
The following example response states that ESC is disabled for the entire {zone_id} zone:
{"always": true}
The following example response includes the previously configured secret for the zone using the Create ESC secret for a zone operation:
{"with_secret": "<SECRET>"}
Create ESC secret for a zone
This POST request example configures an ESC secret for disabling ESC in specific requests for the {zone_id} zone, setting the secret to MySecretString321#.
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/disable_esc" \
--header "X-Auth-Key: <API_KEY>" \
--header "X-Auth-Email: <EMAIL>" \
--header "Content-Type: application/json" \
--data '{ "with_secret": "MySecretString321#" }'
The maximum secret length is 100 characters.
To use the secret, include a cookie named disable_esc with the secret value in any requests for which you want to have ESC disabled:
curl "https://example.com/company_app" \
--header "Cookie: disable_esc=MySecretString321#"
This will only disable ESC for the request that includes the cookie.
Disable ESC for a zone
This POST request example disables ESC for all incoming requests of {zone_id} zone.
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/disable_esc" \
--header "X-Auth-Key: <API_KEY>" \
--header "X-Auth-Email: <EMAIL>" \
--header "Content-Type: application/json" \
--data '{ "always": true }'
Re-enable ESC for a zone
This example re-enables ESC for the {zone_id} zone.
curl --request DELETE \
"https://api.cloudflare.com/client/v4/zones/{zone_id}/disable_esc" \
--header "X-Auth-Key: <API_KEY>" \
--header "X-Auth-Email: <EMAIL>"
Get ESC status for an account
This example obtains the current status of Disable ESC setting for the specified account. The same endpoint will return the currently configured ESC secret for the account, if configured.
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/disable_esc" \
--header "X-Auth-Key: <API_KEY>" \
--header "X-Auth-Email: <EMAIL>"
The following example response states that ESC is disabled for the entire {account_id} account:
{ "always": true }
The following example response includes the previously configured secret for the account using the Create ESC secret for an account operation:
{ "with_secret": "<SECRET>" }
Create ESC secret for an account
This example configures an ESC secret for disabling ESC in specific requests for the {account_id} account, setting the secret to MySecretString321#.
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/disable_esc" \
--header "X-Auth-Key: <API_KEY>" \
--header "X-Auth-Email: <EMAIL>" \
--header "Content-Type: application/json" \
--data '{ "with_secret": "MySecretString321#" }'
The maximum secret length is 100 characters.
To use the secret, include a cookie named disable_esc with the secret value in any requests for which you want to have ESC disabled:
curl "https://example.com/company_app" \
--header "Cookie: disable_esc=MySecretString321#"
This will only disable ESC for the request that includes the cookie.
Disable ESC for an account
This POST request example disables ESC for all incoming requests of {account_id} account.
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/disable_esc" \
--header "X-Auth-Key: <API_KEY>" \
--header "X-Auth-Email: <EMAIL>" \
--header "Content-Type: application/json" \
--data '{ "always": true }'
Re-enable ESC for an account
This example re-enables ESC for the {account_id} account.
curl --request DELETE \
"https://api.cloudflare.com/client/v4/accounts/{account_id}/disable_esc" \
--header "X-Auth-Key: <API_KEY>" \
--header "X-Auth-Email: <EMAIL>"
Final remarks
Some configurations currently done using ESC will not be directly available in any other Cloudflare product. In this rare situation, Cloudflare will discontinue the custom behavior currently obtained through ESC and work with you to help you understand alternative solutions for your use cases.