docs: Add VPC Lattice concepts and troubleshooting guide (#9351)

awscli/examples/vpc-lattice/_concepts.rst

@@ -0,0 +1,294 @@
+This section explains the core concepts and components of Amazon VPC Lattice, along with common usage patterns and examples.
+
+Core Concepts
+++++++++++++
+
+Amazon VPC Lattice is an application networking service that lets you connect, secure, and monitor all your services across multiple VPCs and AWS accounts. Here are the key concepts:
+
+Service Network
+~~~~~~~~~~~~~~
+A service network is a logical boundary for a group of services. It acts as a container where you can:
+
+* Connect multiple VPCs
+* Define shared security policies
+* Monitor service-to-service communication
+* Implement consistent access controls
+
+Services
+~~~~~~~~
+A service represents an application that you want to make available to other applications. Services:
+
+* Can be accessed via DNS names
+* Support HTTP/HTTPS traffic
+* Can have multiple listeners
+* Can route traffic to different target groups
+
+Target Groups
+~~~~~~~~~~~~
+Target groups define where your service traffic should be directed. They can be:
+
+* Instance-based (EC2 instances)
+* IP-based (IP addresses)
+* Lambda functions
+* Application Load Balancers (ALB)
+
+Components and Their Relationships
+++++++++++++++++++++++++++++++++
+
+Service Network Association
+~~~~~~~~~~~~~~~~~~~~~~~~~
+There are two types of associations:
+
+1. Service Association: Links a service to a service network
+2. VPC Association: Links a VPC to a service network
+
+This creates the networking fabric that allows services to communicate.
+
+Listeners and Rules
+~~~~~~~~~~~~~~~~~
+Listeners define how your service accepts traffic:
+
+* Protocol (HTTP/HTTPS)
+* Port number
+* Rules for routing traffic
+* Optional authentication policies
+
+Authentication and Authorization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+VPC Lattice supports multiple authentication methods:
+
+* None (open access)
+* IAM authentication
+* Custom authentication via Lambda
+
+End-to-End Example
++++++++++++++++++
+
+Here's a complete example of setting up a service network with two services:
+
+1. Create a service network::
+
+    aws vpc-lattice create-service-network \
+        --name my-service-network
+
+2. Create two services::
+
+    aws vpc-lattice create-service \
+        --name service-a \
+        --auth-type NONE
+
+    aws vpc-lattice create-service \
+        --name service-b \
+        --auth-type AWS_IAM
+
+3. Create target groups for each service::
+
+    aws vpc-lattice create-target-group \
+        --name service-a-tg \
+        --type INSTANCE \
+        --config file://tg-config.json
+
+Contents of ``tg-config.json``::
+
+    {
+        "port": 80,
+        "protocol": "HTTP",
+        "protocolVersion": "HTTP1",
+        "vpcIdentifier": "vpc-1234567890abcdef0"
+    }
+
+4. Create listeners for the services::
+
+    aws vpc-lattice create-listener \
+        --service-identifier service-a \
+        --name http-listener \
+        --protocol HTTP \
+        --port 80 \
+        --default-action file://default-action.json
+
+Contents of ``default-action.json``::
+
+    {
+        "forward": {
+            "targetGroups": [
+                {
+                    "targetGroupIdentifier": "service-a-tg",
+                    "weight": 100
+                }
+            ]
+        }
+    }
+
+5. Associate services with the service network::
+
+    aws vpc-lattice create-service-network-service-association \
+        --service-network-identifier my-service-network \
+        --service-identifier service-a
+
+6. Associate VPCs with the service network::
+
+    aws vpc-lattice create-service-network-vpc-association \
+        --service-network-identifier my-service-network \
+        --vpc-identifier vpc-1234567890abcdef0
+
+Best Practices
++++++++++++++
+
+Security
+~~~~~~~~
+* Use IAM authentication when possible
+* Implement least-privilege access policies
+* Use HTTPS listeners for sensitive traffic
+* Regularly audit service network associations
+* Rotate security credentials regularly
+* Use AWS Organizations SCPs to control VPC Lattice permissions
+* Implement network ACLs and security groups for additional protection
+
+Monitoring
+~~~~~~~~~
+* Enable access logs for auditing
+* Set up CloudWatch metrics for monitoring
+* Use AWS X-Ray for tracing requests
+* Monitor target group health status
+* Configure CloudWatch alarms for key metrics:
+    * TargetGroupHealthyCount
+    * RequestCount
+    * HTTP 4xx/5xx errors
+* Use AWS CloudTrail for API activity monitoring
+
+Scalability
+~~~~~~~~~~
+* Use multiple target groups for high availability
+* Implement health checks for automatic failover
+* Configure appropriate timeouts and retries
+* Use weighted target groups for traffic distribution
+* Consider the following limits:
+    * Services per service network
+    * Target groups per service
+    * Rules per listener
+* Implement circuit breakers for downstream service protection
+
+Performance Optimization
+~~~~~~~~~~~~~~~~~~~~~~
+* Use connection pooling when possible
+* Configure appropriate keep-alive settings
+* Implement request timeouts based on service SLAs
+* Use caching where appropriate
+* Monitor and tune target group settings:
+    * Health check intervals
+    * Deregistration delay
+    * Slow start duration
+
+Troubleshooting Guide
++++++++++++++++++++
+
+Common Issues and Solutions
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Service Discovery Issues
+-------------------------
+If services cannot discover each other:
+
+* Verify DNS resolution is working::
+
+    aws vpc-lattice get-service \
+        --service-identifier service-a \
+        --query 'dnsEntry'
+
+* Check VPC DNS settings::
+
+    aws ec2 describe-vpc-attribute \
+        --vpc-id vpc-1234567890abcdef0 \
+        --attribute enableDnsSupport
+
+* Ensure service network associations are active::
+
+    aws vpc-lattice list-service-network-service-associations \
+        --service-network-identifier my-service-network \
+        --status ACTIVE
+
+2. Authentication Failures
+------------------------
+For IAM authentication issues:
+
+* Verify IAM policy attachments
+* Check for correct principal configuration
+* Ensure clock synchronization for signature verification
+* Review CloudWatch logs for specific authentication errors
+
+3. Health Check Failures
+----------------------
+If targets are being marked unhealthy:
+
+* Verify target health status::
+
+    aws vpc-lattice get-target-group-health \
+        --target-group-identifier tg-1234567890abcdef0
+
+* Common causes:
+    * Security group rules blocking health check traffic
+    * Application not responding on configured port
+    * Incorrect health check path configuration
+    * Target instance/container not running
+
+4. Performance Issues
+-------------------
+For latency or timeout problems:
+
+* Check target group metrics::
+
+    aws cloudwatch get-metric-statistics \
+        --namespace AWS/VpcLattice \
+        --metric-name TargetResponseTime \
+        --dimensions Name=TargetGroupId,Value=tg-1234567890abcdef0
+
+* Review and adjust:
+    * Connection timeouts
+    * Request timeouts
+    * Health check intervals
+    * Target group attributes
+
+Diagnostic Commands
+~~~~~~~~~~~~~~~~~
+
+1. Check Service Status::
+
+    aws vpc-lattice get-service \
+        --service-identifier service-a \
+        --query 'status'
+
+2. List Active Listeners::
+
+    aws vpc-lattice list-listeners \
+        --service-identifier service-a \
+        --status ACTIVE
+
+3. Verify Target Group Configuration::
+
+    aws vpc-lattice get-target-group \
+        --target-group-identifier tg-1234567890abcdef0
+
+4. Review Access Logs::
+
+    aws logs get-log-events \
+        --log-group-name /aws/vpc-lattice/my-service-network \
+        --log-stream-name access-logs
+
+Common Use Cases
++++++++++++++++
+
+1. Service-to-Service Communication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Connect microservices across multiple VPCs while maintaining security and observability.
+
+2. Multi-Account Architecture
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Share services across AWS accounts while maintaining centralized control and monitoring.
+
+3. Zero Trust Security
+~~~~~~~~~~~~~~~~~~~~
+Implement fine-grained access controls and authentication for all service-to-service communication.
+
+4. API Gateway Alternative
+~~~~~~~~~~~~~~~~~~~~~~~~
+Use VPC Lattice as an internal API gateway for service-to-service communication within your VPCs.