aliyun-esa-manage

What this skill does

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

```python
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

```javascript
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

```python
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 `DescribeSit