Keycloak v26 Migration to AWS

Complete implementation for migrating Keycloak version 26 from Windows Server to a containerized cluster hosted on AWS using EKS.

🎯 Overview

This project provides a comprehensive solution for migrating Keycloak v26 from a Windows Server deployment to a highly available, containerized deployment on AWS Elastic Kubernetes Service (EKS). The solution includes infrastructure as code, backup scripts, migration automation, and monitoring.

Key Features

• Keycloak v26 Optimized: Specifically designed for Keycloak version 26 with enhanced features
• Production Ready: High availability with multi-AZ deployment and auto-scaling
• Security Focused: Network policies, secrets management, and security best practices
• Complete Automation: End-to-end automation from backup to deployment
• AWS Native: Leverages AWS services for optimal performance and reliability

🏗 Architecture

┌─────────────────────────────────────────────────────────────────┐
│                           AWS Cloud                             │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   EKS Cluster   │  │   RDS (PostgreSQL)  │  │  Application    │ │
│  │                 │  │                 │  │  Load Balancer  │ │
│  │  ┌───────────┐  │  │                 │  │                 │ │
│  │  │ Keycloak  │  │  │  Multi-AZ      │  │  SSL/TLS        │ │
│  │  │ v26 Pods  │  │  │  Encrypted     │  │  WAF Enabled    │ │
│  │  │ (3 replicas)│  │  │  Automated    │  │                 │ │
│  │  └───────────┘  │  │  Backups       │  │                 │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

📋 Prerequisites

Source Environment (Windows Server)

• Keycloak v26 installed and running
• Database access (PostgreSQL/MySQL/SQL Server)
• PowerShell 5.1 or later
• Administrative access to server

Target Environment (AWS)

• AWS CLI configured with appropriate permissions
• kubectl installed and configured
• Terraform v1.0 or later
• Helm v3.0 or later
• Access to create EKS clusters, RDS instances, VPCs

Required AWS Permissions

• EKS cluster management
• RDS instance creation and management
• VPC and networking configuration
• IAM roles and policies
• Application Load Balancer management
• S3 bucket access for backups

🚀 Quick Start

1. Backup Current Keycloak Instance

# Export realm data (Windows Server)
.\backup\export-keycloak-data.ps1 -KeycloakHome "C:\keycloak" -OutputDir "C:\backup" -AdminPassword "your-admin-password"

# Backup database
.\backup\backup-database.ps1 -DatabaseType postgresql -Server localhost -Database keycloak -Username keycloak -Password "db-password" -OutputDir "C:\backup"

2. Deploy AWS Infrastructure

# Initialize and deploy infrastructure
cd terraform
terraform init
terraform plan -var="environment=production" -var="cluster_name=keycloak-prod"
terraform apply

3. Deploy Keycloak on Kubernetes

# Apply Kubernetes manifests
kubectl apply -f kubernetes/namespace.yaml
kubectl apply -f kubernetes/secrets.yaml
kubectl apply -f kubernetes/configmap.yaml
kubectl apply -f kubernetes/deployment.yaml
kubectl apply -f kubernetes/service.yaml
kubectl apply -f kubernetes/ingress.yaml

4. Import Data

# Run migration script
./migration/import-data.sh -f /path/to/export.json -d /path/to/database.sql -n keycloak

📁 Project Structure

keycloak-migration/
├── README.md                    # This file
├── .github/
│   └── copilot-instructions.md  # GitHub Copilot guidelines
├── terraform/                  # Infrastructure as Code
│   ├── main.tf                 # Main Terraform configuration
│   ├── variables.tf            # Input variables
│   ├── outputs.tf              # Output values
│   └── terraform.tfvars.example # Example variables
├── kubernetes/                 # Kubernetes manifests
│   ├── namespace.yaml          # Namespace configuration
│   ├── secrets.yaml            # Secret management
│   ├── configmap.yaml          # Keycloak configuration
│   ├── deployment.yaml         # Keycloak deployment
│   ├── service.yaml            # Service definitions
│   └── ingress.yaml            # Ingress configuration
├── backup/                     # Windows backup scripts
│   ├── export-keycloak-data.ps1 # Realm export script
│   └── backup-database.ps1     # Database backup script
├── migration/                  # Migration automation
│   └── import-data.sh          # Data import script
├── docs/                       # Documentation
│   └── migration-guide.md      # Detailed migration guide
└── .vscode/                    # VS Code configuration
    └── tasks.json              # Build and deployment tasks

🔧 Configuration

Keycloak v26 Specific Features

The deployment includes optimizations for Keycloak v26:

