Aliyun Esa Manage

Category: service

Edge Security Acceleration (ESA) - Pages, Edge Routine, KV, Site Management, Analytics & More

Use Alibaba Cloud OpenAPI (RPC) with official Python SDK to manage all ESA capabilities.

Alibaba Cloud ESA provides five core capabilities:

• Pages — Deploy HTML or static directories to edge nodes (quick deployment flow based on Edge Routine)
• Edge Routine (ER) — Full lifecycle management of serverless edge functions
• Edge KV — Distributed edge key-value storage with Namespace/Key/Value management
• Site Management — Site management, DNS records, cache rules, certificates, etc.
• Analytics — Traffic analysis, time-series trends, Top-N rankings, bandwidth statistics, request metrics

Use Python SDK uniformly to call ESA OpenAPI.

Prerequisites

• Prepare AccessKey (RAM user/role with least privilege).
• Install Python SDK: pip install alibabacloud_esa20240910 alibabacloud_tea_openapi alibabacloud_credentials
• ESA OpenAPI is RPC style; prefer SDK or OpenAPI Explorer to avoid manual signing.

SDK quickstart

from alibabacloud_esa20240910.client import Client as Esa20240910Client
from alibabacloud_esa20240910 import models as esa_models
from alibabacloud_tea_openapi import models as open_api_models


def create_client(region_id: str = "cn-hangzhou") -> Esa20240910Client:
    config = open_api_models.Config(
        region_id=region_id,
        endpoint="esa.cn-hangzhou.aliyuncs.com",
    )
    return Esa20240910Client(config)

Pages — Edge Page Deployment

Pages is a quick deployment flow based on Edge Routine, deploying HTML or static directories to the edge.

HTML Page Deployment Flow

CreateRoutine → GetRoutineStagingCodeUploadInfo → Upload code to OSS
→ CommitRoutineStagingCode → PublishRoutineCodeVersion(staging)
→ PublishRoutineCodeVersion(production) → GetRoutine(get access URL)

Static Directory Deployment Flow

CreateRoutine → CreateRoutineWithAssetsCodeVersion → Package zip and upload to OSS
→ Poll GetRoutineCodeVersionInfo(wait for available)
→ CreateRoutineCodeDeployment(staging) → CreateRoutineCodeDeployment(production)
→ GetRoutine(get access URL)

Zip Package Structure

The zip package structure depends on EDGE_ROUTINE_TYPE (automatically determined by checkEdgeRoutineType based on whether entry file and assets directory exist):

• JS_ONLY: routine/index.js (bundled with esbuild or --no-bundle to read source files directly)
• ASSETS_ONLY: All static files under assets/, maintaining original directory structure
• JS_AND_ASSETS: routine/index.js + assets/ static resources (most common)

The assets/ path is relative to assets.directory in configuration. Configuration priority: CLI args > esa.jsonc / esa.toml.

Key Notes

• Function name rules: lowercase letters/numbers/hyphens, start with lowercase letter, length >= 2
• Same name function: Reuse if exists, deploy new version code
• Deploy to both staging and production by default
• After successful deployment, get defaultRelatedRecord via GetRoutine as access domain

Bind Custom Domain (CNAME-Access Sites)

For CNAME-access sites, binding a custom domain to a Pages/ER routine requires:

1. CreateRecord(A/AAAA, proxied=true)     → Register domain in ESA CDN
2. CreateRoutineRoute(rule expression)     → Route traffic to Edge Routine
3. External DNS: CNAME → record_cname      → Point domain to ESA CDN
4. ApplyCertificate(lets_encrypt)          → Provision SSL certificate

Critical: Do NOT use CreateRoutineRelatedRecord for CNAME-access sites — it doesn't create a visible DNS record, causing CDN to fall back to origin. Use A/AAAA record + Route instead.

SDK note: CreateRoutineRoute parameter is rule (ESA rule expression like (http.host eq "domain")), NOT route.

Detailed reference: references/pages.md (section: Bind Custom Domain)

Edge Routine (ER) — Edge Functions

Manage the complete lifecycle of serverless edge functions via Python SDK.

Core Workflow

CreateRoutine → GetRoutineStagingCodeUploadInfo → Upload code to OSS
→ CommitRoutineStagingCode → PublishRoutineCodeVersion
→ (CreateRoutineRoute) → GetRoutine

API Summary

• Function Management: CreateRoutine, DeleteRoutine, GetRoutine, GetRoutineUserInfo, ListUserRoutines
• Code Version: GetRoutineStagingCodeUploadInfo, CommitRoutineStagingCode, PublishRoutineCodeVersion, DeleteRoutineCodeVersion
• Routes: CreateRoutineRoute, UpdateRoutineRoute, DeleteRoutineRoute, GetRoutineRoute, ListRoutineRoutes, ListSiteRoutes
• Related Records: CreateRoutineRelatedRecord, DeleteRoutineRelatedRecord, ListRoutineRelatedRecords

ER Code Format

