Amazon VPC Lattice Diagnostics
When to use
Any Amazon VPC Lattice investigation where the console alone is insufficient — service network management, service creation and configuration, target group health, listener rules and routing, auth policies, cross-account sharing via RAM, DNS resolution, health checks, access logging, or VPC association issues.
Investigation workflow
Step 1 — Collect and triage
aws vpc-lattice list-service-networks
aws vpc-lattice list-services
aws vpc-lattice list-target-groups
aws vpc-lattice get-service-network --service-network-identifier <id>
aws vpc-lattice get-service --service-identifier <id>
Step 2 — Domain deep dive
aws vpc-lattice list-service-network-service-associations --service-network-identifier <id>
aws vpc-lattice list-service-network-vpc-associations --service-network-identifier <id>
aws vpc-lattice list-targets --target-group-identifier <id>
aws vpc-lattice list-listeners --service-identifier <id>
aws vpc-lattice list-rules --service-identifier <id> --listener-identifier <id>
aws vpc-lattice get-auth-policy --resource-identifier <id>
Step 3 — Detailed investigation
aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=vpc-lattice.amazonaws.com --max-results 20
aws logs filter-log-events --log-group-name <lattice-access-log-group> --filter-pattern "{ $.responseCode = 4* }"
aws cloudwatch get-metric-statistics --namespace AWS/VPCLattice --metric-name RequestCount --dimensions Name=ServiceName,Value=<name> --start-time <start> --end-time <end> --period 300 --statistics Sum
Read references/guardrails.md before concluding on any VPC Lattice issue.
Tool quick reference
| Tool / API |
When to use |
get-service-network |
Check service network status and config |
get-service |
Check service status, DNS, custom domain |
list-targets |
Check target registration and health |
get-auth-policy |
Check auth policy on service network or service |
list-service-network-vpc-associations |
Check VPC associations |
get-access-log-subscription |
Check access log configuration |
| CloudWatch Metrics |
Monitor request counts, latency, errors |
| CloudTrail |
Audit configuration changes |
Gotchas: Amazon VPC Lattice
- VPC Lattice uses a managed DNS name for each service. Clients in associated VPCs resolve the service DNS name automatically via the VPC Lattice managed prefix (169.254.171.0/24 and fd00:ec2:80::/48). If DNS resolution fails, check VPC association status and DNS settings.
- Auth policies are evaluated at TWO levels: service network AND service. Both must allow the request. A deny at either level blocks the request. Auth policies use IAM policy syntax but are NOT IAM policies — they are VPC Lattice resource policies.
- Target groups support IP, Instance, Lambda, and ALB target types. Each type has different health check behavior. Lambda targets do not support health checks. ALB targets require the ALB to be in a VPC associated with the service network.
- Cross-account sharing uses AWS RAM. The service network owner shares via RAM, and the consumer account accepts the share and associates their VPC. Services can also be shared cross-account and associated with shared service networks.
- Access logs must be explicitly enabled per service network. Logs can go to CloudWatch Logs, S3, or Kinesis Data Firehose. Without access logs, you cannot see request/response details.
- Listener rules use path-based and header-based matching. Rules are evaluated in priority order (lowest number first). The default rule catches unmatched requests. Weighted target groups enable traffic splitting.
Anti-hallucination rules
- Always cite specific service network IDs, service IDs, or API responses as evidence.
- Auth policies exist at BOTH service network and service level. Never ignore either.
- VPC Lattice DNS requires VPC association. Never claim automatic DNS resolution without association.
- Lambda targets do NOT support health checks. Never suggest configuring them.
- Access logs are NOT enabled by default. Never assume they exist.
- Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.
14 runbooks
| Category |
IDs |
Covers |
| A — Service Network |
A1–A2 |
Creation failures, configuration |
| B — Services |
B1–B2 |
Service creation, listener config |
| C — Target Groups |
C1–C2 |
Target registration, health issues |
| D — Listener Rules |
D1–D2 |
Rule matching, routing issues |
| E — Auth Policies |
E1–E2 |
Policy evaluation, cross-level auth |
| F — Cross-Account |
F1–F2 |
RAM sharing, consumer association |
| G — DNS & Health |
G1–G2 |
DNS resolution, health checks |
| H — Logging & VPC |
H1–H2 |
Access logs, VPC association |
| Z — Catch-All |
Z1 |
General troubleshooting |
1---2name: vpclattice-diagnostics3description: Use this skill to investigate and troubleshoot Amazon VPC Lattice problems by analyzing service networks, services, target groups, listener rules, auth policies, cross-account sharing, DNS resolution, health checks, access logs, and VPC associations following structured runbooks. Activate when: service network creation failures, service registration issues, target group health failures, listener rule mismatches, auth policy denials, cross-account sharing problems, DNS resolution failures, health check failures, missing access logs, VPC association errors, or the user says something is wrong with VPC Lattice without naming specific symptoms.4---56# Amazon VPC Lattice Diagnostics78## When to use910Any Amazon VPC Lattice investigation where the console alone is insufficient — service network management, service creation and configuration, target group health, listener rules and routing, auth policies, cross-account sharing via RAM, DNS resolution, health checks, access logging, or VPC association issues.1112## Investigation workflow1314### Step 1 — Collect and triage1516```17aws vpc-lattice list-service-networks18aws vpc-lattice list-services19aws vpc-lattice list-target-groups20aws vpc-lattice get-service-network --service-network-identifier <id>21aws vpc-lattice get-service --service-identifier <id>22```2324### Step 2 — Domain deep dive2526```27aws vpc-lattice list-service-network-service-associations --service-network-identifier <id>28aws vpc-lattice list-service-network-vpc-associations --service-network-identifier <id>29aws vpc-lattice list-targets --target-group-identifier <id>30aws vpc-lattice list-listeners --service-identifier <id>31aws vpc-lattice list-rules --service-identifier <id> --listener-identifier <id>32aws vpc-lattice get-auth-policy --resource-identifier <id>33```3435### Step 3 — Detailed investigation3637```38aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=vpc-lattice.amazonaws.com --max-results 2039aws logs filter-log-events --log-group-name <lattice-access-log-group> --filter-pattern "{ $.responseCode = 4* }"40aws cloudwatch get-metric-statistics --namespace AWS/VPCLattice --metric-name RequestCount --dimensions Name=ServiceName,Value=<name> --start-time <start> --end-time <end> --period 300 --statistics Sum41```4243Read `references/guardrails.md` before concluding on any VPC Lattice issue.4445## Tool quick reference4647| Tool / API | When to use |48|------------|-------------|49| `get-service-network` | Check service network status and config |50| `get-service` | Check service status, DNS, custom domain |51| `list-targets` | Check target registration and health |52| `get-auth-policy` | Check auth policy on service network or service |53| `list-service-network-vpc-associations` | Check VPC associations |54| `get-access-log-subscription` | Check access log configuration |55| CloudWatch Metrics | Monitor request counts, latency, errors |56| CloudTrail | Audit configuration changes |5758## Gotchas: Amazon VPC Lattice5960- VPC Lattice uses a managed DNS name for each service. Clients in associated VPCs resolve the service DNS name automatically via the VPC Lattice managed prefix (169.254.171.0/24 and fd00:ec2:80::/48). If DNS resolution fails, check VPC association status and DNS settings.61- Auth policies are evaluated at TWO levels: service network AND service. Both must allow the request. A deny at either level blocks the request. Auth policies use IAM policy syntax but are NOT IAM policies — they are VPC Lattice resource policies.62- Target groups support IP, Instance, Lambda, and ALB target types. Each type has different health check behavior. Lambda targets do not support health checks. ALB targets require the ALB to be in a VPC associated with the service network.63- Cross-account sharing uses AWS RAM. The service network owner shares via RAM, and the consumer account accepts the share and associates their VPC. Services can also be shared cross-account and associated with shared service networks.64- Access logs must be explicitly enabled per service network. Logs can go to CloudWatch Logs, S3, or Kinesis Data Firehose. Without access logs, you cannot see request/response details.65- Listener rules use path-based and header-based matching. Rules are evaluated in priority order (lowest number first). The default rule catches unmatched requests. Weighted target groups enable traffic splitting.6667## Anti-hallucination rules68691. Always cite specific service network IDs, service IDs, or API responses as evidence.702. Auth policies exist at BOTH service network and service level. Never ignore either.713. VPC Lattice DNS requires VPC association. Never claim automatic DNS resolution without association.724. Lambda targets do NOT support health checks. Never suggest configuring them.735. Access logs are NOT enabled by default. Never assume they exist.746. Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.7576## 14 runbooks7778| Category | IDs | Covers |79|----------|-----|--------|80| A — Service Network | A1–A2 | Creation failures, configuration |81| B — Services | B1–B2 | Service creation, listener config |82| C — Target Groups | C1–C2 | Target registration, health issues |83| D — Listener Rules | D1–D2 | Rule matching, routing issues |84| E — Auth Policies | E1–E2 | Policy evaluation, cross-level auth |85| F — Cross-Account | F1–F2 | RAM sharing, consumer association |86| G — DNS & Health | G1–G2 | DNS resolution, health checks |87| H — Logging & VPC | H1–H2 | Access logs, VPC association |88| Z — Catch-All | Z1 | General troubleshooting |
aws-samples