/aliyun-esa-manage

name: aliyun-esa-manage
description: Use when managing Alibaba Cloud ESA — deploy HTML/static sites via Pages, manage Edge Routines (ER) for serverless edge functions, use Edge KV for distributed key-value storage, configure Origin Rules for CDN proxy and origin routing, handle site management, DNS records, cache rules, and query traffic analytics via OpenAPI/SDK. Use when working with ESA, edge deployment, edge functions, Pages, ER, KV storage, DNS, cache, origin rules, CDN proxy, site configuration, traffic analytics, bandwidth trends, or top-N rankings.

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`, `GetKvNam