Skip to content

Commit 4222596

Browse files
rcgeorgercgeorge
committed
docs: add ALB hosting guide and update existing docs with ALB/VPC hosting references
1 parent 421b80a commit 4222596

7 files changed

Lines changed: 296 additions & 15 deletions

File tree

‎docs/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@ This folder contains detailed documentation on various aspects of the GenAI Inte
7676

7777
- [Well-Architected Framework Assessment](./well-architected.md) - Analysis based on AWS Well-Architected Framework
7878
- [AWS Services & IAM Roles](./aws-services-and-roles.md) - AWS services used and IAM role requirements
79+
- [ALB Hosting](./alb-hosting.md) - ALB+S3 hosting for private network and GovCloud deployments
7980
- [GovCloud Deployment](./govcloud-deployment.md) - Deployment guide for AWS GovCloud regions
8081
- [EU Region Model Support](./eu-region-model-support.md) - Model availability in EU regions
8182

‎docs/alb-hosting.md‎

Lines changed: 273 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,273 @@
1+
---
2+
title: "ALB Hosting Guide"
3+
---
4+
5+
Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
6+
SPDX-License-Identifier: MIT-0
7+
8+
# ALB Hosting Guide
9+
10+
## Overview
11+
12+
The GenAI IDP Accelerator supports an alternative web UI hosting mode using an Application Load Balancer (ALB) with an S3 VPC Interface Endpoint, replacing CloudFront for environments that require VPC-based hosting.
13+
14+
> **Note**: For standard deployments, CloudFront hosting (the default) is recommended. Use ALB hosting only when your environment has specific requirements that prevent using CloudFront.
15+
16+
## When to Use ALB Hosting
17+
18+
ALB hosting is designed for organizations that need the full IDP web UI but cannot use CloudFront due to network or compliance constraints:
19+
20+
- **Private network requirements** — environments where all web traffic must remain within a VPC and internet-facing CDN endpoints are not permitted
21+
- **Regulated environments** — deployments that require all traffic to traverse private network paths with VPC-level security controls (security groups, NACLs, VPC Flow Logs)
22+
- **Corporate network restrictions** — organizations where users access applications exclusively through VPN or Direct Connect, and public CDN endpoints are blocked by policy
23+
- **Air-gapped or isolated VPCs** — environments with no internet egress where CloudFront cannot function
24+
25+
> **Note on GovCloud**: GovCloud deployments use a separate headless template (no web UI or AppSync). ALB hosting is not applicable to GovCloud — see [GovCloud Deployment](./govcloud-deployment.md) instead.
26+
27+
## Architecture
28+
29+
### Standard Hosting (CloudFront)
30+
31+
```
32+
Internet Users → CloudFront (Edge) → S3 Origin (WebUI Bucket)
33+
```
34+
35+
### ALB Hosting
36+
37+
```
38+
VPC Users → ALB → S3 VPC Interface Endpoint → S3 (WebUI Bucket)
39+
```
40+
41+
The ALB hosting nested stack creates:
42+
43+
- An Application Load Balancer (internal or internet-facing)
44+
- An S3 Interface VPC Endpoint for private connectivity to S3
45+
- Security groups controlling traffic between ALB and VPC endpoint
46+
- Listener rules with host-header rewrite and URL rewrite transforms to serve S3 static content as a single-page application
47+
- Custom resource Lambda functions for VPC CIDR lookup and VPC endpoint target registration
48+
49+
## Prerequisites
50+
51+
### VPC Requirements
52+
53+
You need an existing VPC with the following:
54+
55+
1. **At least 2 subnets in different Availability Zones** — required by ALB. These can be:
56+
- **Private subnets** (recommended for internal ALBs) — must have a route to S3 via VPC endpoint (created by the stack) and to AWS service endpoints for SSM, CloudWatch, etc.
57+
- **Public subnets** (for internet-facing ALBs) — must have an Internet Gateway route
58+
2. **DNS resolution enabled** — the VPC must have `enableDnsSupport` and `enableDnsHostnames` set to `true`
59+
3. **Sufficient IP space** — the S3 VPC Interface Endpoint creates ENIs in each subnet (one IP per subnet)
60+
61+
### ACM Certificate
62+
63+
An ACM certificate is required for the ALB HTTPS listener. Options:
64+
65+
- **ACM-issued certificate** (recommended for production) — request via ACM with DNS or email validation
66+
- **Imported certificate** — import your organization's CA-signed certificate into ACM
67+
- **Self-signed certificate** (demo/testing only) — use the provided helper script:
68+
69+
```bash
70+
# Generate and import a self-signed certificate
71+
CERT_ARN=$(./scripts/generate_self_signed_cert.sh --region us-east-1 --domain myapp.internal)
72+
echo "Certificate ARN: $CERT_ARN"
73+
74+
# Options:
75+
# --region AWS region for ACM import (default: from AWS config)
76+
# --domain Domain name for the certificate CN/SAN (default: self-signed.internal)
77+
# --days Certificate validity in days (default: 365)
78+
```
79+
80+
### Network Connectivity
81+
82+
Users must be able to reach the ALB:
83+
84+
- **Internal ALB**: Users need VPN, Direct Connect, or access from within the VPC (e.g., WorkSpaces, Cloud9, SSM port forwarding)
85+
- **Internet-facing ALB**: Users can access directly, but the ALB security group controls which source IPs are allowed
86+
87+
## Deployment
88+
89+
### Option 1: IDP CLI
90+
91+
```bash
92+
idp-cli deploy \
93+
--stack-name my-idp-stack \
94+
--admin-email user@example.com \
95+
--from-code . \
96+
--parameters "WebUIHosting=ALB,ALBVpcId=vpc-xxxxx,ALBSubnetIds=subnet-aaaa,subnet-bbbb,ALBCertificateArn=arn:aws:acm:REGION:ACCOUNT:certificate/xxxxx,ALBScheme=internal" \
97+
--wait
98+
```
99+
100+
### Option 2: CloudFormation Console
101+
102+
When deploying via the CloudFormation console, set the following parameters in the **Web UI Hosting** and **ALB Hosting** parameter sections:
103+
104+
| Parameter | Value | Description |
105+
|-----------|-------|-------------|
106+
| `WebUIHosting` | `ALB` | Switches from CloudFront to ALB hosting |
107+
| `ALBVpcId` | `vpc-xxxxx` | VPC for the ALB and S3 VPC endpoint |
108+
| `ALBSubnetIds` | `subnet-aaaa,subnet-bbbb` | Minimum 2 subnets in different AZs |
109+
| `ALBCertificateArn` | `arn:aws:acm:...` | ACM certificate ARN for HTTPS |
110+
| `ALBScheme` | `internal` or `internet-facing` | ALB accessibility |
111+
| `ALBAllowedCIDRs` | *(optional)* | Comma-separated CIDRs for ALB ingress. Empty = VPC CIDR |
112+
113+
### Switching an Existing Stack
114+
115+
You can switch an existing CloudFront-hosted stack to ALB hosting (or vice versa) by updating the stack with the new `WebUIHosting` parameter value and providing the required ALB parameters. CloudFormation will conditionally create or remove the appropriate resources.
116+
117+
## Parameters Reference
118+
119+
### WebUIHosting
120+
121+
- **Type**: String
122+
- **Default**: `CloudFront`
123+
- **Allowed Values**: `CloudFront`, `ALB`
124+
- **Description**: Selects the frontend hosting method. CloudFront is the default for standard deployments. ALB is for private network deployments that require VPC-based hosting.
125+
126+
### ALBVpcId
127+
128+
- **Type**: String
129+
- **Required when**: `WebUIHosting=ALB`
130+
- **Description**: The VPC ID where the ALB and S3 VPC Interface Endpoint will be created.
131+
132+
### ALBSubnetIds
133+
134+
- **Type**: CommaDelimitedList
135+
- **Required when**: `WebUIHosting=ALB`
136+
- **Description**: At least 2 subnet IDs in different Availability Zones. Use private subnets for internal ALBs, public subnets for internet-facing ALBs.
137+
138+
### ALBCertificateArn
139+
140+
- **Type**: String
141+
- **Required when**: `WebUIHosting=ALB`
142+
- **Description**: ACM certificate ARN for the ALB HTTPS listener. Can be an ACM-issued certificate, an imported certificate, or a self-signed certificate (for testing).
143+
144+
### ALBScheme
145+
146+
- **Type**: String
147+
- **Default**: `internal`
148+
- **Allowed Values**: `internal`, `internet-facing`
149+
- **Description**: Controls ALB accessibility. Use `internal` for private network access (recommended). Use `internet-facing` for public access.
150+
151+
### ALBAllowedCIDRs
152+
153+
- **Type**: String
154+
- **Default**: *(empty)*
155+
- **Description**: Comma-separated CIDR ranges allowed to access the ALB on port 443. When empty, the VPC CIDR is used automatically (recommended for internal ALBs). Specify explicit CIDRs to restrict access to specific networks.
156+
157+
## How It Works
158+
159+
### Conditional Resource Creation
160+
161+
When `WebUIHosting=ALB`:
162+
163+
- CloudFront distribution, Origin Access Identity, and security headers policy are **not created**
164+
- ALB nested stack is created with all ALB infrastructure
165+
- S3 WebUI bucket omits `WebsiteConfiguration` (ALB handles routing)
166+
- S3 bucket policy grants access via `aws:sourceVpce` condition instead of CloudFront OAI
167+
168+
When `WebUIHosting=CloudFront` (default):
169+
170+
- ALB nested stack is **not created**
171+
- Standard CloudFront distribution with OAI is created
172+
173+
### Request Flow (ALB Mode)
174+
175+
1. User sends HTTPS request to the ALB
176+
2. ALB listener rule matches the path pattern
177+
3. ALB applies **host-header rewrite** transform — sets the Host header to the S3 bucket's regional endpoint (`bucket.s3.region.amazonaws.com`)
178+
4. ALB applies **URL rewrite** transform for root path (`/` → `/index.html`) to support SPA routing
179+
5. Request is forwarded to the S3 VPC Interface Endpoint ENI IPs (registered as ALB targets)
180+
6. S3 serves the content through the VPC endpoint
181+
182+
### Automatic Integration
183+
184+
The following are automatically configured based on the `WebUIHosting` parameter — no manual configuration is needed:
185+
186+
- **S3 CORS origins** — all bucket CORS `AllowedOrigins` resolve to the ALB URL
187+
- **Cognito callback/logout URLs** — OAuth redirect URLs point to the ALB URL
188+
- **UI build configuration** — the `VITE_CLOUDFRONT_DOMAIN` environment variable resolves to the ALB URL
189+
- **CodeBuild post-deploy** — CloudFront cache invalidation is skipped in ALB mode
190+
- **Stack outputs** — `ApplicationWebURL` returns the ALB URL
191+
192+
## Accessing the UI
193+
194+
### Internal ALB
195+
196+
For internal ALBs, you need network connectivity to the VPC. Common approaches:
197+
198+
**VPN or Direct Connect** (recommended for production): Access the ALB DNS name directly through your organization's private network connection.
199+
200+
**SSM Port Forwarding** (recommended for testing):
201+
202+
1. Launch a small EC2 instance (e.g., t3.micro) in the same VPC with an IAM role that includes `AmazonSSMManagedInstanceCore`
203+
2. Start a port forwarding session:
204+
```bash
205+
aws ssm start-session \
206+
--target INSTANCE_ID \
207+
--document-name AWS-StartPortForwardingSessionToRemoteHost \
208+
--parameters '{"host":["ALB_DNS_NAME"],"portNumber":["443"],"localPortNumber":["8443"]}'
209+
```
210+
3. Add a local hosts file entry so the browser sends the correct Host header:
211+
```bash
212+
echo "127.0.0.1 ALB_DNS_NAME" | sudo tee -a /etc/hosts
213+
```
214+
4. Open `https://ALB_DNS_NAME:8443/` in your browser (accept the certificate warning for self-signed certs)
215+
5. Remove the hosts entry when done testing
216+
217+
### Internet-Facing ALB
218+
219+
Access the ALB DNS name directly from the stack outputs:
220+
221+
```bash
222+
aws cloudformation describe-stacks \
223+
--stack-name my-idp-stack \
224+
--query 'Stacks[0].Outputs[?OutputKey==`ApplicationWebURL`].OutputValue' \
225+
--output text
226+
```
227+
228+
## Security Considerations
229+
230+
- ALB security group restricts ingress to port 443 from the VPC CIDR (or specified CIDRs)
231+
- ALB egress is restricted to the VPC endpoint security group on port 443 only
232+
- S3 bucket policy uses `aws:sourceVpce` condition — only requests through the VPC endpoint are allowed
233+
- S3 VPC endpoint policy is scoped to the WebUI bucket ARN only
234+
- ALB enforces TLS 1.3 (`ELBSecurityPolicy-TLS13-1-2-2021-06`)
235+
- ALB drops invalid HTTP header fields (`routing.http.drop_invalid_header_fields.enabled`)
236+
- ALB access logs are written to the stack's logging bucket under `alb-access-logs/` prefix
237+
- All traffic between ALB and S3 traverses the VPC endpoint (no internet path)
238+
239+
## Troubleshooting
240+
241+
### 403 Forbidden
242+
243+
- Verify the ALB target group health checks are passing (expected HTTP codes: 200, 307, 405)
244+
- Check the S3 bucket policy includes the correct VPC endpoint ID in the `aws:sourceVpce` condition
245+
- Confirm the ALB listener rules have the host-header rewrite transform configured correctly
246+
247+
### 404 Not Found
248+
249+
- The ALB default action returns 404 for unmatched paths. Ensure your request path matches a listener rule (`/` or `/*`)
250+
- Verify the WebUI bucket contains `index.html` and assets — check the CodeBuild project logs for build errors
251+
252+
### Target Group Unhealthy
253+
254+
- The custom resource Lambda registers S3 VPC endpoint ENI private IPs as ALB targets. If the VPC endpoint was recreated, targets may reference stale IPs
255+
- Verify the VPC endpoint security group allows inbound HTTPS (port 443) from the ALB security group
256+
257+
### UI Not Loading After Deploy
258+
259+
- The UI is built and deployed to S3 by CodeBuild during stack creation/update. Check the CodeBuild project logs for errors
260+
- Verify the `VITE_CLOUDFRONT_DOMAIN` build environment variable resolves to the ALB URL (not a CloudFront domain)
261+
262+
## Comparison: CloudFront vs ALB Hosting
263+
264+
| Feature | CloudFront | ALB |
265+
|---------|-----------|-----|
266+
| Global edge caching | ✅ | ❌ |
267+
| VPC-only access | ❌ | ✅ |
268+
| Custom domain (Route53) | Via CloudFront alias | Via ALB alias record |
269+
| WAF integration | ✅ (CloudFront WAF) | ✅ (Regional WAF) |
270+
| Cost model | Data transfer per GB | Hourly + data transfer |
271+
| Geo restrictions | ✅ Built-in | ❌ (use security groups/NACLs) |
272+
| SPA routing | S3 error document | ALB URL rewrite transform |
273+
| TLS termination | CloudFront edge | ALB in VPC |

