| name | wavelength-diagnostics |
| version | 1.0.0 |
| last_updated | 2025-04-12 |
| description | Use this skill to investigate and troubleshoot AWS Wavelength problems by analyzing Wavelength Zone deployments, carrier gateway configurations, compute instances, networking, performance, and Region integration using structured runbooks. Activate when: Wavelength Zone issues, carrier gateway problems, EC2 in Wavelength failures, ECS/EKS on Wavelength errors, carrier IP allocation issues, VPC subnet configuration, latency problems, throughput issues, Region connectivity, S3 access from Wavelength, or the user says something is wrong with Wavelength without naming specific symptoms.
|
| compatibility | Requires AWS CLI or SDK access with EC2, ECS, EKS, VPC, CloudWatch, CloudTrail, and IAM permissions. Wavelength Zone must be enabled in the account.
|
Wavelength Diagnostics
When to use
Any AWS Wavelength investigation where the console alone is insufficient — Wavelength Zone deployment, carrier gateway configuration, compute troubleshooting, networking issues, ultra-low latency optimization, or Region integration problems.
Investigation workflow
Step 1 — Collect and triage
aws ec2 describe-availability-zones --filters "Name=zone-type,Values=wavelength-zone" --all-availability-zones
aws ec2 describe-subnets --filters "Name=availability-zone,Values=<wavelength-zone>"
aws ec2 describe-instances --filters "Name=availability-zone,Values=<wavelength-zone>"
aws ec2 describe-carrier-gateways
aws ec2 describe-addresses --filters "Name=domain,Values=vpc" --query 'Addresses[?CarrierIp!=null]'
Step 2 — Domain deep dive
aws ec2 describe-route-tables --filters "Name=association.subnet-id,Values=<wavelength-subnet-id>"
aws ec2 describe-security-groups --filters "Name=vpc-id,Values=<vpc-id>"
aws ec2 describe-network-interfaces --filters "Name=availability-zone,Values=<wavelength-zone>"
aws ecs list-clusters
aws eks list-clusters
Step 3 — Detailed investigation
aws cloudwatch get-metric-statistics --namespace AWS/EC2 --metric-name NetworkIn --dimensions Name=InstanceId,Value=<instance-id> --start-time <start> --end-time <end> --period 300 --statistics Average
aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=ec2.amazonaws.com --max-results 20
aws ec2 describe-vpc-endpoints --filters "Name=vpc-id,Values=<vpc-id>"
Read references/guardrails.md before concluding on any Wavelength issue.
Tool quick reference
| Tool / API | When to use |
|---|
describe-availability-zones | List Wavelength Zones |
describe-carrier-gateways | Carrier gateway status |
describe-addresses | Carrier IP allocations |
describe-subnets | Wavelength subnet config |
describe-instances | EC2 in Wavelength |
describe-route-tables | Routing configuration |
describe-network-interfaces | ENI details |
describe-vpc-endpoints | VPC endpoint access |
Gotchas: Wavelength
- Wavelength Zones must be explicitly opted-in per account. They are not enabled by default.
- Carrier gateway is required for carrier network (mobile) traffic. It is NOT the same as an internet gateway or NAT gateway.
- Carrier IPs are allocated from the carrier's IP pool, not AWS. They are routable on the carrier's 5G network.
- Not all instance types are available in Wavelength Zones. Typically t3, r5, g4dn families.
- EBS volumes in Wavelength Zones are stored locally. Snapshots go to the parent Region.
- No NAT gateway or internet gateway support in Wavelength Zones. Use carrier gateway for mobile traffic or route through the Region for internet.
- S3 access from Wavelength requires routing through the Region VPC or using S3 gateway endpoints.
- Wavelength subnets are in the same VPC as Region subnets but in a different AZ type.
- DNS resolution uses the VPC resolver in the parent Region.
- Auto Scaling groups can span Wavelength Zones but require Wavelength-specific launch templates.
Anti-hallucination rules
- Always verify the Wavelength Zone is opted-in before diagnosing deployment issues.
- Never suggest using internet gateways or NAT gateways in Wavelength Zones — they are not supported.
- Carrier IPs are different from Elastic IPs — do not confuse them.
- Not all services are available in Wavelength Zones — verify service availability before recommending.
- Latency measurements must account for the carrier network path, not just AWS infrastructure.
- Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.
16 runbooks
| Category | IDs | Covers |
|---|
| A — Zone | A1-A2 | Wavelength zone, carrier gateway |
| B — Compute | B1-B2 | EC2 in Wavelength, ECS/EKS |
| C — Networking | C1-C2 | Carrier IP, VPC subnets |
| D — Performance | D1-D2 | Latency, throughput |
| E — Integration | E1-E2 | Region connectivity, S3 access |
| Z — Catch-All | Z1 | General troubleshooting |
