| name | globalaccelerator-diagnostics |
| version | 1.0.0 |
| last_updated | 2025-04-12 |
| description | Use this skill to investigate and troubleshoot AWS Global Accelerator problems by analyzing accelerator configurations, endpoint health, routing policies, performance metrics, DNS resolution, and following structured runbooks. Activate when: accelerator creation failures, static IP issues, endpoint health check failures, endpoint group configuration, traffic dial problems, client affinity issues, flow log analysis, latency problems, throughput degradation, DNS resolution failures, custom routing issues, DDoS protection concerns, cross-account endpoint problems, ALB/NLB/EC2/EIP integration issues, or the user says something is wrong with Global Accelerator without naming specific symptoms.
|
| compatibility | Requires AWS CLI or SDK access with Global Accelerator, EC2, ELB, CloudWatch, CloudTrail, IAM, and optionally Shield and VPC Flow Logs permissions.
|
Global Accelerator Diagnostics
When to use
Any Global Accelerator investigation where the console alone is insufficient — accelerator configuration analysis, endpoint health debugging, routing policy troubleshooting, performance optimization, DNS resolution issues, custom routing configuration, or security concerns.
Investigation workflow
Step 1 — Collect and triage
aws globalaccelerator list-accelerators
aws globalaccelerator describe-accelerator --accelerator-arn <accelerator-arn>
aws globalaccelerator describe-accelerator-attributes --accelerator-arn <accelerator-arn>
aws cloudwatch get-metric-statistics --namespace AWS/GlobalAccelerator --metric-name NewFlowCount --dimensions Name=Accelerator,Value=<accelerator-arn> --start-time <start> --end-time <end> --period 300 --statistics Sum
aws cloudwatch get-metric-statistics --namespace AWS/GlobalAccelerator --metric-name ProcessedBytesIn --dimensions Name=Accelerator,Value=<accelerator-arn> --start-time <start> --end-time <end> --period 300 --statistics Sum
Step 2 — Domain deep dive
aws globalaccelerator list-listeners --accelerator-arn <accelerator-arn>
aws globalaccelerator list-endpoint-groups --listener-arn <listener-arn>
aws globalaccelerator describe-endpoint-group --endpoint-group-arn <endpoint-group-arn>
aws globalaccelerator list-custom-routing-accelerators
aws globalaccelerator describe-custom-routing-accelerator --accelerator-arn <accelerator-arn>
Step 3 — Detailed investigation
aws globalaccelerator describe-listener --listener-arn <listener-arn>
aws globalaccelerator list-custom-routing-port-mappings --accelerator-arn <accelerator-arn>
aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=globalaccelerator.amazonaws.com
aws ec2 describe-flow-logs --filter Name=resource-id,Values=<vpc-id>
Read references/globalaccelerator-guardrails.md before concluding on any Global Accelerator issue.
Tool quick reference
| Tool / API | When to use |
|---|
describe-accelerator | Full accelerator details and status |
describe-accelerator-attributes | Flow logs and other attributes |
list-listeners | Listener port/protocol configuration |
list-endpoint-groups | Endpoint groups per listener |
describe-endpoint-group | Health checks, traffic dial, endpoints |
list-custom-routing-accelerators | Custom routing accelerators |
list-custom-routing-port-mappings | Port-to-instance mappings |
describe-custom-routing-endpoint-group | Custom routing endpoint group |
| CloudWatch metrics | Flow counts, processed bytes, healthy endpoints |
| CloudTrail | Configuration change audit |
Gotchas: Global Accelerator
- Static anycast IPs: each accelerator gets exactly 2 static anycast IP addresses. These IPs are allocated from the AWS global network and cannot be changed after creation. They persist for the lifetime of the accelerator.
- Endpoint health checks are independent of ELB health checks. Global Accelerator performs its own health checks on endpoints. An endpoint can be healthy in ELB but unhealthy in Global Accelerator if the GA health check port/path differs.
- Traffic dial controls the percentage of traffic routed to an endpoint group (regional). It does NOT control traffic to individual endpoints within a group. Use endpoint weights for per-endpoint traffic distribution.
- Client affinity is per-accelerator listener (not per-endpoint). When enabled, all requests from a client IP go to the same endpoint. Options are NONE (default), SOURCE_IP. Client affinity applies to the listener, not individual endpoint groups.
- Custom routing maps specific ports on the accelerator to specific EC2 instances in a VPC subnet. It does NOT support ALB/NLB endpoints. Custom routing accelerators and standard accelerators are different resource types.
- Global Accelerator is NOT a CDN — it does not cache content. It optimizes the network path using the AWS global network. For caching, use CloudFront. GA and CloudFront serve different purposes and can be used together.
- DDoS protection via AWS Shield Standard is included automatically. Shield Advanced can be associated for enhanced protection and DDoS response team access.
- Endpoint types: ALB, NLB, EC2 instances, and Elastic IP addresses. Each endpoint group can contain up to 10 endpoints. Endpoints must be in the same region as the endpoint group.
- Cross-account endpoints: Global Accelerator supports endpoints in different AWS accounts using cross-account attachment resources.
- Flow logs: Global Accelerator flow logs capture information about IP address traffic going to and from network interfaces in your accelerator. Logs are published to S3.
Anti-hallucination rules
- Always cite specific accelerator configurations, endpoint health status, or API responses as evidence.
- Global Accelerator is NOT a CDN. Never claim it caches content or replaces CloudFront.
- Traffic dial is per-endpoint-group (regional), NOT per-endpoint. Never confuse with endpoint weights.
- Client affinity is per-listener, NOT per-endpoint or per-endpoint-group.
- Custom routing accelerators are separate from standard accelerators. Never mix their APIs.
- Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.
22 runbooks
| Category | IDs | Covers |
|---|
| A — Accelerator | A1-A3 | Creation failures, static IP issues, configuration |
| B — Endpoints | B1-B3 | Endpoint health, endpoint groups, traffic dial |
| C — Routing | C1-C2 | Client affinity, flow logs |
| D — Performance | D1-D2 | Latency, throughput |
| E — DNS | E1-E2 | DNS resolution, custom routing |
| F — Security | F1-F2 | DDoS protection, cross-account endpoints |
| G — Integration | G1-G2 | ALB/NLB/EC2/EIP endpoints, custom routing accelerator |
| Z — Catch-All | Z1 | General troubleshooting |
