{"id":30578308,"url":"https://github.com/cflarios/terraform-aws-vpn","last_synced_at":"2026-02-11T13:32:29.108Z","repository":{"id":307724957,"uuid":"1030429807","full_name":"cflarios/terraform-aws-vpn","owner":"cflarios","description":"Create your own VPN on AWS! Easy! ;)","archived":false,"fork":false,"pushed_at":"2025-08-04T02:52:50.000Z","size":106,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-29T05:56:43.871Z","etag":null,"topics":["ansible","aws","cicd","devops","terraform","wireguard"],"latest_commit_sha":null,"homepage":"","language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cflarios.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-01T16:14:49.000Z","updated_at":"2025-08-04T02:52:54.000Z","dependencies_parsed_at":"2025-08-01T21:37:35.511Z","dependency_job_id":"21997158-ac74-4787-870e-664ecf693dc7","html_url":"https://github.com/cflarios/terraform-aws-vpn","commit_stats":null,"previous_names":["cflarios/terraform-aws-vpn"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cflarios/terraform-aws-vpn","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cflarios%2Fterraform-aws-vpn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cflarios%2Fterraform-aws-vpn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cflarios%2Fterraform-aws-vpn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cflarios%2Fterraform-aws-vpn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cflarios","download_url":"https://codeload.github.com/cflarios/terraform-aws-vpn/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cflarios%2Fterraform-aws-vpn/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29333508,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-11T12:42:24.625Z","status":"ssl_error","status_checked_at":"2026-02-11T12:41:23.344Z","response_time":97,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible","aws","cicd","devops","terraform","wireguard"],"created_at":"2025-08-29T03:11:50.903Z","updated_at":"2026-02-11T13:32:29.082Z","avatar_url":"https://github.com/cflarios.png","language":"HCL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 AWS VPN Infrastructure - Terraform \u0026 Ansible\n\nAutomated infrastructure-as-code solution for deploying a temporary VPN server on AWS using Terraform for infrastructure and Ansible for configuration.\n\n## 🏗️ Architecture Overview\n\nThis project creates a complete VPN infrastructure with:\n- **Terraform**: Provisions AWS infrastructure (VPC, EC2, Security Groups)\n- **Ansible**: Configures WireGuard VPN using Docker containers\n- **GitHub Actions**: Automated deployment and destruction workflows\n- **AWS Parameter Store**: Secure storage for SSH keys and configurations\n- **S3 + DynamoDB**: Remote Terraform state management with locking\n\n## 📁 Project Structure\n\n```\n├── 📁 terraform/                    # Infrastructure as Code\n│   ├── 📁 modules/                 # Reusable Terraform modules\n│   │   ├── 📁 vpc/                # VPC and networking\n│   │   ├── 📁 security_group/     # Security group rules\n│   │   └── 📁 ec2/                # EC2 instance configuration\n│   ├── 📄 main.tf                 # Main Terraform configuration\n│   ├── 📄 backend.tf              # S3 backend configuration\n│   ├── 📄 variables.tf            # Input variables\n│   ├── 📄 outputs.tf              # Output values\n│   └── 📄 README.md               # Terraform documentation\n├── 📁 ansible/                     # Server Configuration\n│   ├── 📁 roles/                  # Ansible roles\n│   │   └── 📁 wireguard-docker/   # WireGuard Docker setup\n│   ├── 📁 group_vars/             # Group variables\n│   ├── 📄 site.yml                # Main playbook\n│   └── 📄 inventory.ini           # Inventory file (auto-generated)\n├── 📁 .github/workflows/           # CI/CD Automation\n│   ├── 📄 cicd_creation.yml       # Deploy infrastructure workflow\n│   ├── 📄 cicd_destroy.yml        # Destroy infrastructure workflow\n│   └── 📄 README.md               # Workflows documentation\n├── 📁 scripts/                     # Utility scripts\n│   ├── 📄 setup-backend.sh        # Backend setup script\n│   └── 📄 verify-setup.sh         # Configuration verification\n├── 📄 SETUP-BACKEND.md            # Setup documentation\n├── 📄 CHANGELOG.md                # Version history and release notes\n└── 📄 LICENSE                     # MIT License\n```\n\n## ✨ Features\n\n### 🏗️ Infrastructure (Terraform)\n- **VPC**: Small VPC in `us-east-1` region\n- **EC2**: Ubuntu 22.04 LTS instance (t3.micro by default)\n- **Security Groups**: \n  - Port 22 (SSH)\n  - Port 80 (HTTP)\n  - Port 443 (HTTPS)\n  - Port 8080 (WireGuard config server)\n  - Port 51820 (WireGuard VPN)\n- **Outputs**: Public IP address for easy access\n- **SSH Keys**: Automatically generated and stored securely\n\n### 🔧 Configuration (Ansible)\n- **Docker**: Automatic installation of Docker and docker-compose\n- **WireGuard**: Containerized using `linuxserver/wireguard` image\n- **Peer Generation**: Automatic client configuration generation with QR codes\n- **Web Interface**: Built-in web server for downloading configurations (port 8080)\n- **Firewall**: UFW firewall properly configured\n- **Security**: All configurations stored securely in AWS Parameter Store\n\n### 🚀 GitHub Actions Workflows\n- **Deploy Workflow**: Complete infrastructure deployment with one click\n- **Destroy Workflow**: Safe infrastructure destruction with confirmation\n- **Multi-Region Deploy**: Deploy VPN servers across multiple regions simultaneously\n- **Multi-Region Destroy**: Clean destruction of multi-region deployments\n- **Backend Management**: Automatic S3 backend creation and configuration\n- **State Persistence**: Terraform state safely stored in S3 with DynamoDB locking\n- **Debugging**: Comprehensive logging and state verification\n\n## � Quick Start\n\n### 📋 Prerequisites\n\n1. **AWS Account** with appropriate permissions\n2. **GitHub Repository** with this code\n3. **AWS Credentials** for GitHub Actions\n\n### 🔧 Setup (One-time only)\n\n1. **Configure GitHub Secrets**:\n   Go to your repository → Settings → Secrets and variables → Actions\n   \n   Add these secrets:\n   ```\n   AWS_ACCESS_KEY_ID=your_access_key\n   AWS_SECRET_ACCESS_KEY=your_secret_key\n   ```\n\n2. **Required AWS Permissions**:\n   Your AWS user needs these policies:\n   - `EC2FullAccess`\n   - `VPCFullAccess`\n   - `S3FullAccess`\n   - `DynamoDBFullAccess`\n   - `SSMFullAccess`\n   - `IAMReadOnlyAccess`\n\n### 🚀 Deploy VPN Infrastructure\n\n1. Go to **Actions** → **\"Deploy VPN Infrastructure\"**\n2. Click **\"Run workflow\"**\n3. Configure options:\n   - **Environment**: `dev`, `staging`, or `prod`\n   - **AWS Region**: Choose your preferred region (us-east-1, us-west-2, eu-west-1, etc.)\n   - **Instance Type**: `t3.micro` (cheapest), `t3.small`, `t3.medium`\n   - **WireGuard Peers**: Number of VPN clients (e.g., `3`)\n4. Click **\"Run workflow\"**\n5. ☕ Wait ~10 minutes for complete deployment\n\n### 📱 Access Your VPN\n\n1. **Web Interface**: Go to `http://INSTANCE_IP:8080`\n2. **Download Configurations**:\n   - `.conf` files for desktop clients (Windows, macOS, Linux)\n   - `.png` files (QR codes) for mobile apps\n3. **Import to WireGuard**: Use the official WireGuard app\n4. **Connect**: Start using your private VPN!\n\n### 🗑️ Destroy Infrastructure\n\n1. Go to **Actions** → **\"Destroy VPN Infrastructure\"**\n2. Click **\"Run workflow\"**\n3. **IMPORTANT**: Type exactly `DESTROY` in the confirmation field\n4. **Select the correct AWS region** (must match where it was deployed)\n5. Select the correct environment\n5. Click **\"Run workflow\"**\n6. ⏱️ Wait ~5 minutes for complete cleanup\n7. 💰 **$0 cost** - all resources destroyed\n\n## 🌍 Multi-Region Deployment\n\nFor global VPN coverage, you can deploy across multiple regions simultaneously:\n\n### 🚀 Deploy Multi-Region Network\n\n1. Go to **Actions** → **\"Deploy Multi-Region VPN Network\"**\n2. Click **\"Run workflow\"**\n3. Configure options:\n   - **Environment**: `multi-region` (or your preference)\n   - **Regions**: Comma-separated list (e.g., `us-east-1,eu-west-1,ap-southeast-1`)\n   - **Instance Type**: `t3.micro` (cheapest), `t3.small`, `t3.medium`\n   - **WireGuard Peers**: Number of VPN clients per region (e.g., `3`)\n4. Click **\"Run workflow\"**\n5. ☕ Wait ~15-20 minutes for global deployment\n\n### 🌐 Access Your Global VPN Network\n\n- Each region will have its own web interface: `http://REGION_IP:8080`\n- Download configurations from the region closest to you\n- Use different regions for different devices or backup connections\n- All servers operate independently\n\n### 🗑️ Destroy Multi-Region Network\n\n1. Go to **Actions** → **\"Destroy Multi-Region VPN Network\"**\n2. Click **\"Run workflow\"**\n3. **IMPORTANT**: Type exactly `DESTROY-ALL` in the confirmation field\n4. **Regions**: Type `all` to destroy all regions, or specific regions\n5. Click **\"Run workflow\"**\n6. ⏱️ Wait ~10-15 minutes for complete global cleanup\n7. 💰 **$0 cost** - all resources across all regions destroyed\n\n## 💰 Cost Management\n\n### 💡 Cost Estimates (Per Region)\n- **t3.micro**: ~$8.50/month (730 hours)\n- **t3.small**: ~$17/month (730 hours)\n- **Daily costs**: ~$0.28 (micro) / ~$0.55 (small)\n\n### 🌍 Multi-Region Cost Examples\n- **3 regions (t3.micro)**: ~$25.50/month (~$0.84/day)\n- **5 regions (t3.micro)**: ~$42.50/month (~$1.40/day)\n- **Global coverage**: Choose regions strategically to balance cost vs. coverage\n\n### 🛡️ Cost Protection\n- **Automatic Destruction**: Use workflows to avoid leaving resources running\n- **Instance Scheduling**: Consider running only when needed\n- **Regional Selection**: Deploy only in regions you need\n- **Monitoring**: AWS CloudWatch alerts for unexpected costs across all regions\n- **Budget Alerts**: Set up AWS Budget alerts for your account\n\n## 🔧 Advanced Configuration\n\n### 🎯 Custom Variables\nModify these in your workflow or Terraform variables:\n\n```yaml\n# In GitHub Actions workflow\naws_region: \"us-east-1\"          # us-east-1, us-west-2, eu-west-1, etc.\ninstance_type: \"t3.micro\"        # t3.micro, t3.small, t3.medium\nwireguard_peers: \"5\"             # Number of VPN clients\nenvironment: \"dev\"               # dev, staging, prod\n```\n\n### 🏗️ Local Development\n```bash\n# Clone repository\ngit clone \u003cyour-repo\u003e\ncd vpn\n\n# Setup backend (one-time)\n./scripts/setup-backend.sh\n\n# Deploy locally\ncd terraform\nterraform init -backend-config=\"bucket=YOUR_BUCKET\" \\\n               -backend-config=\"key=YOUR_KEY\" \\\n               -backend-config=\"region=us-east-1\"\nterraform plan\nterraform apply\n\n# Configure server\ncd ../ansible\nansible-playbook -i inventory.ini site.yml\n```\n\n## 🐛 Troubleshooting\n\n### 🔍 Common Issues\n\n#### \"No changes. No objects need to be destroyed\"\nThis usually means Terraform state issues:\n1. Check S3 bucket for state file\n2. Verify backend configuration\n3. Check debug output in Actions logs\n\n#### SSH Connection Failed\n1. Check security group allows port 22\n2. Verify SSH key is correctly configured\n3. Wait for instance to fully boot (2-3 minutes)\n\n#### WireGuard Not Working\n1. Check if Docker containers are running: `docker ps`\n2. Verify port 51820 is open in security group\n3. Check WireGuard logs: `docker logs wireguard`\n\n### 📊 Debug Information\nBoth workflows include comprehensive debugging:\n- Backend configuration verification\n- S3 state file checking\n- Security group validation\n- Instance status monitoring\n\n### 🆘 Support Resources\n- **AWS Documentation**: EC2, VPC, Security Groups\n- **WireGuard Documentation**: Official setup guides\n- **GitHub Actions**: Workflow debugging guides\n- **Terraform Documentation**: State management and backends\n\n## 🔒 Security Best Practices\n\n### 🛡️ Infrastructure Security\n- **SSH Keys**: Automatically generated and stored in Parameter Store\n- **Security Groups**: Minimal required ports only\n- **VPC**: Isolated network environment\n- **State Storage**: Encrypted S3 backend with DynamoDB locking\n\n### 🔐 Access Control\n- **GitHub Secrets**: Never expose AWS credentials in code\n- **Parameter Store**: Encrypted storage for sensitive configuration\n- **Time-limited**: Deploy only when needed, destroy when done\n- **Monitoring**: CloudTrail logging for all AWS activities\n\n### 🚨 Important Notes\n- **Never commit secrets** to Git repository\n- **Review costs** regularly in AWS console\n- **Monitor access logs** for unusual activity\n- **Keep workflows updated** for security patches\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create feature branch: `git checkout -b feature-name`\n3. Test your changes thoroughly\n4. Submit pull request with detailed description\n\n## 📄 License\n\nThis project is licensed under the MIT License. See [LICENSE](LICENSE) file for details.\n\n## 📞 Support\n\n- **Issues**: Use GitHub Issues for bugs and feature requests\n- **Discussions**: GitHub Discussions for questions and community support\n- **Documentation**: Check all README files in subdirectories\n- **Changelog**: See [CHANGELOG.md](./CHANGELOG.md) for version history and release notes\n\n## 📚 Additional Documentation\n\nFor detailed information about specific components, check these comprehensive guides:\n\n- **🏗️ [Terraform Documentation](./terraform/README.md)**: Infrastructure provisioning, modules, variables, and local development setup\n- **🐳 [Ansible Documentation](./ansible/README.md)**: WireGuard Docker configuration, client management, and troubleshooting\n- **🚀 [GitHub Actions Documentation](./.github/workflows/README.md)**: CI/CD workflows, deployment automation, cost management, and monitoring\n\nEach component has its own detailed README with:\n- Setup instructions\n- Configuration options\n- Troubleshooting guides\n- Best practices\n- Advanced usage examples\n\n---\n\n**⚡ Ready to deploy your VPN? Start with the Quick Start guide above!**\n\n---","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcflarios%2Fterraform-aws-vpn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcflarios%2Fterraform-aws-vpn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcflarios%2Fterraform-aws-vpn/lists"}