‎docs/architecture.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ SPDX-License-Identifier: MIT-0
2929
- **DynamoDB**: Tracking and concurrency management
3030
- **CloudWatch**: Comprehensive monitoring and logging
3131
- **Web UI**: Browser-based interface for document management and visualization
32-
- CloudFront distribution for global availability
32+
- CloudFront distribution for global availability (default), or ALB for VPC-based hosting (see [ALB Hosting](./alb-hosting.md))
3333
- Cognito user authentication
3434
- GraphQL API for UI-backend interactions
3535
- **Evaluation**: Document processing accuracy assessment system
@@ -69,7 +69,7 @@ The main template handles all pattern-agnostic resources and infrastructure:
6969
- CloudWatch Alarms and Dashboard
7070
- SNS Topics for Alerts
7171
- Web UI Infrastructure:
72-
- CloudFront Distribution
72+
- CloudFront Distribution (default) or Application Load Balancer ([ALB Hosting](./alb-hosting.md))
7373
- S3 Bucket for static web assets
7474
- CodeBuild project for UI deployment
7575
- Authentication:
@@ -149,8 +149,8 @@ For detailed information about the Web UI, its features, and usage, see [web-ui.
149149
- Optional self-signup can be enabled with domain restrictions
150150
- Identity pools provide secure, temporary AWS credentials
151151

152-
2. **Content Delivery**: CloudFront distribution serves the static web assets
153-
- Global availability and low latency
152+
- **Content Delivery**: CloudFront distribution serves the static web assets (default), or an Application Load Balancer for VPC-based hosting (see [ALB Hosting](./alb-hosting.md))
153+
- Global availability and low latency (CloudFront) or private network access (ALB)
154154
- WAF integration for added security (optional)
155155
- Geographical restrictions can be applied
156156

‎docs/aws-services-and-roles.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,8 @@ This document outlines the AWS services used by the GenAI Intelligent Document P
2121
| **AWS Step Functions** | Orchestrates document processing workflows | ✓ | ✓ |
2222
| **Amazon SQS** | Queues documents for processing and handles throttling | ✓ | ✓ |
2323
| **Amazon EventBridge** | Triggers document processing workflows when files are uploaded | ✓ | ✓ |
24-
| **Amazon CloudFront** | Delivers the web UI with global distribution | ✓ | ✓ |
24+
| **Amazon CloudFront** | Delivers the web UI with global distribution (default hosting mode) | ✓ | ✓ |
25+
| **Elastic Load Balancing (ALB)** | Alternative web UI hosting via Application Load Balancer for VPC-based deployments (see [ALB Hosting](./alb-hosting.md)) | ✓ | ✓ |
2526
| **AWS CloudFormation** | Deploys and manages the solution infrastructure | ✓ | |
2627
| **AWS SAM** | Simplifies serverless application deployment | ✓ | |
2728
| **AWS CodeBuild** | Builds and packages the web UI assets | ✓ | |
@@ -208,7 +209,7 @@ When deploying this solution, consider the following security best practices:
208209
* Enable encryption for DynamoDB tables
209210

210211
2. **Network Security**:
211-
* Use CloudFront security features (geo-restrictions, HTTPS, etc.)
212+
* Use CloudFront security features (geo-restrictions, HTTPS, etc.) or ALB security groups for [VPC-based hosting](./alb-hosting.md)
212213
* Configure AWS WAF to protect web interfaces
213214

214215
3. **Authentication**:

‎docs/configuration.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -270,8 +270,9 @@ Key parameters that can be configured during CloudFormation deployment:
270270
- `ExecutionTimeThresholdMs`: Maximum acceptable execution time before alerting (default: 30000 ms)
271271
- `LogLevel`: Set logging level (DEBUG, INFO, WARN, ERROR)
272272
- `WAFAllowedIPv4Ranges`: IP restrictions for web UI access (default: allow all)
273-
- `CloudFrontPriceClass`: Set CloudFront price class for UI distribution
274-
- `CloudFrontAllowedGeos`: Optional geographic restrictions for UI access
273+
- `CloudFrontPriceClass`: Set CloudFront price class for UI distribution (CloudFront hosting only)
274+
- `CloudFrontAllowedGeos`: Optional geographic restrictions for UI access (CloudFront hosting only)
275+
- `WebUIHosting`: Select hosting mode — `CloudFront` (default) or `ALB` for VPC-based hosting (see [ALB Hosting](./alb-hosting.md))
275276
- `CustomConfigPath`: Optional S3 URI to a custom configuration file that overrides pattern presets. Leave blank to use selected pattern configuration. Example: s3://my-bucket/custom-config/config.yaml
276277

277278
### Integration and Tracing Parameters

‎docs/web-ui.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -295,7 +295,7 @@ The web UI is automatically deployed as part of the CloudFormation stack. The de
295295

296296
1. Creates required Cognito resources (User Pool, Identity Pool)
297297
2. Builds and deploys the React application to S3
298-
3. Sets up CloudFront distribution for content delivery
298+
3. Sets up CloudFront distribution for content delivery (or ALB for VPC-based hosting — see [ALB Hosting](./alb-hosting.md))
299299
4. Configures necessary IAM roles and permissions
300300

301301
## Accessing the Web UI
@@ -342,7 +342,7 @@ The web UI implementation includes several security features:
342342
- All communication is encrypted using HTTPS
343343
- Authentication tokens are automatically rotated
344344
- Session timeouts are enforced
345-
- CloudFront distribution uses secure configuration
345+
- CloudFront distribution uses secure configuration (or ALB with TLS 1.3 for VPC-based hosting)
346346
- S3 buckets are configured with appropriate security policies
347347
- API access is controlled through IAM and Cognito
348348
- Web Application Firewall (WAF) protection for AppSync API
@@ -371,14 +371,14 @@ The web UI includes built-in monitoring:
371371

372372
- CloudWatch metrics for API and authentication activity
373373
- Access logs in CloudWatch Logs
374-
- CloudFront distribution logs
374+
- CloudFront distribution logs (or ALB access logs for VPC-based hosting)
375375
- Error tracking and reporting
376376
- Performance monitoring
377377

378378
To troubleshoot issues:
379379

380380
1. Check CloudWatch Logs for application errors
381381
2. Verify Cognito user status in the AWS Console
382-
3. Check CloudFront distribution status
382+
3. Check CloudFront distribution status (or ALB target group health for VPC-based hosting)
383383
4. Verify API endpoints are accessible
384384
5. Review browser console for client-side errors

0 commit comments

Comments
 (0)