simplify infrastructure architecture

Examples/ServiceLifecycle/INFRASTRUCTURE.md

@@ -1,154 +1,125 @@
-# Infrastructure Documentation
-
-This document describes the AWS infrastructure defined in `template.yaml` for the ServiceLifecycle Lambda with PostgreSQL example.
-
-## Architecture Overview
-
-The infrastructure consists of a secure VPC setup with public and private subnets, a Lambda function in public subnets, and an RDS PostgreSQL database in private subnets. The architecture follows AWS best practices for security and connectivity.
-
-```mermaid
-graph TD
-    subgraph "AWS Cloud"
-        subgraph "VPC (10.0.0.0/16)"
-            subgraph "Public Subnets"
-                Lambda["Lambda Function"]
-                NAT["NAT Gateway"]
-                IGW["Internet Gateway"]
-            end
-
-            subgraph "Private Subnets"
-                RDS["PostgreSQL RDS"]
-                SSM1["SSM Endpoint"]
-                SSM2["SSM Messages Endpoint"]
-                SSM3["EC2 Messages Endpoint"]
-            end
-
-            Lambda -- "Egress to DB (5432)" --> RDS
-            Lambda -- "Egress to AWS APIs (443)" --> Internet
-
-            RDS -- "Ingress from Lambda (5432)" --> Lambda
-            RDS -- "Ingress from SSM (5432)" --> SSM1
-
-            NAT -- "Outbound traffic" --> IGW
-            IGW -- "Internet Access" --> Internet
-        end
-
-        SecretsManager["Secrets Manager"]
-        APIGateway["API Gateway"]
-        EC2["Amazon EC2"]
-
-        APIGateway --> Lambda
-        Lambda --> SecretsManager
-        EC2 -- "Via SSM Endpoints" --> SSM1
-        SSM1 --> RDS
-    end
-
-    User["User"] --> APIGateway
-    Admin["Admin"] --> EC2
-```
-
-## Key Components
-
-### Networking
-
-1. **VPC**: A dedicated VPC with CIDR block `10.0.0.0/16`
-2. **Subnets**:
-   - Public Subnets (10.0.1.0/24, 10.0.2.0/24): For Lambda and NAT Gateway
-   - Private Subnets (10.0.3.0/24, 10.0.4.0/24): For RDS and VPC endpoints
-3. **Internet Gateway**: Provides internet access for public subnets
-4. **NAT Gateway**: Allows outbound internet access from private subnets
-5. **Route Tables**: Separate route tables for public and private subnets
-
-### Security
-
-1. **Security Groups**:
-   - **Lambda Security Group**: Restricts outbound traffic to:
-     - PostgreSQL (5432) within the VPC
-     - HTTPS (443) to the internet
-   - **Database Security Group**: Allows inbound PostgreSQL connections only from:
-     - Lambda Security Group
-     - SSM Endpoint Security Group
-   - **SSM Endpoint Security Group**: Allows HTTPS inbound for SSM connections
-
-2. **Encryption**:
-   - RDS storage encryption enabled
-   - SSL/TLS for database connections with certificate verification
-   - Secrets Manager for secure credential storage
-
-### Compute & Database
-
-1. **Lambda Function**:
-   - Runtime: provided.al2 (Swift)
-   - Memory: 512MB
-   - Timeout: 60 seconds
-   - VPC integration with public subnets
-
-2. **RDS PostgreSQL**:
-   - Instance class: db.t3.micro
-   - Engine version: 15.7
-   - Storage: 20GB gp2
-   - Placed in private subnets
-   - Not publicly accessible
-
-### Access & Management
-
-1. **Secrets Manager**:
-   - Stores database credentials
-   - Auto-generates secure password
-   - Referenced by Lambda and RDS
-
-2. **VPC Endpoints**:
-   - SSM Endpoint
-   - SSM Messages Endpoint
-   - EC2 Messages Endpoint
-   - Enables CloudShell access to private resources
-
-3. **Function URL**:
-   - HTTP endpoint for invoking Lambda function
+# Infrastructure Architecture
+
+This document describes the AWS infrastructure deployed by the ServiceLifecycle example's SAM template.
+
+## Overview
+
+The infrastructure consists of a secure VPC setup with public and private subnets, a PostgreSQL RDS instance in private subnets, and a Lambda function with VPC access. The architecture follows AWS best practices for security and network isolation.
+
+## Network Architecture
+
+### VPC Configuration
+- **VPC**: Custom VPC with CIDR block `10.0.0.0/16`
+- **DNS Support**: DNS hostnames and DNS resolution enabled
+
+### Subnet Layout
+- **Public Subnets**:
+  - Public Subnet 1: `10.0.1.0/24` (AZ 1)
+  - Public Subnet 2: `10.0.2.0/24` (AZ 2)
+  - Used for Lambda functions and NAT Gateway
+  - Auto-assign public IP addresses enabled
+
+- **Private Subnets**:
+  - Private Subnet 1: `10.0.3.0/24` (AZ 1)
+  - Private Subnet 2: `10.0.4.0/24` (AZ 2)
+  - Used for RDS PostgreSQL database
+  - No public IP addresses assigned
+
+### Network Components
+- **Internet Gateway**: Provides internet access for public subnets
+- **NAT Gateway**: Deployed in Public Subnet 1, allows private subnets to access the internet
+- **Route Tables**:
+  - Public Route Table: Routes traffic to the Internet Gateway
+  - Private Route Table: Routes traffic through the NAT Gateway
+
+## Security Groups
+
+### Lambda Security Group
+- **Outbound Rules**:
+  - PostgreSQL (5432): Restricted to VPC CIDR `10.0.0.0/16`
+  - HTTPS (443): Open to `0.0.0.0/0` for AWS service access
+
+### Database Security Group
+- **Inbound Rules**:
+  - PostgreSQL (5432): Only allows connections from the Lambda Security Group
+
+## Database Configuration
+
+### PostgreSQL RDS Instance
+- **Instance Type**: `db.t3.micro` (cost-optimized)
+- **Engine**: PostgreSQL 15.7
+- **Storage**: 20GB GP2 (SSD)
+- **Network**: Deployed in private subnets with no public access
+- **Security**:
+  - Storage encryption enabled
+  - SSL/TLS connections supported
+  - Credentials stored in AWS Secrets Manager
+- **High Availability**: Multi-AZ disabled (development configuration)
+- **Backup**: Automated backups disabled (development configuration)
+
+### Database Subnet Group
+- Spans both private subnets for availability
+
+## Lambda Function Configuration
+
+### Service Lifecycle Lambda
+- **Runtime**: Custom runtime (provided.al2)
+- **Architecture**: ARM64
+- **Memory**: 512MB
+- **Timeout**: 60 seconds
+- **Network**: Deployed in public subnets with access to both internet and private resources
+- **Environment Variables**:
+  - `LOG_LEVEL`: trace
+  - `DB_HOST`: RDS endpoint address
+  - `DB_USER`: Retrieved from Secrets Manager
+  - `DB_PASSWORD`: Retrieved from Secrets Manager
+  - `DB_NAME`: Database name from parameter
+
+## API Gateway
+
+- **Type**: HTTP API
+- **Integration**: Direct Lambda integration
+- **Authentication**: None (for demonstration purposes)
+
+## Secrets Management
+
+### Database Credentials
+- **Storage**: AWS Secrets Manager
+- **Secret Name**: `{StackName}-db-credentials`
+- **Content**:
+  - Username: "postgres"
+  - Password: Auto-generated 16-character password
+  - Special characters excluded: `"@/\`
+
+## SAM Outputs
+
+The template provides several outputs to facilitate working with the deployed resources:
+
+- **APIGatewayEndpoint**: URL to invoke the Lambda function
+- **DatabaseEndpoint**: Hostname for the PostgreSQL instance
+- **DatabasePort**: Port number for PostgreSQL (5432)
+- **DatabaseName**: Name of the created database
+- **DatabaseSecretArn**: ARN of the secret containing credentials
+- **DatabaseConnectionInstructions**: Instructions for retrieving connection details
+- **ConnectionDetails**: Consolidated connection information
 
 ## Security Considerations
 
-1. **Network Isolation**: Database is in private subnets, not directly accessible from the internet
-2. **Least Privilege**: Security groups follow principle of least privilege
-3. **Encryption**: Data at rest is encrypted
-4. **Secure Credentials**: No hardcoded credentials, using Secrets Manager
-5. **SSL/TLS**: Database connections use SSL/TLS with certificate verification
+This infrastructure implements several security best practices:
 
-## Accessing the Database
-
-The database is in a private subnet and not directly accessible from the internet. To connect:
-
-1. **From Lambda**: Direct connection through VPC networking
-2. **From Amazon EC2**: Through SSM VPC endpoints
-3. **From your local machine**: Options include:
-   - SSH tunnel through a bastion host
-   - AWS Session Manager port forwarding
-   - AWS Cloud9 environment in the same VPC
-
-## Deployment
-
-Deploy this infrastructure using AWS SAM:
-
-```bash
-sam deploy
-```
-
-## Outputs
-
-After deployment, the following information is available in CloudFormation outputs:
-
-- API Gateway endpoint URL
-- Database endpoint hostname and port
-- Database name
-- Secret ARN for retrieving credentials
-- Connection instructions
+1. **Network Isolation**: Database is placed in private subnets with no direct internet access
+2. **Least Privilege**: Security groups restrict traffic to only necessary ports and sources
+3. **Encryption**: Database storage is encrypted at rest
+4. **Secure Credentials**: Database credentials are managed through AWS Secrets Manager
+5. **Secure Communication**: Lambda function connects to database over encrypted connections
 
 ## Cost Optimization
 
-The template uses cost-effective resources:
-- db.t3.micro RDS instance (eligible for free tier)
+The template uses cost-effective resources suitable for development:
+
+- `db.t3.micro` instance (eligible for free tier)
 - Minimal storage allocation (20GB)
-- Single-AZ deployment
+- No Multi-AZ deployment
 - No automated backups
 
 For production workloads, consider adjusting these settings based on your requirements.