aws-samples · arghyaaws · Aug 1, 2025
diff --git a/snowflake-cortex-qbusiness-plugin/PROJECT_SUMMARY.md b/snowflake-cortex-qbusiness-plugin/PROJECT_SUMMARY.md
@@ -0,0 +1,63 @@
+# Project Summary: Snowflake Q Business Plugin
+
+## 🎯 **What This Project Does**
+Creates a custom Amazon Q Business plugin that integrates with Snowflake Cortex Search, allowing users to query Snowflake data using natural language through Q Business.
+
+## 📁 **Final File Structure**
+```
+/Users/arghyaba/demo/genAI/FT/
+├── snowflake-q-business-final.yaml    # Main CloudFormation template
+├── deploy-snowflake-qbusiness.sh      # Deployment script
+├── test-deployment.sh                 # Testing script
+├── README.md                          # Complete documentation
+├── aws-credentials.env                # AWS credentials (not in git)
+├── .gitignore                         # Git ignore file
+└── PROJECT_SUMMARY.md                 # This summary
+```
+
+## 🚀 **Quick Deployment**
+```bash
+# 1. Set credentials
+source aws-credentials.env
+
+# 2. Deploy
+./deploy-snowflake-qbusiness.sh \
+  "arn:aws:secretsmanager:us-west-2:<account-id>:secret:snowflake/amazon-q-oauth-UKe0dC" \
+  "arn:aws:sso:::instance/ssoins-xxxxxxx"
+
+# 3. Test
+./test-deployment.sh
+```
+
+## ✅ **What's Automated**
+- Q Business application creation
+- Snowflake plugin configuration with OpenAPI schema
+- OAuth authentication setup
+- Web experience creation
+- Auto-subscriptions for users
+- All AWS resource provisioning
+
+## ⚠️ **What Requires Manual Configuration**
+- **LLM Access Settings**: Must be enabled in AWS Console
+  - "Allow end users to send queries directly to the LLM"
+  - "Allow Amazon Q to fall back to LLM knowledge"
+- **User Management**: Create users in IAM Identity Center and assign subscriptions
+
+## 🔧 **Key Features**
+- **Comprehensive CloudFormation**: All resources defined as code
+- **Security**: OAuth 2.0 with Secrets Manager integration
+- **Scalability**: Auto-subscriptions and proper IAM roles
+- **Testing**: Built-in verification scripts
+- **Documentation**: Complete setup and troubleshooting guide
+
+## 🎉 **Current Status**
+- ✅ All older files cleaned up
+- ✅ Final template tested and working
+- ✅ Deployment scripts functional
+- ✅ Documentation complete
+- ✅ Ready for production use
+
+## 📞 **Support**
+- Check README.md for detailed instructions
+- Use test-deployment.sh for verification
+- Review CloudFormation events for troubleshooting
diff --git a/snowflake-cortex-qbusiness-plugin/README.md b/snowflake-cortex-qbusiness-plugin/README.md
@@ -0,0 +1,223 @@
+# Snowflake Q Business Custom Plugin
+
+This project creates a custom Amazon Q Business plugin that integrates directly with Snowflake Cortex Search, enabling users to query unstructured data stored in Snowflake through natural language interactions.
+
+## Architecture
+
+```
+┌─────────────────┐    ┌──────────────────┐    ┌─────────────────────┐
+│   Amazon Q      │    │   Custom Plugin  │    │    Snowflake        │
+│   Business      │◄──►│   (OpenAPI       │◄──►│    Cortex Search    │
+│                 │    │    Schema +      │    │    Service          │
+│                 │    │    OAuth 2.0)    │    │                     │
+└─────────────────┘    └──────────────────┘    └─────────────────────┘
+```
+
+## Files Overview
+
+- `snowflake-q-business-final.yaml` - Final CloudFormation template with comprehensive configuration
+- `deploy-snowflake-qbusiness.sh` - Deployment script
+- `test-deployment.sh` - Testing and verification script
+- `aws-credentials.env` - AWS credentials configuration (not in git)
+
+## Prerequisites
+
+### AWS Requirements
+- AWS Account with Amazon Q Business access
+- Valid AWS credentials with permissions for:
+  - CloudFormation stack creation
+  - Q Business application management
+  - Secrets Manager access
+  - IAM role creation
+  - IAM Identity Center access
+
+### Snowflake Requirements
+- Snowflake account with Cortex Search enabled
+- OAuth security integration configured
+- Cortex Search service created
+- Existing Secrets Manager secret with OAuth credentials
+
+## Quick Start
+
+### Step 1: Set AWS Credentials
+
+```bash
+# Option 1: Use environment file (recommended)
+source aws-credentials.env
+
+# Option 2: Set environment variables directly
+export AWS_ACCESS_KEY_ID="your_access_key"
+export AWS_SECRET_ACCESS_KEY="your_secret_key"
+export AWS_SESSION_TOKEN="your_session_token"  # if using temporary credentials
+export AWS_DEFAULT_REGION="us-west-2"
+```
+
+### Step 2: Deploy the Plugin
+
+```bash
+./deploy-snowflake-qbusiness.sh <SECRETS_MANAGER_ARN> <IDC_INSTANCE_ARN> [APPLICATION_NAME]
+```
+
+Example:
+```bash
+./deploy-snowflake-qbusiness.sh \
+  "arn:aws:secretsmanager:us-west-2:<account-id>:secret:snowflake/amazon-q-oauth-UKe0dC" \
+  "arn:aws:sso:::instance/ssoins-xxxxxxxx" \
+  "SnowflakeCortexApp"
+```
+
+### Step 3: Test the Deployment
+
+```bash
+./test-deployment.sh [STACK_NAME] [REGION]
+```
+
+Example:
+```bash
+./test-deployment.sh snowflake-qbusiness-plugin us-west-2
+```
+
+## Manual Configuration Required
+
+⚠️ **Important**: Some Q Business features are not available through CloudFormation and must be configured manually:
+
+### LLM Access Settings (Console Only)
+
+1. **Go to Q Business Console**:
+   - Navigate to: https://console.aws.amazon.com/qbusiness/
+   - Select your application
+
+2. **Enable LLM Features**:
+   - Click "Edit" or go to "Settings"
+   - Enable "Allow end users to send queries directly to the LLM"
+   - Enable "Allow Amazon Q to fall back to LLM knowledge"
+   - Save changes
+
+### User Access Management
+
+1. **Create Users in IAM Identity Center**:
+   - Go to: https://console.aws.amazon.com/singlesignon/
+   - Add users with appropriate email addresses
+
+2. **Assign Q Business Subscriptions**:
+   - Go to Q Business Console → Your App → Access management → Subscriptions
+   - Assign Q Business Lite or Pro subscriptions to users
+
+## CloudFormation Template Features
+
+The template includes comprehensive configuration:
+
+### ✅ Automated Configuration
+- **Application Setup**: Q Business application with optimal settings
+- **Plugin Integration**: Snowflake Cortex Search plugin with OpenAPI schema
+- **OAuth Configuration**: Secure authentication with Snowflake
+- **Web Experience**: Ready-to-use web interface
+- **Auto Subscriptions**: Automatic Q Business Pro subscriptions for new users
+- **Feature Enablement**: File uploads, personalization, Q Apps, sample prompts
+
+### ⚠️ Manual Configuration Required
+- **LLM Direct Access**: "Allow end users to send queries directly to the LLM"
+- **LLM Knowledge Fallback**: "Allow Amazon Q to fall back to LLM knowledge"
+- **User Management**: Creating users and assigning subscriptions
+
+## Snowflake Configuration
+
+The plugin uses the following Snowflake configuration (stored in Secrets Manager):
+
+```json
+{
+  "account": "xxxxxY-xxxxx",
+  "warehouse": "AMAZON_Q_WAREHOUSE",
+  "database": "AMAZON_Q_BUSINESS",
+  "schema": "CORTEX_SEARCH",
+  "role": "AMAZON_Q_ROLE",
+  "client_id": "your_oauth_client_id",
+  "client_secret": "your_oauth_client_secret",
+  "refresh_token": "your_refresh_token"
+}
+```
+
+## Testing the Plugin
+
+After deployment and manual configuration:
+
+1. **Access the Web Experience**: Use the URL from deployment outputs
+2. **Sign In**: Use your IAM Identity Center credentials
+3. **Test Queries**: Try questions like:
+   - "Search for pump maintenance procedures"
+   - "Find information about troubleshooting"
+   - "What are the safety guidelines?"
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Login Error: "Please ask your IT Admin to add access to General knowledge"**
+   - Enable LLM access settings manually in the console (see Manual Configuration section)
+
+2. **User Not Found**
+   - Create the user in IAM Identity Center
+   - Assign Q Business subscription to the user
+   - Wait up to 24 hours for changes to propagate
+
+3. **Plugin Not Working**
+   - Verify Snowflake OAuth credentials in Secrets Manager
+   - Check that Cortex Search service is active in Snowflake
+   - Ensure plugin is enabled in Q Business console
+
+### Debug Commands
+
+Check stack status:
+```bash
+aws cloudformation describe-stacks --stack-name snowflake-qbusiness-plugin --region us-west-2
+```
+
+View stack events:
+```bash
+aws cloudformation describe-stack-events --stack-name snowflake-qbusiness-plugin --region us-west-2
+```
+
+Get application details:
+```bash
+aws qbusiness get-application --application-id <APP_ID> --region us-west-2
+```
+
+## Security Considerations
+
+- OAuth credentials are stored securely in AWS Secrets Manager
+- IAM roles follow least privilege principle
+- All communications use HTTPS
+- Session tokens have limited validity
+
+## Cost Considerations
+
+### AWS Costs
+- Q Business application usage (based on user subscriptions)
+- Secrets Manager storage (minimal)
+- CloudFormation (no additional cost)
+- Lambda function executions (minimal)
+
+### Snowflake Costs
+- Warehouse compute time for queries
+- Cortex Search operations
+- Data storage and transfer
+
+## Cleanup
+
+To remove the plugin and associated resources:
+
+```bash
+aws cloudformation delete-stack --stack-name snowflake-qbusiness-plugin --region us-west-2
+```
+
+## Support
+
+For issues or questions:
+1. Check the troubleshooting section above
+2. Review CloudFormation stack events
+3. Verify Snowflake configuration and permissions
+4. Check AWS Q Business application status in the console
+
+## License
+
+This project is licensed under the Apache License 2.0 - see the code headers for details.
diff --git a/snowflake-cortex-qbusiness-plugin/deploy-snowflake-qbusiness.sh b/snowflake-cortex-qbusiness-plugin/deploy-snowflake-qbusiness.sh
@@ -0,0 +1,98 @@
+#!/bin/bash
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}========================================${NC}"
+echo -e "${BLUE}  Snowflake Q Business Plugin Deployment${NC}"
+echo -e "${BLUE}========================================${NC}"
+
+# Check if required parameters are provided
+if [ $# -lt 2 ]; then
+    echo -e "${RED}[ERROR]${NC} Usage: $0 <SECRETS_MANAGER_ARN> <IDC_INSTANCE_ARN> [APPLICATION_NAME]"
+    echo -e "${YELLOW}[INFO]${NC} Example:"
+    echo -e "${YELLOW}[INFO]${NC}   $0 arn:aws:secretsmanager:us-west-2:123456789012:secret:snowflake/oauth-abc123 arn:aws:sso:::instance/ssoins-1234567890abcdef"
+    exit 1
+fi
+
+SECRETS_MANAGER_ARN="$1"
+IDC_INSTANCE_ARN="$2"
+APPLICATION_NAME="${3:-SnowflakeCortexApp}"
+STACK_NAME="snowflake-qbusiness-plugin"
+REGION="us-west-2"
+
+echo -e "${GREEN}[INFO]${NC} Configuration:"
+echo -e "${GREEN}[INFO]${NC}   Secrets Manager ARN: $SECRETS_MANAGER_ARN"
+echo -e "${GREEN}[INFO]${NC}   IDC Instance ARN: $IDC_INSTANCE_ARN"
+echo -e "${GREEN}[INFO]${NC}   Application Name: $APPLICATION_NAME"
+echo -e "${GREEN}[INFO]${NC}   Stack Name: $STACK_NAME"
+echo -e "${GREEN}[INFO]${NC}   Region: $REGION"
+
+# Check if AWS credentials are configured
+echo -e "${BLUE}[CHECK]${NC} Verifying AWS credentials..."
+if ! aws sts get-caller-identity >/dev/null 2>&1; then
+    echo -e "${RED}[ERROR]${NC} AWS credentials not configured. Please run 'aws configure' or set environment variables."
+    exit 1
+fi
+
+ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
+echo -e "${GREEN}[INFO]${NC} Using AWS Account: $ACCOUNT_ID"
+
+# Deploy the CloudFormation stack
+echo -e "${BLUE}[DEPLOY]${NC} Deploying CloudFormation stack..."
+
+aws cloudformation deploy \
+    --template-file snowflake-q-business-final.yaml \
+    --stack-name "$STACK_NAME" \
+    --parameter-overrides \
+        ExistingSecretsManagerArn="$SECRETS_MANAGER_ARN" \
+        ExistingIDCInstanceArn="$IDC_INSTANCE_ARN" \
+        ApplicationName="$APPLICATION_NAME" \
+        CortexSearchServiceName="PUMP_SEARCH_SERVICE" \
+        PluginDisplayName="Snowflake-Cortex-Search" \
+    --capabilities CAPABILITY_NAMED_IAM \
+    --region "$REGION"
+
+if [ $? -eq 0 ]; then
+    echo -e "${GREEN}[SUCCESS]${NC} ✅ Stack deployment completed successfully!"
+
+    # Get stack outputs
+    echo -e "${BLUE}[INFO]${NC} Retrieving deployment information..."
+
+    WEB_URL=$(aws cloudformation describe-stacks \
+        --stack-name "$STACK_NAME" \
+        --region "$REGION" \
+        --query 'Stacks[0].Outputs[?OutputKey==`QBusinessWebExperienceUrl`].OutputValue' \
+        --output text)
+
+    APPLICATION_ID=$(aws cloudformation describe-stacks \
+        --stack-name "$STACK_NAME" \
+        --region "$REGION" \
+        --query 'Stacks[0].Outputs[?OutputKey==`QBusinessApplicationId`].OutputValue' \
+        --output text)
+
+    echo -e "${GREEN}========================================${NC}"
+    echo -e "${GREEN}  DEPLOYMENT SUCCESSFUL! 🎉${NC}"
+    echo -e "${GREEN}========================================${NC}"
+    echo -e "${GREEN}[SUCCESS]${NC} Web Experience URL: $WEB_URL"
+    echo -e "${GREEN}[SUCCESS]${NC} Application ID: $APPLICATION_ID"
+    echo -e ""
+    echo -e "${YELLOW}[NEXT STEPS]${NC} Manual Configuration Required:"
+    echo -e "${YELLOW}[STEP 1]${NC} Go to: https://console.aws.amazon.com/qbusiness/home?region=$REGION#/applications/$APPLICATION_ID"
+    echo -e "${YELLOW}[STEP 2]${NC} Click 'Edit' and enable 'Allow Amazon Q to fall back to LLM knowledge'"
+    echo -e "${YELLOW}[STEP 3]${NC} Create users in IAM Identity Center and assign Q Business subscriptions"
+    echo -e "${YELLOW}[STEP 4]${NC} Test the application at: $WEB_URL"
+    echo -e ""
+    echo -e "${BLUE}[INFO]${NC} For detailed outputs, run:"
+    echo -e "${BLUE}[INFO]${NC}   aws cloudformation describe-stacks --stack-name $STACK_NAME --region $REGION --query 'Stacks[0].Outputs'"
+
+else
+    echo -e "${RED}[ERROR]${NC} ❌ Stack deployment failed!"
+    echo -e "${RED}[ERROR]${NC} Check the CloudFormation console for details:"
+    echo -e "${RED}[ERROR]${NC} https://console.aws.amazon.com/cloudformation/home?region=$REGION#/stacks"
+    exit 1
+fi