GovCloud Deployment Guide

Overview

The GenAI IDP Accelerator now supports “headless” deployment to AWS GovCloud regions through a specialized template generation script. This solution addresses two key GovCloud requirements:

ARN Partition Compatibility: All ARN references use arn:${AWS::Partition}: instead of arn:aws: to work in both commercial and GovCloud regions
Service Compatibility: Removes services not available in GovCloud (AppSync, CloudFront, WAF, Cognito UI components)

Architecture Differences

Standard AWS Deployment

graph TB
    A[Users] --> B[CloudFront Distribution]
    B --> C[React Web UI]
    C --> D[AppSync GraphQL API]
    D --> E[Cognito Authentication]
    E --> F[Core Processing Engine]
    F --> G[Document Workflows]
    G --> H[S3 Storage]

GovCloud Deployment

graph TB
    A[Direct S3 Upload] --> F[Core Processing Engine]
    F --> G[Document Workflows]
    G --> H[S3 Storage]
    I[CLI Tools] --> F
    J[SDK Integration] --> F

Deployment Process

Dependencies

You need to have the following packages installed on your computer:

bash shell (Linux, MacOS, Windows-WSL)
aws (AWS CLI)
sam (AWS SAM)
python 3.12 (required to generate templates)
Node.js >=22.12.0
npm >=10.0.0
A local Docker daemon
Python packages for the IDP CLI and SDK. Run make setup-venv from the project root to create a .venv and install all required packages (idp-cli, idp-sdk, idp_common). Activate with source .venv/bin/activate.

Deploy to GovCloud

Build and deploy to GovCloud with a single command. The --from-code . flag builds from your local source code (required for GovCloud since public templates are not published for GovCloud regions), and --headless strips UI, AppSync, Cognito, and WAF resources:

idp-cli deploy \
  --stack-name my-idp-headless-stack \
  --region us-gov-west-1 \
  --from-code . \
  --headless \
  --wait

Note: The CLI creates an S3 bucket automatically. Customize with --bucket-basename and --prefix.

Legacy: The scripts/generate_govcloud_template.py script is deprecated. Use idp-cli deploy --headless --from-code . instead.

Services Removed in GovCloud

The following services are automatically removed from the GovCloud template:

Web UI Components (11 resources removed)

CloudFront distribution and origin access identity
WebUI S3 bucket and build pipeline
CodeBuild project for UI deployment
Security headers policy

API Layer (136 resources removed)

AppSync GraphQL API and schema
All GraphQL resolvers and data sources (50+ resolvers)
Lambda resolver functions (20+ functions)
Test Studio Resources (36 resources): All test management Lambda functions, AppSync resolvers, data sources, SQS queues, and supporting infrastructure added in v0.4.6
API authentication and authorization
Chat infrastructure (ChatMessagesTable, ChatSessionsTable)
Agent chat processors and resolvers

Authentication (14 resources removed)

Cognito User Pool and Identity Pool
User pool client and domain
Admin user and group management
Email verification functions

WAF Security (6 resources removed)

WAF WebACL and IP sets
IP set updater functions
CloudFront protection rules

Agent & Analytics Features (14 resources removed)

AgentTable and agent job tracking
Agent request handler and processor functions
MCP/AgentCore Gateway Resources (7 resources): MCP integration components that depend on Cognito authentication (AgentCoreAnalyticsLambdaFunction, AgentCoreGatewayManagerFunction, AgentCoreGatewayExecutionRole, AgentCoreGateway, ExternalAppClient, and log groups)
External MCP agent credentials secret
Knowledge base query functions
Chat with document features
Text-to-SQL query capabilities

HITL Support (11 resources removed)

SageMaker A2I Human-in-the-Loop
Private workforce configuration
Human review workflows
A2I flow definition and human task UI
Cognito client for A2I integration

Core Services Retained

The following essential services remain available:

Document Processing

✅ All 3 processing patterns (BDA, Textract+Bedrock, Textract+SageMaker+Bedrock)
✅ Complete 6-step pipeline (OCR, Classification, Extraction, Assessment, Summarization, Evaluation)
✅ Step Functions workflows
✅ Lambda function processing
✅ Custom prompt Lambda integration

Storage & Data

