Deploy Acceleration Services with Global Accelerator (GA)
Create a GA instance from scratch and complete end-to-end configuration (Instance -> Acceleration Region -> Listener -> Endpoint Group -> Forwarding Rules) to enable global network acceleration for your services.
1. Scenario Overview
1.1 Applicable Scenarios
Cross-border Web/API acceleration: Overseas users accessing domestic web services, or domestic users accessing overseas services
Global gaming acceleration: Reduce cross-region latency and improve player experience
Audio/video transmission acceleration: Optimize cross-region real-time audio/video communication
Enterprise application acceleration: Accelerate cross-border enterprise internal system access
1.2 Architecture
text
Client -> Accelerated IP/CNAME -> Global Accelerator (GA) -> (Cross-border/Cross-region transit) -> Forwarding Rules -> Endpoint Group -> Origin Server
Configure credentials outside of this session (via aliyun configure in terminal or environment variables in shell profile)
Return and re-run after aliyun configure list shows a valid profile
4. RAM Policy
This skill requires the following RAM permissions. See references/ram-policies.md for the complete list.
5. GA Service Activation Check
Pre-check: GA service must be activated
Before performing any GA operation, you must confirm that the Global Accelerator service has been activated.
bash
aliyun ga DescribeAcceleratorServiceStatus --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills
Check the Status field in the response:
Normal: The service is activated. Proceed with subsequent steps.
Other statuses: The service is not activated. Activate it first:
bash
aliyun ga OpenAcceleratorService --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills
After activation, re-run DescribeAcceleratorServiceStatus to confirm the status is Normal, then proceed.
If the service is not activated and activation fails, STOP here.
6. Parameter Confirmation
Important: Parameter Confirmation -- Before executing any command or API call,
all user-configurable parameters must be confirmed with the user.
Do not assume or use default values without the user's explicit consent.
Parameter
Required
Description
Default
AcceleratorName
Optional
GA instance name
-
AccelerateRegionId
Required
Acceleration region ID (region where users access)
-
IspType
Optional
ISP line type for the acceleration region
China (Hong Kong): BGP_PRO, Others: BGP
Bandwidth
Required
Acceleration region bandwidth (Mbps)
-
ListenerProtocol
Optional
Listener protocol: TCP/UDP/HTTP/HTTPS
HTTPS
ListenerPort
Optional
Listener port
443
CertificateId
Conditional
SSL certificate ID (HTTPS listeners only)
-
EndpointGroupRegion
Required
Endpoint group region (region of the origin server)
Blocking requirement: Before entering the workflow, you MUST use the Read tool to fully read the following files. No steps may be executed until reading is complete.
Instance type and billing restriction: This skill can ONLY create pay-as-you-go (postpay) + CDT Standard GA instances. Creating prepaid (subscription) Standard instances or Basic GA instances of any billing mode is FORBIDDEN. Calling CreateBasicAccelerator is FORBIDDEN. If the user requests a prepaid instance or a Basic instance, inform them that this skill does not support it and suggest creating it manually via the Alibaba Cloud Console.
New instances by default: This skill defaults to creating and configuring new GA instances. Modifying, updating, or deleting existing GA instances or their sub-resources (acceleration regions, listeners, endpoint groups, forwarding rules, etc.) is only permitted when the user explicitly specifies the target GA instance ID to operate on. Without an explicit user instruction identifying a specific existing instance, all operations MUST target newly created instances only.
GA product boundary: Write operations (create/update/delete) are limited to the GA product only. For all other Alibaba Cloud products and services (e.g., CAS, CMS, ECS, SLB, ALB, NLB, OSS), only read-only (Describe/List/Get/Query) operations are permitted. Any non-read-only operation on other products is FORBIDDEN.
General rules (apply throughout the entire workflow):
User-Agent requirement [MANDATORY]: ALL aliyun CLI commands (including ga, sts, cas, cms, and any other Alibaba Cloud service calls) MUST include --user-agent AlibabaCloud-Agent-Skills. This flag must be appended to every CLI invocation without exception. Commands missing this flag are non-compliant.
Parameter confirmation: All user-configurable parameters must be confirmed with the user before execution. Do not assume or use default values.
Status check: After each creation step, query the instance status and wait until it becomes active before proceeding to the next step.
API metadata validation: Before generating CLI commands, use WebFetch to retrieve API metadata and verify parameter accuracy.
URL: https://api.aliyun.com/meta/v1/products/GA/versions/2019-11-20/apis/{api_name}/api.json
7.2 Interaction Flow
text
Step 1: Gather user requirements
|-- Service type (Web/API/Gaming/Audio-Video, etc.)
|-- Origin server information (type, region, IP/domain)
|-- Acceleration region (where users access from)
|-- Protocol and port (HTTP/HTTPS/TCP/UDP, port number)
|-- Whether cross-border acceleration is needed
+-- Certificate information (for HTTPS scenarios)
|
Step 2: Analyze and recommend configuration
|-- Call `aliyun ga ListAccelerateAreas --user-agent AlibabaCloud-Agent-Skills` to get supported acceleration regions and available ISP line types
|-- Analyze requirements based on important-notes.md and GA features
|-- Match the optimal configuration (billing mode, ISP line type, protocol, endpoint type, etc.)
|-- [MANDATORY] Billing mode: ALWAYS use pay-as-you-go (postpay) + CDT. Do NOT guide or recommend the user to create prepaid (subscription) instances
|-- Identify potential issues (cross-border compliance, Proxy Protocol compatibility, HTTP/2 back-to-origin limitations, etc.)
+-- Output recommended configuration with rationale
|
Step 3: Format configuration parameters for user confirmation
|-- Present all configuration objects and parameters in a table
| (Instance, cross-border mode, acceleration region, listener, endpoint group, forwarding rules, etc.)
+-- Wait for user confirmation
|
Step 4: Iterative adjustments
|-- Incorporate user feedback and update configuration parameters
+-- Repeat Step 3 until the user gives final confirmation
|
Step 5: Generate execution plan
|-- List each operation in execution order (target object, parameters, CLI command)
|-- Annotate dependencies between steps (e.g., wait for instance status to become active)
+-- Use WebFetch to retrieve API metadata and verify all parameter accuracy
|
Step 6: Present final configuration summary and execution steps
|-- [MANDATORY] Run `aliyun sts GetCallerIdentity --user-agent AlibabaCloud-Agent-Skills` and display account identity in a table:
| - This step is REQUIRED and MUST NOT be skipped under any circumstances
| - Parse the response and present it in the following table format:
| | Field | Value |
| |------------------|--------------------------------|
| | AccountId | (from response) |
| | IdentityType | (from response) |
| | PrincipalId | (from response) |
| | Arn | (from response) |
|-- Display a "Final Configuration Summary" table with the following format:
| - Table columns MUST be properly aligned using consistent-width separators
| - Use fixed-width padding so that all columns line up cleanly in monospace rendering
| - Example format (values are illustrative only, actual content is dynamic):
|
| | # | Resource Object | Parameter | Value |
| |----|----------------------|----------------|----------------------|
| | 1 | GA Instance | Name | my-ga-instance |
| | | | BillingMode | CDT (pay-as-you-go) |
| | 2 | Acceleration Region | RegionId | us-west-1 |
| | | | ... | ... |
|
| Rules:
| - List each resource object with ALL its confirmed parameters, one parameter per row
| - Group rows by resource object (GA Instance, Cross-border Mode, Acceleration Region, Listener, Endpoint Group, Forwarding Rules, etc.)
| - Do not omit any confirmed parameter
| - The # column only shows the number on the first row of each resource group; subsequent rows leave it blank
|-- Display an "Execution Steps" table with the following format:
| | Step | Operation | API | Depends On | Notes |
| |------|-----------|-----|------------|-------|
| | (List each operation in execution order based on the actual plan generated in Step 5.)
| | (Include dependency references and key notes such as "wait for active", "cross-border only", etc.)
+-- Wait for user to review and confirm both tables
|
Step 7: [MANDATORY] Pre-execution validation and user confirmation
|-- [BLOCKING CHECK] Prepaid (subscription) instance interception:
| - Before requesting user confirmation, verify the billing mode in the confirmed configuration
| - If the configuration contains prepaid/subscription billing (PREPAY/Subscription),
| IMMEDIATELY BLOCK execution and display the following message:
| "⚠️ Automatic creation of prepaid (subscription) GA instances is NOT supported by this skill.
| Prepaid instances must be created manually via the Alibaba Cloud Console: https://ga.console.aliyun.com/
| It is recommended to use the pay-as-you-go (postpay) + CDT billing mode, which charges based on
| actual usage and provides better cost-effectiveness and elastic scaling.
| To continue, please switch the billing mode to pay-as-you-go + CDT and re-confirm the configuration."
| - DO NOT proceed to ask for execution confirmation; return to Step 4 for user to adjust parameters
|-- DO NOT proceed to execute any commands until the user explicitly confirms
|-- Present all information from Step 6 and ask the user: "Please confirm to proceed with execution"
+-- Only after receiving explicit user confirmation (e.g., "确认", "执行", "proceed", "yes"), move to Step 8
|
Step 8: Execute the plan
|-- Execute CLI commands in order (see 7.3 API Execution Order)
|-- [MANDATORY] After EACH step, immediately display the execution result to the user before proceeding:
| - Print the current step number, operation name, and execution status (success/failure/waiting)
| - On success: show key output fields (e.g., resource ID, status) so the user can track progress
| - On waiting: show the current polling status (e.g., "Waiting for instance ga-xxx to become active... current status: configuring")
| - On failure: show the full error message, pause, and wait for user decision
| - Do NOT batch multiple steps silently — each step must be reported individually and sequentially
|-- Check the instance status after each creation step (wait for active) before moving to the next
+-- Pause and report on errors, wait for user decision
|
Step 9: Configuration verification
|-- Query instance status and confirm it is active
|-- Check each created resource (acceleration region, listener, endpoint group, forwarding rules)
|-- Compare actual configuration against the target parameters confirmed in Step 3
|-- Check endpoint health status
|-- [Cross-border scenarios] Perform post-deployment cross-border checks (see 7.4)
|-- End-to-end connectivity test
+-- Output verification report (pass/anomalies with recommendations)
7.3 API Execution Order
Call the following APIs in order to create resources. After each step, wait for the instance status to become active:
text
DescribeAcceleratorServiceStatus -> [Status Not Normal] OpenAcceleratorService
-> CreateAccelerator [pay-as-you-go (postpay) + CDT; do NOT use subscription-based instance specs]
-> [Cross-border scenarios] UpdateAcceleratorCrossBorderStatus -> UpdateAcceleratorCrossBorderMode -> QueryCrossBorderApprovalStatus
-> CreateIpSets
-> CreateListener
-> CreateEndpointGroup
-> [Multi-domain scenarios] CreateForwardingRules
-> [Cross-border scenarios] Post-deployment cross-border checks (see 7.4)
7.4 Cross-border Configuration Key Points
Cross-border mode MUST be set before creating IpSets/Listeners. Do not skip or defer this step.
Mode selection:
Mode
Description
Applicable Scenario
private (Private cross-border)
Higher quality, lower cost
Recommended for production
bgpPro (BGP Premium cross-border)
Temporary alternative
Use only when private fails due to compliance review
If switching to private fails (e.g., cross-border compliance review has not been approved), inform the user:
"Switching cross-border mode to private is pending compliance approval. Currently using bgpPro (BGP Premium).
Please complete the cross-border compliance review, then re-run UpdateAcceleratorCrossBorderMode --CrossBorderMode private."
Post-deployment check:
After all resources are created, call DescribeAccelerator to check the current cross-border mode. If the mode is not private, attempt to switch:
If it still fails, inform the user:
"The current cross-border mode is bgpPro (BGP Premium). It is recommended to switch to private (Private cross-border) mode after the cross-border compliance review is approved for better performance and stability."
8. Verification
Quick Verification
bash
# 1. Confirm instance status and cross-border mode
aliyun ga DescribeAccelerator --AcceleratorId <ga-id> --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills
# 2. Confirm acceleration regions and assigned accelerated IP addresses
aliyun ga ListIpSets --AcceleratorId <ga-id> --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills
# 3. Confirm listener status
aliyun ga ListListeners --AcceleratorId <ga-id> --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills
# 4. Confirm endpoint groups and health status
aliyun ga ListEndpointGroups --AcceleratorId <ga-id> --ListenerId <listener-id> --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills
Acceleration Performance Testing
Must read: When performing acceleration performance testing or latency comparison, use the Read tool to read references/acceleration-test-guide.md and select the appropriate test method based on the listener protocol:
UDP: scripts/udping.py -c 10 <ip> <port> -- requires a UDP Echo Server running on the origin server
You must compare non-accelerated (direct to origin server) and accelerated (through GA) results.
9. Cleanup
bash
# Delete the GA instance (associated sub-resources are automatically cleaned up in the background)
aliyun ga DeleteAccelerator --AcceleratorId <ga-id> --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills
Note: GA APIs use RPC-style PascalCase naming. Nested array parameters require dot notation + --method POST --force.
11. Important Notes
All important operational notes, constraints, defaults, and common pitfalls are maintained in references/important-notes.md.
You must fully read important-notes.md before starting the deployment workflow. It contains critical information on billing, cross-border configuration, status management, and parameter formats that directly affect deployment success.
12. Best Practices
Gather before configuring -- Fully understand the business requirements before planning configuration
Confirm all parameters -- All user-configurable parameters must be confirmed before execution
Check status after each step -- After each creation operation, wait for the instance status to become active
Prefer private cross-border mode -- Use private mode whenever possible for cross-border scenarios
Isolate endpoint groups -- Use separate endpoint groups + forwarding rules for different domains/services
Verify after deployment -- Perform end-to-end configuration verification and connectivity testing after deployment