export default {
  async fetch(request) {
    return new Response("Hello", {
      headers: { "content-type": "text/html;charset=UTF-8" },
    });
  },
};

Detailed reference: references/er.md

Edge KV — Edge Key-Value Storage

Distributed edge key-value storage, readable and writable in Edge Routine, also manageable via OpenAPI/SDK.

Core Concepts

• Namespace: Isolation container for KV data, Key max 512 chars, Value max 2MB (high capacity 25MB)
• Supports TTL expiration: Expiration (Unix timestamp) or ExpirationTtl (seconds)

API Summary

• Namespace: CreateKvNamespace, DeleteKvNamespace, GetKvNamespace, GetKvAccount, DescribeKvAccountStatus
• Single Key Operations: PutKv, GetKv, GetKvDetail, DeleteKv, PutKvWithHighCapacity
• Batch Operations: BatchPutKv, BatchDeleteKv, BatchPutKvWithHighCapacity, BatchDeleteKvWithHighCapacity, ListKvs

Quick Start

client = create_client()

# Create namespace
client.create_kv_namespace(esa_models.CreateKvNamespaceRequest(namespace="my-ns"))

# Write
client.put_kv(esa_models.PutKvRequest(namespace="my-ns", key="k1", value="v1"))

# Read
resp = client.get_kv(esa_models.GetKvRequest(namespace="my-ns", key="k1"))

Detailed reference: references/kv.md

Site Management — Site Management

Use Python SDK to manage ESA sites, DNS records, cache rules, etc.

API behavior notes

• Most list APIs support pagination via PageNumber + PageSize.
• ListSites returns sites across all regions; no need to iterate regions.
• Newly created sites start as pending; complete access verification via VerifySite to activate.
• Deleting a site removes all associated configuration.
• UpdateSiteAccessType can switch between CNAME and NS, but switching to CNAME may fail if incompatible DNS records exist.
• DNS record APIs (CreateRecord, ListRecords, etc.) work for both NS and CNAME connected sites. CNAME sites are limited to CNAME and A/AAAA types only, and records cannot disable acceleration (proxy must stay enabled).
• DNS record Type parameter must be exact: use A/AAAA (not A), CNAME, MX, TXT, NS, SRV, CAA.
• CreateCacheRule supports two config types: global (site-wide default) and rule (conditional rule with match expression).

Workflow

1. Confirm target site ID, access type (CNAME/NS), and desired action.
2. Find API group and exact operation name in references/api_overview.md.
3. Call API with Python SDK (preferred) or OpenAPI Explorer.
4. Verify results with describe/list APIs.
5. If you need repeatable inventory or summaries, use scripts/ and write outputs under output/aliyun-esa-manage/.

SDK priority

1. Python SDK (preferred)
2. OpenAPI Explorer
3. Other SDKs (only if Python is not feasible)

Python SDK scripts (recommended for inventory)

• List all ESA sites: scripts/list_sites.py
• Summarize sites by plan: scripts/summary_sites_by_plan.py
• Check site status: scripts/check_site_status.py
• List DNS records for a site: scripts/list_dns_records.py

Analytics — Traffic Analysis

Query and analyze ESA site traffic data using DescribeSiteTimeSeriesData and DescribeSiteTopData APIs.

Core Features

• Time-Series Data: Query traffic trends with configurable time granularity
• Top-N Rankings: Get rankings by country/IP/host/path/status code dimensions
• Multiple Metrics: Traffic, Requests, RequestTraffic, PageView
• Rich Dimensions: Country, province, ISP, browser, device, host, path, status code, etc.

Two Main APIs

1. DescribeSiteTimeSeriesData - Time-Series Trends

Query traffic trends over time, returning aggregated data points.

Time Granularity Rules:

2. DescribeSiteTopData - Top-N Rankings

Query Top-N ranking data by various dimensions.

Limit Options: 5, 10, 150

Available Metrics (FieldName)

Available Dimensions

Geographic Dimensions: ClientCountryCode (country), ClientProvinceCode (province), ClientISP (ISP), ClientASN

Client Info: ClientIP, ClientIPVersion, ClientBrowser, ClientDevice, ClientOS

Request Details: ClientRequestHost, ClientRequestMethod, ClientRequestPath, ClientRequestProtocol, ClientRequestQuery, ClientRequestReferer, ClientRequestUserAgent

Response/Cache: EdgeCacheStatus, EdgeResponseStatusCode, EdgeResponseContentType, OriginResponseStatusCode

Others: ALL (aggregated), SiteId (account-level query), Version, ClientSSLProtocol, ClientXRequestedWith

Error Handling

Detailed reference: references/time-series.md, references/top-data.md, references/fields.md

Origin Rules — CDN 代理回源

Origin Rules 控制 ESA CDN 如何回源到源站。当需要将子域名通过 ESA CDN 代理到后端服务器时使用。

CDN 代理回源工作流

CreateRecord(A, proxied=true) → ApplyCertificate → CreateOriginRule → 验证