Edge Security Acceleration:Get started with Edge Routine

Before you begin

• Your website has been added to ESA and is in the Active state. Refer to Add your website to ESA by NS setup or Add your website to ESA by CNAME setup to add a website.

• An SSL/TLS certificate is configured for the website before you access Edge Routine over HTTPS.

Step 1: Create a routine

1. Log on to the ESA console, and in the left-side navigation pane, choose Edge Computing > Edge Routine.

2. On the Edge Routine page, click Create Routine.

3. On the Create Routine page, select a template provided by ESA to generate routine code. You can also select a template for a custom routine. Click Next.

   

4. On the page that appears, configure parameters including Routine Name and click Submit.

   

   The following list shows the parameters:

   • Routine Name

     Enter a routine name.

     Note

     The name must be 2 to 41 characters and can include lowercase letters, digits, and hyphens (-). It must start with a lowercase letter and cannot end with a hyphen. For example: routine-name. Once created, the routine name cannot be changed.

   • Description

     Optional. Enter a description for the routine.

   • Code Preview

     Preview the routine code.

Step 2: Configure a trigger

Edge Routine of ESA allows you to use triggers to define the calling methods of scripts. You can associate a domain such as er.example.com with a routine. This way, all the traffic destined for the domain is directed to the routine. You can also add a route to specify matching URLs in a routine. In this case, a portion of the traffic destined for the specified URLs is directed to the routine. For example, if you add the er.example.com/test/path/ route in a routine, the traffic to er.example.com/test/path/ is directed to the routine.

1. Upon creation of the Edge Routine, click Associate Domain Name.

   

2. On the Triggers page. You can associate a domain name or add a route to direct traffic destined for a specific domain to the routine.

   Associate a domain name as trigger

   You can connect your website to a routine by associating the domain name of your website with the routine. After you complete the association, you can directly use the domain name to access the routine.

   For example, if you use er.example.com to access a routine after you add the example.com website to ESA, all the requests destined for er.example.com, er.example.com/user, and er.example.com/login are forwarded to the routine.

   1. In the Custom Domains section, click Add Domain Name.

   2. Enter a domain name and click OK.

      

   Note

   If you connect your website to ESA in NS setup, ESA automatically adds a CNAME record for the domain name that you associated.

   If you connect your website to ESA in CNAME setup, ESA automatically assigns a CNAME for the domain name that you associated. You must go to your DNS provider and add a CNAME record to map the domain name to the CNAME.

   Add a route as trigger

   You can create a route to map request URLs to routines. If a request matches a specified URL that is mapped to a routine, the request goes to the routine. In other cases, ESA forwards the request to the origin server to pull the required content.

   In this section, the example.com website is used as an example. If you add the example.com/a* route for the example.com website in a routine, all the requests that match the route such as requests destined for example.com/a, example.com/a1, and example.com/a2 are processed by the routine.

   Requests that do not match the route such as requests destined for example.com/b, example.com/c, and example.com/d are processed by the origin server or points of presence (POPs).

   

   1. Log on to the ESA console, and in the left-side navigation pane, choose Edge Computing > Edge Routine.Select the routine you created, and click Details.

   2. In the Details page, click Triggers > Add Route.

   3. Fill in the route name. Select example.com from the Website drop-down list.

   4. Choose Route Mode.

      Simple Mode

      1. Fill the route. You can add an asterisk (*) as the prefix or suffix of the route to match more URLs

         

      Custom Mode

      1. Choose Custom Mode.

      2. In the If Requests Match... area, specify the conditions for matching incoming requests. For more information about how to configure a rule, see Rules.

         

      • Example 1: If you enter *.example.com/* in the Route field, requests destined for http://www.example.com/ or http://example.com/ are processed by the routine.

      • Example 2: If you enter example.com/a* in the Route field, requests destined for http://example.com/a, http://example.com/a1, or http://example.com/api are processed by the routine.

      • Example 3: If you enter www.example.com/api/* in the Route field, requests destined for http://www.example.com/api/ and requests destined for subpaths such as http://www.example.com/api/users and http://www.example.com/api/products/123 are processed by the routine.

   5. Click OK.

   Important

   • If you enter a domain name with a prefix in the Route field such as *.example.com and www.example.com, you must manually add a record on the Records page in the ESA console to prevent access failures to the routine.

   • If there are multiple routines, the system will exit after the first successful match from top to bottom and will not execute any further matching below.

   Matching rules

   • When you configure a route, you must specify both the hostname of the domain name and the URI path. If you specify only the URI path, such as /path, the route cannot take effect.

   • When you configure a route, you can add an asterisk (*) as the prefix or suffix to match more URLs. An asterisk can match zero or more characters. For example, if you enter example.com/* in the Route field, requests destined for example.com are matched.

   • Routes are case-sensitive. For example, example.com/a and example.com/A specifies two different routes.

   • You cannot include an asterisk (*) or parameter in the middle of a route. For example, example.com/*/path and example.com/path?param=1 are considered invalid routes.

   • If a request matches multiple routes at the same time, the route that is configured at the earliest point in time is preferentially used.

Step 3: Develop and debug a routine

1. On the Edge Routine details page, click the Code tab and develop the routine by using JavaScript (ES6 syntax).

   

2. Debug the routine code. ESA provides a debugging environment. After you compile the code, you can click Save on the Code tab. Then, you can construct an HTTP request method, header, and body on the right side of the Code tab and click Request. ESA directly returns a response after the routine processes the request.

3. After you debug the code, click Generate Version. On the Deploy tab, view the generated version.

   

4. Click Release in the Actions column, in the dialog that appears, set the Deployment Environment parameter to Staging Environment. The code takes effect on the test POP. You can add a binding entry to your local hosts file. This allows you to initiate a request from a real client and view the response on the client.

   

   Note

   We recommend that you deploy the version to all the canary environments before you deploy the version to the production environments.

Step 4: Release the official version

1. On the Edge Routine details page, click the Deploy tab. Click Release in the Actions column of the desired version.

2. In the dialog that appears, set the Deployment Environment parameter to Production Environment.

   

3. Click Release. Then, code of this version is deployed to all POPs of the production environments.