• Enhanced Clustering: JGroups configuration for multi-pod coordination
• Recovery Codes: Support for v26 recovery code authentication
• Fine-grained Authorization: Enhanced authorization capabilities
• Performance Optimizations: JVM tuning and resource optimization
• Token Exchange: Advanced token exchange features

Environment Variables

Key configuration options in configmap.yaml:

KC_DB: postgres
KC_DB_URL: jdbc:postgresql://keycloak-db:5432/keycloak
KC_HOSTNAME_STRICT: false
KC_HTTP_ENABLED: true
KC_METRICS_ENABLED: true
KC_HEALTH_ENABLED: true
KC_CACHE_STACK: kubernetes

Security Configuration

• Network Policies: Restrict pod-to-pod communication
• RBAC: Role-based access control for Kubernetes resources
• Secrets Management: AWS Secrets Manager integration
• TLS Encryption: End-to-end encryption with cert-manager
• Security Headers: Comprehensive security headers in ingress

📊 Monitoring and Observability

Metrics Collection

• Prometheus metrics endpoint enabled
• Custom Keycloak v26 metrics
• Database connection monitoring
• Resource utilization tracking

Health Checks

• Kubernetes liveness and readiness probes
• Database connectivity checks
• External dependency monitoring

Logging

• Structured JSON logging
• Centralized log aggregation
• Error tracking and alerting

🔄 Migration Process

Phase 1: Preparation

1. Assessment: Evaluate current Keycloak configuration
2. Backup: Create comprehensive backups of data and configuration
3. Infrastructure: Deploy AWS infrastructure using Terraform
4. Validation: Verify infrastructure deployment

Phase 2: Migration

1. Database Migration: Restore database to AWS RDS
2. Application Deployment: Deploy Keycloak v26 on EKS
3. Data Import: Import realm configurations and user data
4. Validation: Comprehensive testing and validation

Phase 3: Cutover

1. DNS Update: Point domains to new AWS infrastructure
2. Monitoring: Activate comprehensive monitoring
3. Validation: Final end-to-end testing
4. Cleanup: Decommission old infrastructure

🛠 Troubleshooting

Common Issues

Database Connection Issues

# Check database connectivity
kubectl exec -n keycloak deployment/keycloak -- nc -zv keycloak-postgresql 5432

Pod Startup Issues

# Check pod logs
kubectl logs -n keycloak deployment/keycloak --previous
kubectl describe pod -n keycloak -l app.kubernetes.io/name=keycloak

Import Failures

# Validate import file format
jq '.["export-metadata"]["export-format-version"]' export.json

Performance Tuning

Memory Optimization

• Increase JVM heap size for large datasets
• Adjust database connection pool settings
• Configure horizontal pod autoscaling

Network Optimization

• Use Application Load Balancer with session affinity
• Configure proper readiness and liveness probes
• Optimize database query performance

🔒 Security Considerations

Data Protection

• Encryption at rest for RDS
• Encryption in transit for all communications
• Regular security updates and patches

Access Control

• Multi-factor authentication for admin access
• Role-based access control
• Audit logging for all administrative actions

Network Security

• Private subnets for database and application
• Web Application Firewall (WAF) protection
• DDoS protection via AWS Shield

📈 Scaling

Horizontal Scaling

• Horizontal Pod Autoscaler (HPA) configuration
• Cluster autoscaling for EKS nodes
• Database read replicas for performance

Vertical Scaling

• Vertical Pod Autoscaler (VPA) for resource optimization
• Instance type optimization
• Storage scaling for RDS

💰 Cost Optimization

Resource Optimization

• Right-sizing of EC2 instances
• Reserved instances for predictable workloads
• Spot instances for development environments

Monitoring Costs

• AWS Cost Explorer integration
• Resource tagging for cost allocation
• Automated cost alerts

🔄 Backup and Recovery

Automated Backups

• Daily RDS snapshots with 30-day retention
• Application configuration backups to S3
• Cross-region replication for disaster recovery

Recovery Procedures

• Point-in-time recovery for RDS
• Application state restoration
• Disaster recovery runbooks

📚 Additional Resources

• Keycloak v26 Documentation
• AWS EKS User Guide
• Terraform AWS Provider
• Kubernetes Documentation

🤝 Contributing

Contributions are welcome! Please read the contributing guidelines and submit pull requests for any improvements.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Support

For support and questions:

1. Check the troubleshooting section
2. Review the migration guide in /docs
3. Open an issue for bug reports or feature requests

---

Note: This migration solution is specifically optimized for Keycloak v26. Ensure compatibility before using with other versions.