ip allowlist (#14)

* feat: allowlist

* version

Author: levkk

Chart.yaml

@@ -2,5 +2,5 @@ apiVersion: v2
 name: pgdog-control
 description: PgDog Control
 type: application
-version: 0.2.9
+version: 0.2.10
 appVersion: "v2026-06-09"

README.md

@@ -461,6 +461,33 @@ The control plane reads its runtime configuration from a TOML file at `/etc/pgdo
 
 Each subsection below covers one TOML section.
 
+### PgDog API IP Allowlist
+
+`control.config.api.pgdog.ip_allowlist` adds an optional source-IP gate in front of the PgDog machine API endpoints under `/api/v2/*`. It is disabled by default. When enabled, the control plane accepts those requests only when the direct TCP peer address falls inside one of the configured CIDR ranges:
+
+```yaml
+control:
+  config:
+    api:
+      pgdog:
+        ip_allowlist:
+          enabled: true
+          allowed_cidrs:
+            - 10.0.0.0/8
+            - 172.16.0.0/12
+            - 192.168.0.0/16
+            - 127.0.0.0/8
+            - ::1/128
+            - fc00::/7
+```
+
+If `allowed_cidrs` is omitted, the control plane defaults to private IPv4 ranges, IPv4/IPv6 loopback, and IPv6 ULA. The check intentionally uses the direct TCP peer address and ignores forwarded headers such as `X-Forwarded-For`; configure the CIDRs for the address the control plane actually sees from your ingress, load balancer, sidecar, or PgDog caller.
+
+| Option | Description |
+|-|-|
+| `api.pgdog.ip_allowlist.enabled` | Enables source-IP checks for `/api/v2/*` PgDog endpoints (bool, default `false`). |
+| `api.pgdog.ip_allowlist.allowed_cidrs` | CIDR ranges allowed to call `/api/v2/*`. Invalid CIDRs cause protected requests to be rejected until the config is fixed (list of strings, default private IPv4 ranges, loopback, and IPv6 ULA). |
+
 ### Authentication
 
 `control.config.auth` wires up the OAuth-backed login flow for the dashboard. GitHub and Google are supported and can be enabled side by side. At least one needs to be configured, or the dashboard will be **accessible by anyone with the URL**:

templates/configmap.yaml

@@ -18,6 +18,20 @@ metadata:
     {{- include "pgdog-control.labels" . | nindent 4 }}
 data:
   control.toml: |
+    {{- with $config.api }}
+    {{- with .pgdog }}
+    {{- with .ip_allowlist }}
+    [api.pgdog.ip_allowlist]
+    {{- if hasKey . "enabled" }}
+    enabled = {{ .enabled }}
+    {{- end }}
+    {{- if hasKey . "allowed_cidrs" }}
+    allowed_cidrs = [{{ range $i, $cidr := .allowed_cidrs }}{{ if $i }}, {{ end }}{{ $cidr | quote }}{{ end }}]
+    {{- end }}
+    {{- end }}
+    {{- end }}
+    {{- end }}
+
     {{- with $config.rds }}
     [rds]
     {{- with .refresh_interval_secs }}

values.yaml

@@ -71,6 +71,20 @@ control:
   # unset falls back to the Rust-side default. Field names match the TOML
   # keys (snake_case) so values are passed through verbatim.
   config:
+    api: {}
+      # pgdog:
+      #   ip_allowlist:
+      #     # When enabled, restricts /api/v2/* PgDog API endpoints by the
+      #     # direct TCP peer IP address. Forwarded headers are ignored.
+      #     enabled: false
+      #     # Defaults, when omitted:
+      #     # - 10.0.0.0/8
+      #     # - 172.16.0.0/12
+      #     # - 192.168.0.0/16
+      #     # - 127.0.0.0/8
+      #     # - ::1/128
+      #     # - fc00::/7
+      #     allowed_cidrs: []
     rds: {}
       # refresh_interval_secs: 60
       # Experimental: do not enable in production yet.