✅ S3 buckets (Input, Output, Working, Configuration, Logging)
✅ DynamoDB tables (Tracking, Configuration, Concurrency)
✅ Data encryption with customer-managed KMS keys
✅ Lifecycle policies and data retention

Monitoring & Operations

✅ CloudWatch dashboards and metrics
✅ CloudWatch alarms and SNS notifications
✅ Lambda function logging and tracing
✅ Step Functions execution logging

Integration

✅ SQS queues for document processing
✅ EventBridge rules for workflow orchestration
✅ Post-processing Lambda hooks
✅ Evaluation and reporting systems

Access Methods

Without the web UI, you can interact with the system through:

1. Direct S3 Upload

# Upload documents directly to input bucket
aws s3 cp my-document.pdf s3://InputBucket/my-document.pdf


### 2. Check progress
Using the lookup script
```bash
# Use the lookup script to check document status
./scripts/lookup_file_status.sh documents/my-document.pdf MyStack

Or navigate to the AWS Step Functions workflow using the link in the stack Outputs tab in CloudFormation, to visually monitor workflow progress.

Monitoring & Troubleshooting

CloudWatch Dashboards

Access monitoring through CloudWatch console:

Navigate to CloudWatch → Dashboards
Find dashboard: {StackName}-{Region}
View processing metrics, error rates, and performance

CloudWatch Logs

Monitor processing through log groups:

/aws/lambda/{StackName}-* - Lambda function logs
/aws/vendedlogs/states/{StackName}/workflow - Step Functions logs
/{StackName}/lambda/* - Pattern-specific logs

Alarms and Notifications

SNS topic receives alerts for errors and performance issues
Configure email subscriptions to the AlertsTopic

Limitations in GovCloud Version

The following features are not available:

❌ Removed Features

Web-based user interface
Real-time document status updates via websockets
Interactive configuration management
User authentication and authorization via Cognito
CloudFront content delivery and caching
WAF security rules and IP filtering
Analytics query interface
Document knowledge base chat interface

✅ Available Workarounds

Use S3 direct upload instead of web UI
Monitor through CloudWatch instead of real-time UI
Edit configuration files in S3 directly
Use CLI/SDK for authentication needs
Access content directly from S3
Implement custom security at application level
Query data through Athena directly
Use the lookup function for document queries

Best Practices

Security

IAM Roles: Use least-privilege IAM roles
Encryption: Enable encryption at rest and in transit
Network: Deploy in private subnets if required
Access Control: Implement custom authentication as needed

Operations

Monitoring: Set up CloudWatch alarms for critical metrics
Logging: Configure appropriate log retention policies
Backup: Implement backup strategies for important data
Updates: Plan for template updates and maintenance

Performance

Concurrency: Adjust MaxConcurrentWorkflows based on load
Timeouts: Configure appropriate timeout values
Memory: Optimize Lambda memory settings
Batching: Use appropriate batch sizes for processing

Troubleshooting

Common Issues

Missing Dependencies

Ensure all Bedrock models are enabled in the region. GovCloud deployment uses amazon.nova-lite-v1:0, amazon.nova-pro-v1:0, us.anthropic.claude-3-5-sonnet-20240620-v1:0, and anthropic.claude-3-7-sonnet-20250219-v1:0 by default
Verify IAM permissions for service roles
Check S3 bucket policies and access

Processing Failures

Check CloudWatch logs for detailed error messages
Verify document formats are supported
Confirm configuration settings are valid

Support Resources

AWS Documentation: GovCloud User Guide
Bedrock in GovCloud: Model Availability
Service Limits: GovCloud Service Quotas

Migration from Commercial AWS

If migrating an existing deployment:

Export Configuration: Download all configuration from existing stack
Export Data: Copy any baseline or reference data
Deploy GovCloud: Use the generated template
Import Configuration: Upload configuration to new stack
Validate: Test processing with sample documents

Cost Considerations

GovCloud pricing may differ from commercial regions:

Review GovCloud Pricing
Update cost estimates in configuration files
Monitor actual usage through billing dashboards

Compliance Notes

The GovCloud version maintains the same security features
Data encryption and retention policies are preserved
All processing remains within GovCloud boundaries
No data egress to commercial AWS regions