diff --git a/awscli/examples/vpc-lattice/_concepts.rst b/awscli/examples/vpc-lattice/_concepts.rst new file mode 100644 index 000000000000..f61196780a8f --- /dev/null +++ b/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. \ No newline at end of file