{"id":30889686,"url":"https://github.com/cbecerrae/aws-cloudformation-wireguard-vpn","last_synced_at":"2026-06-29T11:31:24.785Z","repository":{"id":310380102,"uuid":"1038816802","full_name":"cbecerrae/aws-cloudformation-wireguard-vpn","owner":"cbecerrae","description":"AWS CloudFormation template to deploy a fully configured WireGuard VPN server on AWS, ready for client connections, with support for seamless dynamic updates to client configurations.","archived":false,"fork":false,"pushed_at":"2025-08-29T21:09:12.000Z","size":36,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-08T16:59:45.142Z","etag":null,"topics":["aws","cloudformation","wireguard-vpn"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":false,"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/cbecerrae.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-15T21:50:20.000Z","updated_at":"2025-08-29T21:08:52.000Z","dependencies_parsed_at":"2025-08-17T19:22:04.005Z","dependency_job_id":"82c30672-3443-4498-9fb0-04560fd3122d","html_url":"https://github.com/cbecerrae/aws-cloudformation-wireguard-vpn","commit_stats":null,"previous_names":["cbecerrae/cloudformation-wireguard-vpn"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/cbecerrae/aws-cloudformation-wireguard-vpn","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbecerrae%2Faws-cloudformation-wireguard-vpn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbecerrae%2Faws-cloudformation-wireguard-vpn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbecerrae%2Faws-cloudformation-wireguard-vpn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbecerrae%2Faws-cloudformation-wireguard-vpn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cbecerrae","download_url":"https://codeload.github.com/cbecerrae/aws-cloudformation-wireguard-vpn/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbecerrae%2Faws-cloudformation-wireguard-vpn/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34925718,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-29T02:00:05.398Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["aws","cloudformation","wireguard-vpn"],"created_at":"2025-09-08T16:54:23.602Z","updated_at":"2026-06-29T11:31:24.765Z","avatar_url":"https://github.com/cbecerrae.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WireGuard VPN Deployment Using AWS CloudFormation\n\nThis CloudFormation template deploys a fully configured **WireGuard VPN server** on AWS, ready for secure client connections.\nIt provisions the required networking, IAM roles, security groups, an EC2 instance with WireGuard pre-installed, and generates client tunnel configuration dynamically using a **Custom Resource Lambda function**.\n\nTo add or remove clients, simply update the **ClientConfig** parameter via a direct CloudFormation stack update. Within a few minutes, `cfn-hup` detects the metadata change, runs `cfn-init` again, updates the WireGuard configuration, and restarts the service automatically—without the need to use **Session Manager**.\n\n## Parameters\n\nThe stack accepts several parameters to customize deployment:\n\n| Parameter           | Type                 | Default         | Description                                                                                                             | Required |\n| ------------------- | -------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------- | -------- |\n| **AdditionalCidrs** | String               | (empty)         | Optional comma-separated list of additional CIDR blocks to route through the VPN.                                       | No       |\n| **AttachElasticIp** | String               | `false`         | Whether to associate an Elastic IP with the EC2 instance (`true` or `false`).                                           | Yes      |\n| **ClientConfig**    | String               | (empty)         | Comma-separated list of clients in the format: `number:alias:PublicKey`. Example: `1:john:Base64Key,2:alice:Base64Key`. | Yes      |\n| **InstanceType**    | String               | `t2.micro`      | Amazon EC2 instance type used to provision the WireGuard server.                                                        | Yes      |\n| **Port**            | Number               | `51820`         | UDP port where the WireGuard server listens.                                                                            | Yes      |\n| **Prefix**          | String               | (empty)         | Optional prefix for resource names. If set, must end with `-`.                                                          | No       |\n| **PublicSubnetId**  | AWS::EC2::Subnet::Id | (empty)         | Public subnet within the VPC where the WireGuard EC2 instance will be deployed.                                         | Yes      |\n| **VpcId**           | AWS::EC2::VPC::Id    | (empty)         | The VPC where the WireGuard VPN will operate.                                                                           | Yes      |\n| **VpnCidr**         | String               | `100.64.0.0/16` | CIDR block for the VPN network. Must be between `/16` and `/24`.                                                        | Yes      |\n\n## Resources\n\nThe template provisions several AWS resources:\n\n### Core Infrastructure\n\n* **IAM Role \u0026 Instance Profile**: Allows the EC2 instance to use SSM and bootstrap itself with CloudFormation helper scripts.\n* **Security Group**: Opens the WireGuard UDP port (default `51820`) to all IPs.\n* **Elastic IP (Conditional)**: Attached to the instance if `AttachElasticIp=true`.\n\n### WaitCondition\n\n* **WaitHandle**: Provides a presigned URL for signaling completion.\n* **WaitCondition**: Ensures CloudFormation waits until the EC2 instance completes WireGuard configuration before proceeding. The setup script sends a **SUCCESS** signal including the server’s **public key**.\n\n### WireGuard EC2 Instance\n\n* Ubuntu 22.04 AMI (latest via SSM parameter).\n* Installs WireGuard, generates keys, sets up `wg0.conf`, applies client configurations, and enables IP forwarding.\n* Bootstrapped with `cfn-init` and auto-updates via `cfn-hup`.\n\n### Custom Resources\n\n* **Lambda Function**: Generates client tunnel configuration by combining the WireGuard server’s public key, public IP and port, VPN CIDR, and VPC routes.\n* **Custom::WireGuardTunnelConfig**: Calls the Lambda, which returns the client tunnel configuration in **Base64** format.\n\n## Outputs\n\nThe stack provides the following useful outputs:\n\n| Output                          | Description                                                       |\n| ------------------------------- | ------------------------------------------------------------------|\n| **WireGuardSecurityGroupId**    | Security Group ID attached to the WireGuard EC2 instance.         |\n| **WireGuardInstanceId**         | EC2 instance ID running the WireGuard server.                     |\n| **WireGuardPublicIp**           | Public IP (Elastic IP if attached, otherwise instance public IP). |\n| **WireGuardPrivateIp**          | Private IP of the EC2 instance.                                   |\n| **TestPing**                    | Command to ping the WireGuard private IP.                         |\n| **WireGuardTunnelConfig**       | Base64-encoded client tunnel configuration.                       |\n| **WireGuardPort**               | UDP port used by WireGuard.                                       |\n| **WireGuardVpcId**              | VPC where the VPN is deployed.                                    |\n| **WireGuardVpnCidr**            | CIDR block assigned to VPN.                                       |\n| **WireGuardConfigFile**         | Path to WireGuard configuration.                                  |\n| **WireGuardRestartCommand**     | Command to restart the WireGuard service.                         |\n| **WireGuardStatusCommand**      | Command to check WireGuard status.                                |\n| **WireGuardInstallationUrl**    | Official WireGuard installation documentation.                    |\n| **ClientTunnelConfigDecodeUrl** | Online Base64 decoder for the client tunnel configuration.        |\n\n## Notes\n\n* The **WaitCondition** ensures reliable provisioning by waiting for WireGuard setup before signaling stack success.\n* The **Custom Resource Lambda** provides dynamic tunnel configs without manual editing.\n* The **ClientConfig parameter** must include valid WireGuard public keys.\n* Modifications to the **ClientConfig** can be done directly via CloudFormation; `cfn-hup` applies changes automatically, updating WireGuard and restarting the service, all without the need to use **Session Manager**.\n\n## Updates / Client Management\n\nTo modify the WireGuard clients:\n\n1. Open the CloudFormation stack in the AWS Management Console (or use AWS CLI).\n2. Perform a **direct update** on the existing template and adjust the **ClientConfig** parameter with the new list of clients.\n\n   * Format: `number:alias:PublicKey` (comma-separated for multiple clients)\n   * Example: `1:john:Base64Key,2:alice:Base64Key,3:bob:Base64Key`\n3. Within a few minutes, the EC2 instance detects the change via **cfn-hup**, runs **cfn-init**, updates `/etc/wireguard/wg0.conf`, and restarts the WireGuard service.\n\nThis allows you to **add or remove clients easily** without the need to use **Session Manager**, keeping updates centralized and reproducible through CloudFormation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcbecerrae%2Faws-cloudformation-wireguard-vpn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcbecerrae%2Faws-cloudformation-wireguard-vpn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcbecerrae%2Faws-cloudformation-wireguard-vpn/lists"}