|
| 1 | +# proxy power button |
| 2 | + |
| 3 | +A secure reverse proxy that automatically powers on Google Compute Engine instances when traffic arrives. |
| 4 | + |
| 5 | +This service is designed to run on **Google Cloud Run as an ingress layer** in front of your full application stack running on Google Compute Engine. When traffic hits your Cloud Run endpoint, PPB automatically powers on the target GCE VM (if needed) and proxies the request through. This architecture allows you to run complete application stacks on cost-effective VMs while only paying for Cloud Run when traffic actually arrives. |
| 6 | + |
| 7 | +## Architecture |
| 8 | + |
| 9 | +``` |
| 10 | +Internet → Cloud Run (PPB) → Google Compute Engine (Full App Stack) |
| 11 | +``` |
| 12 | + |
| 13 | +- **Cloud Run**: Runs PPB as serverless ingress, scales to zero when no traffic |
| 14 | +- **GCE VM**: Runs your complete application (web server, database, etc.), can power off when idle |
| 15 | +- **PPB**: Powers on the VM when requests arrive, proxies traffic through with IP authorization |
| 16 | + |
| 17 | +## Cloud Run Behavior |
| 18 | + |
| 19 | +PPB runs as a reverse proxy with intelligent rate limiting: |
| 20 | + |
| 21 | +1. **Request handling**: Each authorized request attempts to power on the target machine if needed |
| 22 | +2. **Rate limiting**: Power-on attempts are rate limited with a configurable cooldown period (default 30s) |
| 23 | +3. **API protection**: Prevents hammering Google Cloud APIs during high traffic periods |
| 24 | +4. **IP Security**: Only requests from allowed IP ranges can trigger machine power-on attempts |
| 25 | + |
| 26 | +This approach balances responsiveness with API efficiency - machines get powered on when traffic arrives, but multiple requests don't spam the Google Cloud APIs. |
| 27 | + |
| 28 | +## Use Case Examples |
| 29 | + |
| 30 | +- **Full Stack Applications**: Run complete LAMP/MEAN/Django stacks on GCE VMs with PPB as Cloud Run ingress |
| 31 | +- **Development Environments**: Keep expensive GPU/high-memory dev instances off until developers access them |
| 32 | +- **Legacy Applications**: Modernize access to monolithic applications that need full VM environments |
| 33 | +- **Cost Optimization**: Run databases, processing servers, or complete application environments that can idle |
| 34 | +- **Multi-service Backends**: Power on VMs running docker-compose stacks, Kubernetes clusters, or complex service meshes |
| 35 | + |
| 36 | +## Config |
| 37 | + |
| 38 | +Currently, only backend services running on Google Compute Engine are supported. |
| 39 | + |
| 40 | +```yaml |
| 41 | +type: google_compute_engine |
| 42 | +port: 80 |
| 43 | +scheme: http |
| 44 | +allowedIps: |
| 45 | + - 127.0.0.1/32 # localhost |
| 46 | + - 10.0.0.0/8 # private networks |
| 47 | + - 172.16.0.0/12 |
| 48 | + - 192.168.0.0/16 |
| 49 | +ipForwardedHeader: X-Forwarded-For # header to check for real client IP |
| 50 | +ipDepth: 0 # depth in X-Forwarded-For chain |
| 51 | +powerOnCooldown: 30 # seconds between power-on attempts (default: 30) |
| 52 | +# Optional proxy timeout configuration (defaults shown) |
| 53 | +proxyTimeouts: |
| 54 | + dialTimeout: 120 # Connection dial timeout in seconds |
| 55 | + keepAlive: 120 # TCP keep-alive timeout in seconds |
| 56 | + idleConnTimeout: 90 # Idle connection timeout in seconds |
| 57 | + tlsHandshakeTimeout: 10 # TLS handshake timeout in seconds |
| 58 | + expectContinueTimeout: 1 # Expect: 100-continue timeout in seconds |
| 59 | + maxIdleConns: 100 # Maximum idle connections |
| 60 | +machineMetadata: |
| 61 | + project_id: foo |
| 62 | + zone: us-central1-a |
| 63 | + name: my-compute-instance-name |
| 64 | + usePrivateIp: false # true for VPC-native setups |
| 65 | +``` |
| 66 | +
|
| 67 | +### Configuration Reference |
| 68 | +
|
| 69 | +| Field | Type | Required | Default | Description | |
| 70 | +|-------|------|----------|---------|-------------| |
| 71 | +| `type` | string | ✅ | - | Backend type, currently only `google_compute_engine` | |
| 72 | +| `port` | int | ✅ | - | Port on target machine to proxy to | |
| 73 | +| `scheme` | string | ✅ | - | Protocol scheme (`http` or `https`) | |
| 74 | +| `allowedIps` | []string | ✅ | - | CIDR ranges of IPs allowed to access the proxy | |
| 75 | +| `ipForwardedHeader` | string | ❌ | `""` | Header to check for real client IP (e.g., `X-Forwarded-For`) | |
| 76 | +| `ipDepth` | int | ❌ | `0` | Depth in forwarded header chain (0 = rightmost IP) | |
| 77 | +| `powerOnCooldown` | int | ❌ | `30` | Seconds between power-on attempts (rate limiting) | |
| 78 | +| `proxyTimeouts.dialTimeout` | int | ❌ | `120` | Connection dial timeout in seconds | |
| 79 | +| `proxyTimeouts.keepAlive` | int | ❌ | `120` | TCP keep-alive timeout in seconds | |
| 80 | +| `proxyTimeouts.idleConnTimeout` | int | ❌ | `90` | Idle connection timeout in seconds | |
| 81 | +| `proxyTimeouts.tlsHandshakeTimeout` | int | ❌ | `10` | TLS handshake timeout in seconds | |
| 82 | +| `proxyTimeouts.expectContinueTimeout` | int | ❌ | `1` | Expect: 100-continue timeout in seconds | |
| 83 | +| `proxyTimeouts.maxIdleConns` | int | ❌ | `100` | Maximum number of idle connections | |
| 84 | +| `machineMetadata.project_id` | string | ✅ | - | Google Cloud project ID | |
| 85 | +| `machineMetadata.zone` | string | ✅ | - | GCE zone (e.g., `us-central1-a`) | |
| 86 | +| `machineMetadata.name` | string | ✅ | - | GCE instance name | |
| 87 | +| `machineMetadata.usePrivateIp` | bool | ❌ | `false` | Use private IP for VPC-native setups | |
| 88 | + |
| 89 | +Deploy this service on **Google Cloud Run** as the public endpoint for your application. Configure the `machineMetadata` to point to your GCE VM running the actual application stack. Only requests from allowed IPs will power on the VM and be proxied through. |
| 90 | + |
| 91 | +### Environment Variables |
| 92 | + |
| 93 | +PPB also supports these environment variables for runtime configuration: |
| 94 | + |
| 95 | +| Variable | Description | Default | |
| 96 | +|----------|-------------|---------| |
| 97 | +| `PPB_CONFIG_PATH` | Path to YAML configuration file | Required | |
| 98 | +| `LOG_LEVEL` | Log level (`DEBUG`, `INFO`, `WARN`, `ERROR`) | `INFO` | |
| 99 | +| `GOOGLE_APPLICATION_CREDENTIALS` | Path to service account JSON file | Uses default credentials | |
| 100 | + |
| 101 | +## IAM Permissions |
| 102 | + |
| 103 | +The Google Service Account (GSA) used by Cloud Run needs a custom IAM role with minimal permissions to control the target compute instance. |
| 104 | + |
| 105 | +### Custom Role Definition |
| 106 | + |
| 107 | +Create a custom role with only the required permissions: |
| 108 | + |
| 109 | +```hcl |
| 110 | +resource "google_project_iam_custom_role" "compute-start" { |
| 111 | + project = var.project |
| 112 | +
|
| 113 | + role_id = "startVM" |
| 114 | + title = "Start Compute Instance" |
| 115 | + description = "Minimal permissions for PPB to control compute instances" |
| 116 | + permissions = [ |
| 117 | + "compute.instances.start", |
| 118 | + "compute.instances.resume", |
| 119 | + "compute.instances.get" |
| 120 | + ] |
| 121 | +} |
| 122 | +``` |
| 123 | + |
| 124 | +### Assign Role to Service Account |
| 125 | + |
| 126 | +```hcl |
| 127 | +resource "google_project_iam_member" "ppb_service_account" { |
| 128 | + project = var.project |
| 129 | + role = google_project_iam_custom_role.compute-start.name |
| 130 | + member = "serviceAccount:${var.service_account_email}" |
| 131 | +} |
| 132 | +``` |
| 133 | + |
| 134 | +### CLI Alternative |
| 135 | + |
| 136 | +```bash |
| 137 | +gcloud iam roles create startVM \ |
| 138 | + --project=PROJECT_ID \ |
| 139 | + --title="Start Compute Instance" \ |
| 140 | + --description="Minimal permissions for PPB to control compute instances" \ |
| 141 | + --permissions="compute.instances.start,compute.instances.resume,compute.instances.get" |
| 142 | +
|
| 143 | +gcloud projects add-iam-policy-binding PROJECT_ID \ |
| 144 | + --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \ |
| 145 | + --role="projects/PROJECT_ID/roles/startVM" |
| 146 | +``` |
| 147 | + |
| 148 | +## Usage |
| 149 | + |
| 150 | +### Local development |
| 151 | + |
| 152 | +```bash |
| 153 | +docker build -t ghcr.io/libops/ppb:development . |
| 154 | +docker run \ |
| 155 | + -p 8080:8080 \ |
| 156 | + -v $GOOGLE_APPLICATION_CREDENTIALS:/app/svc.json:ro \ |
| 157 | + -v ./ppb.yaml:/app/ppb.yaml:ro \ |
| 158 | + --env PPB_CONFIG_PATH=/app/ppb.yaml \ |
| 159 | + --env GOOGLE_APPLICATION_CREDENTIALS=/app/svc.json \ |
| 160 | + --env PRIVATE_IP=false \ |
| 161 | + --env LOG_LEVEL=DEBUG \ |
| 162 | + ghcr.io/libops/ppb:development |
| 163 | +``` |
| 164 | + |
| 165 | +PPB will act as a local ingress proxy to your GCE VM. Visit http://localhost:8080 and PPB will power on your target VM (if needed) then proxy your requests through to the application running on the VM. |
| 166 | + |
| 167 | +### Google Cloud Run Deployment |
| 168 | + |
| 169 | +Deploy PPB to Cloud Run and configure it as your application's public endpoint: |
| 170 | + |
| 171 | +```bash |
| 172 | +gcloud run deploy ppb \ |
| 173 | + --image=ghcr.io/libops/ppb:latest \ |
| 174 | + --set-env-vars="PPB_CONFIG_PATH=/app/ppb.yaml" \ |
| 175 | + --service-account=your-ppb-service-account@project.iam.gserviceaccount.com \ |
| 176 | + --allow-unauthenticated \ |
| 177 | + --port=8080 \ |
| 178 | + --region=us-central1 |
| 179 | +``` |
| 180 | + |
| 181 | +Your users will access `https://ppb-xxx-uc.a.run.app` which automatically powers on your GCE VM and proxies traffic through. |
0 commit comments